Select document

version 2004

Select document (directory; fileTypes; title; options{; selected}) String

The Select document command displays a standard open document dialog box which allows the user to set one or more files and returns the name and/or full access path of the selected file(s).

The directory parameter indicates the folder whose contents are initially displayed in the open document dialog box. You can pass three types of values:

• a text containing the full access path of the folder to display.

• an empty string ("") to display the default user folder for the current opeerating system ("My documents" under Windows, "Documents" under Mac OS).

• a number of the memorized access path (from 1 to 32000) to display the associated folder.

As such, you can store in memory the access path of the folder opened when the user clicked the selection button, in other words, the folder selected by the user. During the first call of an arbitrary number (for example, 5) the command displays the default user folder of the operating system (equivalent of passing an empty string). The user could also browse folders on the hard disk. When the user clicks on the selection button, the access path is memorized and associated with number 5. During future calls to number 5, the memorized access path will be used by default. If a new location is selected, path number 5 is updated.

This mechanism lets you memorize up to 32,000 access paths. Under Windows, each path is kept for the session only. Under Mac OS, the paths are kept by the system and remain stored from one session to the next.

Pass the type(s) of file(s) that can be selected in the open file dialog box in the fileTypes parameter. You can pass a list of several types separated by a ; (semi-colon). For each type defined, a row will be added in the type choice menu of the dialog box.

Under Mac OS, you can pass either a standard Mac OS type (TEXT, APPL, etc.), or a UTI (Uniform Type Identifier) type. UTI types have been defined by Apple in order to meet requirements concerning the standardization of file types. For example, "public.text" is the UTI type of text type files. For more information about UTIs, please refer to the following address: http://developer.apple.com/documentation/Carbon/Conceptual/understanding_utis/index.html.

Under Windows, you can also pass a standard Mac OS type file — 4th Dimension performs the conversion internally — or the file extensions (.txt, .exe, etc.). Please note that under Windows, the user can "force" the display of all document types by entering *.* in the dialog box. However, in this case, 4th Dimension will perform an additional verification of the types of files selected: if the user selects an unauthorized file type, the command returns an error.

If you do not want to restrict the files displayed to one or more types, pass the "*" (star) or ".*" string in fileTypes.

Pass the label that must appear in the dialog box in the title parameter. By default, if you pass an empty string, the label "Open" is displayed.

The options parameter allows you to specify advanced functions that are allowed in an open file dialog box. 4th Dimension provides the following pre-defined constants in the "System Documents" theme:

You can pass one or a combination of constants.

• Multiple files: Authorizes the simultaneous selection of several files using the key combinations Shift+click (adjacent selection) and Ctrl+click (Windows) or Command+click (Mac OS). In this case, the selected parameter, if passed, contains the list of all selected files. By default, if this constant is not used, the command will not allow the selection of multiple files.

• Package open (Mac OS only): Authorizes the opening of packages and the viewing of their contents. By default, if this constant is not used, the command will not allow the opening of packages.

• Package selection (Mac OS only): Authorizes the selection of packages as entities. By default, if this constant is not used, the command will not allow the selection of software packages as such. In this case, it is impossible to open or select a software package (even if the Package open constant is passed.

• Alias selection: Authorizes the selection of shortcuts (Windows) or aliases (Mac OS) as document.

By default, if this constant is not used, when an alias or shortcut is selected, the command will return the access path of the targeted element. When you pass the constant, the command returns the path of the alias or shortcut itself.

• Use Sheet Window (Mac OS only): Displays the selection dialog box in the form of a sheet window (this option is ignored under Windows).

Sheet windows are specific to the Mac OS X interface which have graphic animation (for more information, refer to the Window Types section). By default, if this constant is not used, the command will display a standard dialog box.

If you do not want to use an option, pass 0 in the options parameter.

The optional selected parameter allows you to get the full access path (access path + name) of every file selected by the user. The command creates, sizes and fills the array according to the user selection. This parameter is useful when the Multiple files option is used or when you want to find out the access path of the selected file (simply take the name of the file returned by the command from the value of the array). If no file is selected, the array is returned empty.

The command returns the name (name + extension under Windows) of the selected file. If several files are selected, the command returns the name of the first file in the list of selected files. The list of files can be obtained in the selected parameter. If no file is selected, the command returns an empty string.

Open document, Select folder.

If the command has been correctly executed and a valid document was selected, the system variable OK is set to 1 and the system variable Document will contain the full access path of the selected file.

If no file was selected (for example, if the user clicked on the Cancel button in the open file dialog box), the system variable OK is set to 0 and the system variable Document will be empty.