The FileSelector Object: 4.1 File Selector Use: When a User Selects a File

GFSI_destination, GFSI_notificationMsg, MSG_GEN_FILE_SELECTOR_GET_ACTION, MSG_GEN_FILE_SELECTOR_SET_ACTION

When a user selects an entry in the File Selector's displayed list, either by double-clicking or by clicking on an "Open" button, the File Selector will notify a predetermined object or process that a selection has been made. In addition, if the selection is a volume or a directory, the File Selector will automatically (on a double-click) open the selection and show the new file list.

When defining your GenFileSelector, you must designate an output object and a message that will be sent to it when the user makes a selection. The message is stored in the GFSI_notificationMsg instance field, and the object's optr is stored in the GFSI_destination instance field. Note that instead of an optr, you may use a TravelOption as the output destination (TO_TARGET, TO_FOCUS, etc.); you can also use ATTR_GEN_DESTINATION_CLASS to specify the class of the output object to ensure the notification message is only delivered to a class that can handle it.

When the user makes a selection, the File Selector will send the notification message to the destination object along with flags indicating whether the selection was a single or double click. The message is defined by the class that will receive it; for example, the File Selector definition in A Basic File Selector designates MSG_MY_APP_FILE_SELECTED as the notification message that will be sent to the application's process object (the destination object).

You must set both the notification message and the destination object in your File Selector's Goc code. If you don't, no message will be sent, and your application will ignore user input to the File Selector. (The File Selector will still allow the user to navigate throughout the file system, and your application can query the File Selector as to its current selection, however.)

You may retrieve or set the File Selector's notification message and destination object at run-time by sending the following messages:

MSG_GEN_FILE_SELECTOR_GET_ACTION: Returns the File Selector's current notification message and destination object.
MSG_GEN_FILE_SELECTOR_SET_ACTION: Sets the File Selector's GFSI_destination and GFSI_notificationMsg fields to new values.

MSG_GEN_FILE_SELECTOR_GET_ACTION

void	MSG_GEN_FILE_SELECTOR_GET_ACTION(
        GetActionParams *retValue);

This message returns the File Selector's output object and notification message.

Source: Unrestricted.

Destination: Any GenFileSelector object.

Parameters: retValue A pointer to an empty GetActionParams structure (detailed below), which will be filled with the return data.

Return: The GetActionParams structure pointed to by retValue will contain the output optr and notification message set for the File Selector.

Structures: The GetActionParams structure is shown below:

  typedef struct {
    Message  GAP_message; /* GFSI_notificationMsg */
    word     GAP_unused;  /* Internal field */
    optr     GAP_output;  /* GFSI_destination */
} GetActionParams;

Interception: Generally not intercepted.

MSG_GEN_FILE_SELECTOR_SET_ACTION

void	MSG_GEN_FILE_SELECTOR_SET_ACTION(
        optr		actionOD,
        Message		actionMessage);

This message sets the File Selector's GFSI_notificationMsg field to actionMessage and the GFSI_destination field to actionOD .

Source: Unrestricted.

Destination: Any GenFileSelector object.

Parameters: actionOD The optr of the new output object.

actionMessage: The new output notification message.

Return: Nothing.

Interception: Generally not intercepted.

GEOS SDK TechDocs |

4 File Selector Use | Next:

4.2 The Current Selection