A-Shell Consolidated Reference

Updated February 2021; see History

xcall MIAMEX, MX_GETOFD, path, filter, title, flags {,defext, fname, type}

(Windows/ATE only) MX_GETOFD (MIAMEX 95) displays the standard Windows open file or save file dialog. It can only take place on a GUI-enabled client, either ATE or A-Shell/Windows. Note that the routine can be called with just two parameters; see History.

This function has both a subroutine and a print tab implementation.

Parameters

path  (String, up to a maximum of 4096 bytes)  [in/out]

On input, must contain the default filespec or the default directory, fully qualified, in AMOS or Windows notation. See Comments.

On return, it will contain the full filespec (in Windows notation) of the selected file(s). If more than one file was selected (see OFN_ALLOWMULTISELECT in flags), the individual filespecs will be separated by chr(10) characters, and all but the first filespec will be stripped down to just the file name and extension, since they will all be in the same directory.

filter  [in]

is a set of pairs of strings, concatenated all together using pipes ("|") for delimiters, determining which files will display in the dialog box. The first string in each pair is descriptive, and will display in the "Files of Type" area of the dialog box. The second string in each pair is a wildcard specification for that kind of file. If you have more than one wildcard spec for a particular descriptive name, then separate them with semicolons. For example:

FILTER="Data files|*.DAT|Text files|*.TXT; *.LST"

Note that the "Files of Type" control is actually a drop-down box and that "Data files" will show as the initial choice, and "Text Files" will be the next choice in the list. If you want them all appear together, then just specify one pair of strings, such as:

FILTER="Image Files (*.pcx, *.jpg, *.bmp)|*.pcx; *.jpg; *.bmp"

Also note: do not include any spaces on either side of the | delimiter characters lest they be confused with the pattern, causing a failure to match any files.

title  (String)  [in]

may be set to the desired title of the dialog box. The default is "Open". This is the main difference between the File Open and File Save versions of the dialog box. See type parameter.

flags  (Num)  [in/out]

May be set to any combination of the options shown below.

Note that since the parameter may be updated on return from the function (see OFN_EXTENSIONDIFFERENT and OFN_NOREADONLYRETURN), you'll have to use an actual variable for the flags parameter if you want to be so advised. Otherwise you can just specify an expression consisting of the literal flags, e.g. OFN_PATHMUSTEXIST+OFN_FILEMUSTEXIST.

Note also that MX_GETOFD is primarily a wrapper for the Windows API Function GetOpenFileName() which seems to support additional flags with each new version of Windows. Consult the Microsoft documentation for more complete and up-to-date information on available flags.

Hex-Decimal Values

 

defext  (String)  [in]

may specify the default file extension. Do not include the period. If specified and the user types a filename with no extension, this will be appended to the returned path and fname parameters.

fname  (String)  [out]

is an optional convenience that will return just the filename and extension, without the rest of the path, saving you from having to parse it out of the path string. Note, however, that it is not guaranteed to be in the directory you initially specified. Parameter is ignored if OFN_ALLOWMULTISELECT is set. Maximum length is approximately 256.

type  (Num)  [in]

If specified and set to 1, the main button will say "Save" rather than "Open". This and the title are the main differences between an Open dialog and a Save dialog.

Comments

Note that if the initial path or directory is in the form of a drive letter and colon with no trailing slash (e.g. "C:"), MX_GETOFD automatically appends "\" to avoid confusion. Such ambiguous specs are otherwise likely to be misinterpreted by A-Shell and/or Windows.

If there is an error in the format of the parameters, such that the dialog fails to display, A-Shell will open the System Messages window and display a short message with the internal Windows error number; see descriptions in the following table.

 

 

See Also

History

2021 February A-Shell 6.5.1699:  Support SBR=GETOFD_NOCOM to revert to old implementation

2021 February, A-Shell 6.5.1698:  add new flag OFN_FORCEPREVIEWPANEON as part of update to File Open / File Save dialog. The OFN_EXPLORER option is now essentially meaningless—i.e., it is always on.

2016 March, A-Shell 6.2.1425:  minimum number of parameters has been reduced from five to two, allowing you to call it with just xcall MIAMEX, MX_GETOFD, PATH$

2013 July, A-Shell 6.1.1355:  filenames containing commas are now quoted; previously they were not, which almost certainly led to incorrect parsing of the response

2013 July: 2009 October, A-Shell 5.1.164:  Append "\" when needed