GuiFile()

Presents a File Dialog to obtain one or more filenames from the user. Can also present a Directory dialog to pick out a directory.

error = GuiFile(NameVar, Options, Title, Extensions, InitialDir)


Args

NameVar is the name of the REXX variable where the filename is initially retrieved, and later stored. The File Dialog will initially open with this filename in the "File name" ENTRY, unless NameVar is set to an empty string (in which case the ENTRY is blank). Note that NameVar could be set to a fully-qualified name. If opening the Directory dialog instead, then NameVar contains the directory that is initially selected when the dialog opens, and where the chosen directory is returned.

Options depends upon whether you're opening a File or Directory dialog. In order to open the Directory dialog, you must specify at least the 'BROWSE' option.

For the File dialog, Options can be any or all of the following, each separated by a | character:

Option Meaning
'MULTIPLE' The user can choose more than one filename, by holding down either the SHIFT or CTRL keys while clicking upon names, or typing multiple names into the "File name" ENTRY each separated by a space. See notes below for details.
'NEW' If the user types (into the dialog's "File name" ENTRY) the name of a filename that doesn't actually exist yet, and clicks on the "Ok" button, then an empty file (ie, 0 bytes) is created with that name.
'EXISTING' The names of only existing files are returned. The user is not allowed to type in the name of a file that doesn't exist yet.
'HIDEREADONLY' The dialog's "Read-only" CHECK button is not displayed. When displayed, the user has the option of filtering out the names of files that are read-only. Normally, you would set this flag only if you didn't care whether a file he selected was read-only.
'DIR' When a user selects his filename choice, the file dialog normally sets the current directory to the directory containing that file. Setting this flag prevents that behavior, and the file dialog does not change the current directory. Note that GuiFile() always returns a filename with a fully-qualified path regardless.
'OVERWRITE' If the user chooses the name of an existing file, he is automatically presented with a message box asking if he wishes to overwrite this file. Only if he answers "yes" will GuiFile() return that filename.
'PATH' If the user types in a fully-qualified name (into the "File name" ENTRY), then the path (ie, directory containing that file) must exist.
'SHORTCUT' If the user selects a .lnk file (ie, a shortcut), then the file dialog normally returns the name of the file that the shortcut references. If you set this flag, then the dialog instead returns the name of the shortcut itself. You would set this flag only if you wanted to directly manipulate the settings for a shortcut.
'NORECENT' Doesn't add the chosen file's name to the user's most recently used documents menu.
'SHOWSYS' Shows system and hidden files.
'NONET' Hides the Network button.
'NOTEST' Specifies that the File Save dialog does not test whether the chosen destination drive is writeable. This option should be specified if your script intends to save a file on a create-nonmodify network share. When you specify this option, REXX GUI does not check for write protection, a full disk, an open drive door, or network protection. Note that your script must perform file operations carefully, because a file can't be reopened once it is closed.
'SAVE' Save operation, as opposed to "Open". This is only needed if you don't supply a Title arg.

For the Directory dialog, Options can be any or all of the following, each separated by a | character:

Option Meaning
'BROWSE' Indicates that the Directory (rather than the File) dialog is to be presented. This option must be specified.
'NEWFOLDER' Adds an ENTRY named 'New Folder' into which the user can type the name of a folder that doesn't exist. Without NEWFOLDER, the Directory dialog is limited to selecting only an existing directory.
'DRIVES' The Directory dialog is limited to displaying only those items inside of "My Computer". (ie, The user is limited to browsing local drives).
'NETWORK' The Directory dialog browses all network drives.
'NETHOOD' The Directory dialog is limited to displaying only those items inside of the current user's "Network Neighborhood" hierarchy.
'CONTROL' The Directory dialog is limited to displaying only those items inside of Control Panel.
'PRINTERS' The Directory dialog is limited to displaying only those items inside of the Printers folder.
'PROGRAMFILES' The Directory dialog is limited to displaying only those items inside of the Program Files folder.
'COMMON' The Directory dialog is limited to displaying only those items inside of the Common sub-folder within the Program Files folder.
'MENU' The Directory dialog is limited to displaying only those items inside of the current user's Start menu. ALLMENU instead selects all users.
'PROGRAMS' The Directory dialog is limited to displaying only those directories inside of the current user's Start -> Program menu. ALLPROGRAMS instead selects all users.
'DESKTOP' The Directory dialog is limited to displaying only those items on the Desktop.
'USRDESKTOP' The Directory dialog is limited to displaying only those items on the current user's Desktop.
'INTERNET' The Directory dialog is limited to displaying only those items inside of the Internet Explorer folder on the desktop.
'PERSONAL' The Directory dialog is limited to displaying only those items inside of the current user's personal (ie, "My Documents") folder. ALLDOCS instead selects all users (Shared Documents).
'MYMUSIC' The Directory dialog is limited to displaying only those items inside of the current user's My Music folder. ALLMUSIC instead selects all users.
'MYVIDEO' The Directory dialog is limited to displaying only those items inside of the current user's My Videos folder. ALLVIDEO instead selects all users.
'MYPICS' The Directory dialog is limited to displaying only those items inside of the current user's My Pictures folder. ALLPICS instead selects all users.
'SENDTO' The Directory dialog is limited to displaying only those items inside of the current user's Send Tofolder.
'USRAPPDATA' The Directory dialog is limited to displaying only those items inside of the current user's Application Data folder. ALLAPPDATA instead selects all users. APPDATA instead selects general Application Data, including network.
'CONNECTIONS' The Directory dialog is limited to displaying only those items inside of the Network and Dial-up Connections folder.
'WINDOWS' The Directory dialog is limited to displaying only those items inside of the Windows folder.
'SYSTEM' The Directory dialog is limited to displaying only those items inside of the System folder.
'RECYCLE' The Directory dialog is limited to displaying only those items inside of the Recycle Bin.
'FAVORITES' The Directory dialog is limited to displaying only those items inside of the current user's Favorites folder.
'IECOOKIES' The Directory dialog is limited to displaying only those items inside of Internet Explorer's Cookies folder.
'IEHISTORY' The Directory dialog is limited to displaying only those items inside of Internet Explorer's History folder.
'IECACHE' The Directory dialog is limited to displaying only those items inside of Internet Explorer's Cache folder.

If Options is omitted, it defaults to 'HIDEREADONLY|EXISTING|PATH|DIR'. If an empty string, it is none of the above.

Title is the text displayed in the Dialog's titlebar. If omitted, it defaults to "Open" or "Save as" (depending upon whether the 'SAVE' flag is set) for File dialog, or no title for the Directory dialog.

Extensions is used only with the File Dialog, and may be omitted for the Directory dialog. They are the list of extensions to match. This list appears in the File Dialog's "Files of type" DROP control. The user can select one of the extensions, and then only filenames that end with the chosen extension are displayed for selection.

If Extensions is omitted, then there is no filtering of filenames, and all files in the selected directory are displayed.

InitialDir is the initial directory where the File dialog opens. If omitted, then the dialog opens in the current directory. For the Directory dialog, InitialDir is the directory initially placed into the 'New Folder' ENTRY. If omitted, then the 'New Folder' ENTRY is blank.


Returns

An empty string if successful, or an error message if an error or the "Cancel" button was clicked. The chosen filename(s) or directory is also returned in the variable named by NameVar if successful.


Notes

If the user clicks upon the "Cancel" button, then the error message returned is "Cancel". Reginald will either return this error message, or the error number of 100, or raise a condition, depending upon how you how set the GuiErr variable.

If an OK selection, the filename is returned in the REXX variable specified by the NameVar arg. This will be a fully qualified filename or directory name (ie, with the drive and parent directories too). If the 'MULTIPLE' flag was not set, then the filename is simply returned in the variable with that name. Otherwise, if 'MULTIPLE' is set, then the compound variable with a tail name of ".0" specifies how many filenames were chosen, and variables with tail names starting at 1 contain each of those names. For example, if NameVar is "MYNAME", and he chooses 3 names, then NameVar.0 = 3, and NameVar.1, NameVar.2, and NameVar.3 contain those 3 names.

The format for Extensions is as follows:

Item 1's text that appears under "Files of type".

'|' character
Item 1's extensions, each separated by a semi-colon.
'|' character
Item 2's text that appears under "Files of type".
'|' character
Item 2's extensions, each separated by a semi-colon.
etc.
For example, let's say that you want to add two items to "Files of type". Item 1 will be called "REXX files (*.rex, *.rexx)". When the user selects this item, you want to display only those filenames that end with either the extension .rex or .rexx. You wish to have a second item called "All files (*.*)". When the user selects this item, all filenames, regardless of extension, will be displayed. Your extensions string should look like this:

'REXX files (*.rex, *.rexx) | *.rex;*.rexx | All files (*.*) | *.*'

If you specify an Extensions string, then when the GuiFile returns, the GuiSignal variable will be set a number representing which extension was selected, where 1 would be for REXX files, and 2 would be for All files, above.

It doesn't matter in what order you specify the Options, but each must be separated from another using a | character. You may also use extra spaces inbetween each option.

GuiFile() may be called without any other GUI windows open.


Examples

/* This gets a filename selection and checks for 'Ok'. */

/* Store the filename in the variable FN. */
FN = ''

/* Present the dialog */
err = GuiFile('FN', , 'This is the title')

/* Check for success. */
IF err = '' THEN DO
   /* Do some operation with the filename in FN */
END

/* This gets a Directory selection and checks for 'Ok'. */

/* Store the directory in the variable FN. */
FN = ''

/* Present the dialog */
err = GuiFile('FN', 'BROWSE|DRIVES', 'This is the title')

/* Check for success. */
IF err = '' THEN DO
   /* Do some operation with the directory name in FN */
END