GEOS SDK TechDocs
|
| 
4.1 When a User Selects a File
| 
4.3 Rescanning Directories
GFSI_selection
Most directory and volume navigation is handled internally by the File Selector, and the application has no need to know what is happening until a file is actually selected.
The File Selector maintains the name of the current selection in its
GFSI_selection
instance data field. The current full path, volume name, and disk are stored in variable data entries defined by
GenClass
. The application can easily, at any time, retrieve or set the current selection, path, or volume. Volume names, paths, and file names are all stored as null-terminated character strings in the GEOS character set.
Current path and directory are supported by
GenClass
and are not specific to
GenFileSelectorClass
.
The File Selector's current path is stored in a variable data field called
ATTR_GEN_PATH_DATA
. This field is a
GenFilePath
structure, defined below. This structure stores both an absolute path and the handle of the disk on which the path resides. For the GenFileSelector, this structure represents the currently-displayed directory.
typedef struct {
DiskHandle GFP_disk;
PathName GFP_path;
} GenFilePath;
To retrieve the current path, send the File Selector a
MSG_GEN_PATH_GET
. To set the path, send it
MSG_GEN_PATH_SET
. To retrieve just the disk handle, send
MSG_GEN_PATH_GET_DISK_HANDLE
. Each of these messages is detailed fully in the GenClass chapter.
MSG_GEN_FILE_SELECTOR_UP_DIRECTORY, MSG_GEN_FILE_SELECTOR_OPEN_ENTRY
To set the currently-displayed directory, you can send one of the following messages to the File Selector object (these are all, of course, subject to the File Selector's attributes and applied filters):
MSG_GEN_FILE_SELECTOR_UP_DIRECTORY
GFSI_attrs
.
MSG_GEN_FILE_SELECTOR_OPEN_ENTRY
MSG_GEN_FILE_SELECTOR_GET_SELECTION
when a user clicks on an "Open" button (or something similar) in the File Selector's dialog box.void MSG_GEN_FILE_SELECTOR_UP_DIRECTORY();
This message causes the File Selector to go up one directory in the directory tree. If the File Selector is already in the root directory, it will switch to the volume list (if FSA_ALLOW_CHANGE_VOLUMES is set in
GFSI_attrs
). This message is only valid when the File Selector is visible on the screen.
Source: Unrestricted.
Destination: Any GenFileSelector object that is on the screen.
Interception: Generally not intercepted.
Boolean MSG_GEN_FILE_SELECTOR_OPEN_ENTRY(
word entryNumber);
This message causes the File Selector to open and display the contents of the entry specified. It returns an error flag: if the entry opens successfully, the error flag is returned
false
; if some error occurs, the flag is returned
true
.
The entry specified with this message must be in the current file list. First, retrieve the entry number from the File Selector with the message
MSG_GEN_FILE_SELECTOR_GET_SELECTION
. If the entry can be opened (i.e. it is in the current file list and it is a volume or directory), the File Selector will open it, scan the directory, and display the new file list. If the entry is not a directory or volume, the File Selector will do nothing. This message is only valid when the File Selector is visible on the screen.
Source: Unrestricted.
Destination: Any GenFileSelector object that is on the screen.
Parameters:
entryNumber
The number of the entry to be opened.
Return: An error flag:
true
if error,
false
if no error.
Interception: Generally not intercepted.
MSG_GEN_FILE_SELECTOR_SET_SELECTION, MSG_GEN_FILE_SELECTOR_SET_FULL_SELECTION_PATH, MSG_GEN_FILE_SELECTOR_GET_SELECTION, MSG_GEN_FILE_SELECTOR_GET_FULL_SELECTION_PATH
The File Selector keeps track of which item is currently designated as the selection . The selection appears on the screen as the only highlighted entry in the current list (the highlighted entry may be scrolled out of the view but remains the selection). Additionally, the selection is the file or folder on which any operations (such as open) will be executed.
The
GFSI_selection
field of the GenFileSelector's instance data is a null-terminated character string representing the name of the selection. The format of the selection string depends on the context: If the File Selector is displaying the volume list and thus the selection is a volume label, the string will consist of a drive name followed by a colon. (For non-removable disks, the colon will be followed by [
volume name
].) If the File Selector is displaying a directory and the selection is a file or directory, the selection string will consist of the name of the file or directory selected. The selection does not contain any information about the current volume or directory.
By sending the following messages, you can retrieve or set the current selection in your application. These messages affect
ATTR_GEN_PATH_DATA,
managed by
GenClass
for the File Selector, as well as the
GFSI_selection
instance field.
MSG_GEN_FILE_SELECTOR_SET_SELECTION
MSG_GEN_FILE_SELECTOR_SET_FULL_SELECTION_PATH
MSG_GEN_FILE_SELECTOR_GET_SELECTION
MSG_GEN_FILE_SELECTOR_GET_FULL_SELECTION_PATH
The selection retrieval messages return two word values in a single dword argument. These two values are a record of
GenFileSelectorEntryFlags
, flags that indicate the type of selection and operation underway, and an integer that indicates the place of the selection in the current file list. Two macros allow you to extract these values from the dword argument:
word GFS_GET_ENTRY_NUMBER(arg);
dword arg;
This takes the return value of
MSG_GEN_FILE_SELECTOR_GET_SELECTION
and
MSG_GEN_FILE_SELECTOR_GET_FULL_SELECTION_PATH
and returns the entry number of the selection.
word GFS_GET_ENTRY_FLAGS(arg);
dword arg;
This takes the return value of
MSG_GEN_FILE_SELECTOR_GET_SELECTION
and
MSG_GEN_FILE_SELECTOR_GET_FULL_SELECTION_PATH
and returns the
GenFileSelectorEntryFlags
for the selection.
Boolean MSG_GEN_FILE_SELECTOR_SET_SELECTION(
char *selection);
This message causes the File Selector to attempt to select a given file, directory, or volume from the currently-displayed file list. It sets the selection by setting the File Selector's
GFSI_selection
field to the passed string.
If the File Selector is not on the screen or is suspended when it receives this message, it will set the selection and hold it until it scans the directory. The validity of the selection is not determined until the directory is again scanned. If the directory is not scanned immediately, the message's return value will be
true
. If the File Selector is on the screen and is not suspended, it will determine the validity of the selection immediately and return a value appropriate to the file's validity.
If the selection is valid, the user will see it highlighted in the File Selector's display. The selection will not be opened by this message; it is only selected.
Source: Unrestricted.
Destination: Any GenFileSelector object.
Parameters:
selection
A pointer to a character string giving the name of the file to be selected. The selection string is case-sensitive; if selecting a DOS file, it must be all upper case.
Return: An error flag:
false
if the selection is successfully made. The error condition can occur if the file is not found or if the File Selector can not currently be updated (it is not visible or is suspended).
Interception: Generally not intercepted.
dword MSG_GEN_FILE_SELECTOR_GET_SELECTION(
char *selection);
This message returns the name, the entry number, and the entry flags of the file or directory currently selected.
Source: Unrestricted.
Destination: Any GenFileSelector object.
Parameters:
selection
A pointer to an empty character string at least
sizeof(FileLongName)
characters long. If just the entry number and entry flags are desired, pass a null pointer.
Return: The high word of the dword return value is the number of the selection in the File Selector's current file list. The low word is a record of type
GenFileSelectorEntryFlags
. Use GFS_GET_ENTRY_NUMBER to extract the entry number; use GFS_GET_ENTRY_FLAGS to extract the flags record.
selection
Interception: Generally not intercepted.
Boolean MSG_GEN_FILE_SELECTOR_SET_FULL_SELECTION_PATH(
char *selection,
DiskHandle diskHandle);
This message causes the File Selector to set its path data and its
GFSI_selection
field according to the string passed in
selection
. The string's format is described below. The entry may be in any directory on any volume; the volume is specified by the passed disk handle.
If the File Selector is suspended or not currently on the screen when it receives this message, it will set the path and selection but will do nothing else until it becomes unsuspended or visible. Otherwise, the message will be handled immediately, and the File Selector will navigate to and scan the proper directory, setting the selection if possible.
If the path is valid but the selection is not, the File Selector will display the proper file list and set the selection to the first entry in the list. If any part of the path other than the selection is invalid, the File Selector will show the volume list.
Source: Unrestricted.
Destination: Any GenFileSelector object that is on the screen.
Parameters:
selection
A pointer to a character string containing the full path to be set as the File Selector's current path and selection. The path may be absolute or relative--if relative, it is considered relative to the File Selector's current directory and
diskHandle
will be ignored.
diskHandle
selection
, this parameter will be ignored.
Return: This message returns an error flag: If the selection is successfully made, the flag will be
false
. If an error occurs, the flag will be
true
.
Interception: Generally not intercepted.
dword MSG_GEN_FILE_SELECTOR_GET_FULL_SELECTION_PATH(
char *selection);
This message returns the disk handle and flags as well as the full pathname of the current selection.
Source: Unrestricted.
Destination: Any GenFileSelector object.
Parameters:
selection
A pointer to a character string at least PATH_BUFFER_SIZE characters long. Upon return, this string will contain the full selection path.
Return: The returned dword contains two word-sized fields: The high word represents the File Selector's current disk handle, and the low word is a
GenFileSelectorEntryFlags
record with the selection's flags. Use the macro GFS_GET_FULL_SELECTION_PATH_DISK_HANDLE to extract the disk handle, and use GFS_GET_ENTRY_FLAGS to extract the flags record. If sent when the File Selector is not visible on the screen, the message will return the disk handle and path of the last valid selection.
selection
Interception: Generally not intercepted.
DiskHandle GFS_GET_FULL_SELECTION_PATH_DISK_HANDLE(arg);
dword arg;
This macro extracts the disk handle (the high word) from a dword argument returned by
MSG_GEN_FILE_SELECTOR_GET_FULL_SELECTION_PATH
.
GEOS SDK TechDocs
|
| 4.1 When a User Selects a File
| 4.3 Rescanning Directories