The FileSelector Object: 2.3 File Selector Basics: Messages to Handle

2.2 Supporting the File Selector | Next:

The list above shows two different messages that your File Selector's basic configuration: The first results from the user clicking on an entry and comes from the File Selector object, and the second is sent by the "Insert" trigger when the user clicks on it. The following descriptions show what you must do when handling these messages. (Note that in many cases only one message, the File Selector's action message, will be used; this occurs when the "Insert" trigger is actually an IC_OK or similar response trigger.)

Handling a File Selector Selection shows a sample handler for the message sent by the File Selector. Handling a File Selector "OK" Button shows a sample handler for the message sent by the Reply Bar's Insert trigger. Both these handlers are written to go with the code in A Basic File Selector , and both handle the simplest case. Where application-specific code is required, comments have been inserted.

You should not, in general, have to handle any more than the File Selector's notification message. You may add your own gadgetry to add other functionality, however.

The File Selector's notification message is the message you set in GFSI_notificationMsg . This message should have the same definition as the prototype GEN_FILE_SELECTOR_NOTIFICATION_MSG , which is defined below. You can either define it with the same parameters, or you can define it exactly on the prototype. (The latter is recommended.) The prototype carries with the notification a word of GenFileSelectorEntryFlags ; this record contains the following flag fields:

GFSEF_TYPE: This is a two-bit field (at offset GFSEF_TYPE_OFFSET) that describes the type of the selection. This may be one of GFSET_FILE (selection is a file), GFSET_SUBDIR (selection is a subdirectory), or GFSET_VOLUME (selection is a volume or disk). These are values of GenFileSelectorEntryType .
GFSEF_OPEN: Set if the selection action was an "open" (i.e. double-click).
GFSEF_NO_ENTRIES: Set if no entries are in the list.
GFSEF_ERROR: Set if there was an error opening the selected entry on a double-click or a MSG_GEN_FILE_SELECTOR_OPEN_ENTRY .
GFSEF_TEMPLATE: Set if the file is a template (i.e. has GFHF_TEMPLATE set).
GFSEF_SHARED_MULTIPLE: Set if the file is shared with multiple writers (i.e. has GFHF_SHARED_MULTIPLE).
GFSEF_SHARED_SINGLE: Set if the file is shared and has a single writer (i.e. has GFHF_SHARED_SINGLE).
GFSEF_READ_ONLY: Set if the file is read-only (i.e. has FA_RDONLY).
GFSEF_PARENT_DIR: Set if the current selection is the parent directory (i.e. the first entry in the file selector's list).

GEN_FILE_SELECTOR_NOTIFICATION_MSG

void	GEN_FILE_SELECTOR_NOTIFICATION_MSG(
        word				entryNum,
        GenFileSelectorEntryFlags				entryFlags);

This prototype should be used for all notification messages sent out by the File Selector; that is, any message you set in GFSI_notificationMsg should be based on this prototype.

Source: The GenFileSelector object.

Destination: The object specified in GFSI_destination .

Parameters: entryNum The entry number selected in the list.

entryFlags: A GenFileSelectorEntryFlags record describing the selection. To get the entry type from the flags record, use the macro GFS_GET_ENTRY_TYPE, described after this reference entry.

Return: Nothing.

Structures: GenFileSelectorEntryFlags is a record with the following flags:

typedef WordFlags GenFileSelectorEntryFlags;
#define GFSEF_TYPE						0xc000
#define GFSEF_OPEN						0x2000
#define GFSEF_NO_ENTRIES 						0x1000
#define GFSEF_ERROR 						0x0800
#define GFSEF_TEMPLATE 						0x0400
#define GFSEF_SHARED_MULTIPLE 						0x0200
#define GFSEF_SHARED_SINGLE 						0x0100
#define GFSEF_READ_ONLY 						0x0080
#define GFSEF_PARENT_DIR 						0x0040

#define GFSEF_TYPE_OFFSET 					14

The GFSEF_TYPE field is two bits defined by one of the following GenFileSelectorEntryType constants. These two bits define the type of entry selected.

typedef ByteEnum GenFileSelectorEntryType;
#define GFSET_FILE				0
#define GFSET_SUBDIR				1
#define GFSET_VOLUME				2

Interception: The notification message must be intercepted and handled for the selection of a file to have any effect in your application. There is no default behavior, except in the document control objects (which create their own File Selectors).

GFS_GET_ENTRY_TYPE

byte	GFS_GET_ENTRY_TYPE(flags)
        word	flags;

This macro extracts the high two bits from a GenFileSelectorEntryFlags record delivered as a parameter of a File Selector's notification message. Compare the value to GFSET_FILE, GFSET_SUBDIR, and GFSET_VOLUME.

Code Display 14-2 Handling a File Selector Selection

/*
 * C handler for MSG_MY_APP_FILE_SELECTED. The message is sent by the File Selector
 * object (MyFileSel) to the application's Process object (MyProcessClass) when the
 * user clicks on an entry in the displayed file list. This code display is per the
 * setup in  A Basic File Selector.
 */

/*
 * Format of the message:
 * void MSG_MY_APP_FILE_SELECTED(word entryNum,
 *					GenFileSelectorEntryFlags entryFlags)
 */

@method	MyProcessClass, MSG_MY_APP_FILE_SELECTED {
    /* First check if this is an OPEN operation (double-click). If so,
     * then test whether the selection is a file. If so, simulate the "Insert"
     * trigger by sending the trigger's message to ourselves. If it is not a file,
     * or if the operation is not OPEN, we need do nothing. */

    if (GFS_GET_ENTRY_FLAGS(entryFlags) & GFSEF_OPEN) {    /* Is the operation
						      * a double-click? */
	if (GFS_GET_ENTRY_TYPE(entryFlags) & GFSET_FILE) {
						/* Is the selection a file? */
	    /* Execute application-specific code here. */
	}
    }
}

/* Note that we do not necessarily have to handle double-click operations in this
 * way. Since a double-click automatically activates the GenInteraction's default
 * element (typically an "Ok" trigger), we can simply handle the press of the
 * "Ok" trigger as shown in  Handling a File Selector "OK" Button. */

Code Display 14-3 Handling a File Selector "OK" Button

/* C handler for MSG_MY_APP_INSERT_TRIGGER_SELECTED, the message sent by the Insert
 * trigger to the application's Process object when the user clicks on it.
 * Format of this message: void MSG_MY_APP_INSERT_TRIGGER_SELECTED().
 * This code display is per the setup shown in  A Basic File Selector. */

@method	MyProcessClass, MSG_MY_APP_INSERT_TRIGGER_SELECTED {
    /* Declare a local dword of flags and entry number. */
    dword selFlags;

    /* First, retrieve the selection number and flags from the File Selector.
     * For now, we can ignore the selection name and path. To retrieve this
     * information, send the message MSG_GEN_FILE_SELECTOR_GET_SELECTION to the 
     * File Selector. This message will return a dword (selFlags) that contains the
     * selection's entry number and a GenFileSelectorEntryFlags record. (To ignore
     * the selection name, pass a null pointer with the message.) */

    selFlags = @call MyFileSel::MSG_GEN_FILE_SELECTOR_GET_SELECTION(NULL);

    /* Next, determine whether the selection is a file. To do this, check the
     * returned GenFileSelectorEntryFlags record against GFSET_FILE. If the result
     * is true, the selection is a file. If false, it is a directory or volume. If
     * the selection is a file, we will operate on it appropriately (this is
     * specific to each application). If not, we will direct the File Selector to
     * open the entry. Note that we can assume an OPEN operation is in progress
     * because the only two ways to get to this point are through a double-click
     * on a selection and through a click on the "Insert" trigger.
     */

    /* Note the use of the two macros GFS_GET_ENTRY_FLAGS and GFS_GET_ENTRY_NUMBER.
     * The first extracts the GenFileSelectorEntryFlags record from the dword
     * selFlags, and the second extracts the entry number from selFlags. */

    if (GFS_GET_ENTRY_FLAGS(selFlags) == GFSET_FILE) {	/* the selection is a file */

	/* Execute application-specific code here. */

    } else {				/* the selection is a volume or directory */

	/* Now direct the File Selector to open the entry. Use the message
	 * MSG_GEN_FILE_SELECTOR_OPEN_ENTRY, which returns a flag; if the flag is
	 * set, then an error occurred. If the flag is clear, the operation
	 * succeeded. */

	if (@call MyFileSel::MSG_GEN_FILE_SELECTOR_OPEN_ENTRY(
					GFS_GET_ENTRY_NUMBER(selFlags))) {
	    /* Provide a proper error message or beep sound. */
	}
}

GEOS SDK TechDocs |

2.2 Supporting the File Selector | Next:

2.4 Some Common Customizations