The Application Object: 2.5 Advanced GenApplication Usage: Interaction with the UI

| Up: GEOS SDK TechDocs | Up | Prev: 2.4 Measurement Type

The GenApplication is an application's main point of contact with the UI. As such, it has several messages that are sent by the UI or by other objects to initiate certain UI-related functions. These messages will rarely, if ever, be used by application programmers, but they are documented here in case you find them useful.

Attaching and Detaching

MSG_GEN_APPLICATION_INITIATE_UI_QUIT, MSG_GEN_APPLICATION_INSTALL_TOKEN, MSG_GEN_APPLICATION_DETACH_PENDING, MSG_GEN_APPLICATION_OPEN_COMPLETE, MSG_GEN_APPLICATION_QUIT_AFTER_UI

MSG_GEN_APPLICATION_INITIATE_UI_QUIT

void	MSG_GEN_APPLICATION_INITIATE_UI_QUIT();

This message causes the GenApplication to begin quitting. The application will automatically go through the entire quit sequence.

Source: Infrequently used.

Destination: The GenApplication of the application to be shut down.

Interception: Do not intercept.

MSG_GEN_APPLICATION_INSTALL_TOKEN

void	MSG_GEN_APPLICATION_INSTALL_TOKEN();

This message instructs the GenApplication object to set its token into the token database file.

Source: Infrequently used.

Destination: The GenApplication to have its token installed.

Interception: Do not intercept.

MSG_GEN_APPLICATION_DETACH_PENDING

void	MSG_GEN_APPLICATION_DETACH_PENDING();

This message is sent to the specific UI library through the GenApplication to notify it that the application is about to be shut down. It is used to abort any application-modal dialog boxes so the application's Process object will be able to detach.

Source: The GenApplication object before it detaches.

Destination: The GenApplication of the application about to be detached.

Interception: Do not intercept.

MSG_GEN_APPLICATION_OPEN_COMPLETE

void	MSG_GEN_APPLICATION_OPEN_COMPLETE();

This message is sent by the GenApplication object to itself when it has finished opening (after it has set itself usable). It is sent via the queue and indicates that the application's UI is fully usable.

Source: A GenApplication after it has set itself GS_USABLE.

Destination: Sent to itself.

Interception: Do not intercept.

MSG_GEN_APPLICATION_QUIT_AFTER_UI

void	MSG_GEN_APPLICATION_QUIT_AFTER_UI();

This message is called from the MSG_META_QUIT handler in GenProcessClass, after the UI has finished its MSG_GEN_APPLICATION_INITIATE_UI_QUIT sequence. This message is the application's last chance to abort a quit before the DETACH sequence begins. The default behavior is to abort the QUIT if the application is still open for the user (i.e. not ALF_OPEN_FOR_IACP_CONNECTION_ONLY) or if an IACP connection remains that requires the application to remain open.

Source: GenProcessClass .

Destination: GenApplication object of the application.

Interception: May be intercepted and not sent to the superclass to abort the QUIT.

Queries of the UI

MSG_GEN_APPLICATION_GET_DISPLAY_SCHEME, MSG_GEN_APPLICATION_QUERY_UI, MSG_GEN_APPLICATION_NOTIFY_MODAL_WIN_CHANGE, MSG_GEN_APPLICATION_INK_QUERY_REPLY, MSG_GEN_APPLICATION_GET_GCN_LIST_OF_LISTS, MSG_GEN_APPLICATION_TEST_WIN_INTERACTABILITY, MSG_GEN_APPLICATION_VISIBILITY_NOTIFICATION, MSG_GEN_APPLICATION_GET_MODAL_WIN, MSG_GEN_APPLICATION_CHECK_IF_ALWAYS_INTERACTABLE_OBJECT

MSG_GEN_APPLICATION_GET_DISPLAY_SCHEME

void	MSG_GEN_APPLICATION_GET_DISPLAY_SCHEME(
        DisplayScheme * displayScheme);

This message gets the current display scheme used by the application.

Source: Infrequently used.

Destination: Any GenApplication.

Parameters: displayScheme A pointer to a structure of type DisplayScheme . This structure will be filled by the method and contains information about the color scheme, display type, font ID, and point size used by the application.

Return: The DisplayScheme structure pointed to by displayScheme will be filled upon return.

Interception: Do not intercept.

MSG_GEN_APPLICATION_QUERY_UI

Handle	MSG_GEN_APPLICATION_QUERY_UI();

This message is used to determine which UI should be used at a given point in the generic tree for a certain type of object.

Source: Infrequently used.

Destination: Any GenApplication object.

Parameters: None.

Return: The handle of the specific UI library geode.

Interception: Do not intercept.

MSG_GEN_APPLICATION_NOTIFY_MODAL_WIN_CHANGE

void	MSG_GEN_APPLICATION_NOTIFY_MODAL_WIN_CHANGE();

This message is called on a GenApplication object by the UI whenever the application should check to see if there is a change in modal status. The behavior is to look for the top system-modal window owned by the application and then the top application-modal window within the application's layer.

This message sets the AS_ATTACHED_TO_STATE_FILE in the GenApplication's GAI_states field.

Source: Sent by the UI.

Destination: Any GenApplication object.

Interception: Do not intercept.

MSG_GEN_APPLICATION_INK_QUERY_REPLY

void	MSG_GEN_APPLICATION_INK_QUERY_REPLY(
        InkReturnValue		inkReturnValue,
        word		inkGstate);

This message is sent to an Application object in reply to a MSG_META_QUERY_IF_PRESS_IS_INK . It indicates whether the object that was queried can or can not handle Ink presses. The GenApplication object responds by sending a message to the UI.

Source: Sent by an object in response to MSG_META_QUERY_IF_PRESS_IS_INK .

Destination: The GenApplication object associated with the sender.

Parameters: inkReturnValue A value indicating whether the object queried can handle Ink input or not. Will be one of IRV_NO_INK, IRV_INK_WITH_STANDARD_OVERRIDE, IRV_DESIRES_INK, or IRV_WAIT.

inkGstate
The GState, if any, to be used when drawing Ink.

Return: Nothing.

Interception: Do not intercept.

MSG_GEN_APPLICATION_GET_GCN_LIST_OF_LISTS

ChunkHandle MSG_GEN_APPLICATION_GET_GCN_LIST_OF_LISTS();

This message retrieves the GenApplication's GCN list of lists chunk handle. This chunk handle may then be used with a number of kernel routines for GCN list management or to perform operations on individual GCN lists.

Source: Any object in the GenApplication's thread.

Destination: Any GenApplication object.

Parameters: None.

Return: The chunk handle of the GCN list of lists chunk; a null chunk handle will be returned if the chunk does not exist.

Interception: Do not intercept.

MSG_GEN_APPLICATION_TEST_WIN_INTERACTABILITY

Boolean	MSG_GEN_APPLICATION_TEST_WIN_INTERACTABILITY(
        optr	inputOD,
        Handle	window);

This message tests whether the passed window object is interactable.

Source: Unrestricted.

Destination: Any GenApplication object.

Parameters: inputOD The optr of the windowed object to be tested.

window
The window handle of the window to be tested.

Return: The return value will be false if there are no modal windows in the system or if the window object passed is the topmost active modal window. The return value will be true if an active modal window exists and is not the passed window object (in this case, if the passed object has any window grabs, it should release them). True is also returned if there is no modal window but the GenApplication is ignoring input.

Interception: Do not intercept.

MSG_GEN_APPLICATION_VISIBILITY_NOTIFICATION

void	MSG_GEN_APPLICATION_VISIBILITY_NOTIFICATION(
        optr		obj,
        Boolean 		opening);

Notifies the GenApplication object that it has become visible or not visible.

Source: The specific UI.

Destination: The GenApplication that has become visible or not visible.

Parameters: obj The optr of the object sending the notification message.

opening
A Boolean indicating the state of the object: true if open, false if closed.

Return: Nothing.

Interception: Do not intercept.

MSG_GEN_APPLICATION_GET_MODAL_WIN

optr	MSG_GEN_APPLICATION_GET_MODAL_WIN();

This message returns the current top modal window for the application, if any is present.

Source: Unrestricted.

Destination: GenApplication object.

Return: optr of top modal windowed object.

MSG_GEN_APPLICATION_CHECK_IF_ALWAYS_INTERACTABLE_OBJECT

Boolean	MSG_GEN_APPLICATION_CHECK_IF_ALWAYS_INTERACTABLE_OBJECT(
        optr		objToCheck);

This message checks if the passed object should always remain interactable.

Source: Unrestricted.

Destination: GenApplication object.

Parameters: objToCheck optr of object to check the interactable state.

Return: true if the object is always interactable, false if not.

Alterations of Functionality

MSG_GEN_APPLICATION_BRING_WINDOW_TO_TOP, MSG_GEN_APPLICATION_LOWER_WINDOW_TO_BOTTOM, MSG_GEN_APPLICATION_BUILD_STANDARD_DIALOG, MSG_GEN_APPLICATION_DO_STANDARD_DIALOG, MSG_GEN_APPLICATION_TOGGLE_CURSOR, MSG_GEN_APPLICATION_BRING_UP_HELP, MSG_GEN_APPLICATION_TOGGLE_CURRENT_MENU_BAR, MSG_GEN_APPLICATION_TOGGLE_FLOATING_KEYBOARD, MSG_GEN_APPLICATION_TOGGLE_EXPRESS_MENU

MSG_GEN_APPLICATION_BRING_WINDOW_TO_TOP

void	MSG_GEN_APPLICATION_BRING_WINDOW_TO_TOP(
        optr	window);

This message brings the passed window to the front of the screen.

Source: Unrestricted

Destination: Any GenApplication object.

Parameters: window The optr of the window object to be brought to the front of the screen.

Return: Nothing.

Interception: Do not intercept.

MSG_GEN_APPLICATION_LOWER_WINDOW_TO_BOTTOM

void	MSG_GEN_APPLICATION_LOWER_WINDOW_TO_BOTTOM(
        optr	window);

This message sends the specified window to the back of the screen, behind other window objects.

Source: Unrestricted.

Destination: Any GenApplication object.

Parameters: window The optr of the window object to be sent to the back of the screen.

Return: Nothing.

Interception: Do not intercept.

MSG_GEN_APPLICATION_BUILD_STANDARD_DIALOG

optr	MSG_GEN_APPLICATION_BUILD_STANDARD_DIALOG(
        char	* customTriggers,
        char	* arg2,
        char	* arg1,
        char	* string,
        CustomDialogBoxFlags dialogFlags);

This message builds a standard dialog box for the application.

Source: Infrequently used.

Destination: The GenApplication to use the dialog box.

Parameters: customTriggers A pointer to a table of custom GenTrigger information. Each trigger given in the table will appear in the dialog box in the order declared. The table is made up of structures of type StandardDialogResponseTriggerTable .

arg 1
A pointer to a character string to be displayed in the dialog box.
arg 2
A pointer to a second string to be displayed in the dialog box.
string
A pointer to a custom character string to be displayed in the dialog box.
dialogFlags
A record of CustomDialogBoxFlags indicating what type of dialog box is to be created.

Return: The optr of the dialog box object.

Interception: Do not intercept.

MSG_GEN_APPLICATION_DO_STANDARD_DIALOG

void	MSG_GEN_APPLICATION_DO_STANDARD_DIALOG(@stack
        word	dialogMethod,
        optr	dialogOD,
        char	*helpContext,
        char	* customTriggers,
        char	* arg2,
        char	* arg1,
        char	* string,
        CustomDialogBoxFlags dialogFlags);

This message executes a standard dialog box and returns immediately. When the dialog box is shut down, the message passed in the dialogMethod parameter is sent to the object specified in dialogOD . Only one dialog box at a time may be displayed with this message.

Source: Infrequently used.

Destination: The GenApplication to use the created dialog box.

Parameters: dialogMethod The message to be sent out when the user is finished with the dialog. This message should be defined based on the prototype GEN_APP_DO_STANDARD_DIALOG_MSG .

dialogOD
The recipient of the message specified in dialogMethod above.
helpContext
The help context for this dialog box.
customTriggers
A pointer to a table of custom GenTrigger information. Each trigger given in the table will appear in the dialog box in the order declared. The table is made up of structures of type StandardDialogResponseTriggerTable .
arg2
A pointer to a second string to be displayed in the dialog box.
arg1
A pointer to a character string to be displayed in the dialog box.
string
A pointer to a custom character string to be displayed in the dialog box.
dialogFlags
A record of CustomDialogBoxFlags indicating what type of dialog box is to be created.

Return: Nothing.

Interception: Do not intercept.

MSG_GEN_APPLICATION_TOGGLE_CURSOR

void	MSG_GEN_APPLICATION_TOGGLE_CURSOR();

This message toggles the cursor for a text object.

Source: Infrequently used.

Destination: The GenApplication of the text object.

Interception: Do not intercept.

MSG_GEN_APPLICATION_BRING_UP_HELP

void	MSG_GEN_APPLICATION_BRING_UP_HELP();

This message brings up help for an application. Normally, this is accomplished by sending a message to the focus object telling it to bring up a help window with the focus' help context.

Source: Unrestricted, though generally from an application Help icon or <F1>.

Destination: GenApplication object.

Interception: Generally not intercepted, though it may be useful if for some reason you do not wish to bring up help (such as it doesn't exist for this application).

MSG_GEN_APPLICATION_TOGGLE_CURRENT_MENU_BAR

void	MSG_GEN_APPLICATION_TOGGLE_CURRENT_MENU_BAR();

This message toggles the GIV_POPOUT state of the current GenPrimary's menu bar. This message only takes effect if the menu bar is toggleable (i.e. if UIWO_POPOUT_MENU_BAR is set).

Source: Unrestricted.

Destination: GenApplication object.

MSG_GEN_APPLICATION_TOGGLE_FLOATING_KEYBOARD

void	MSG_GEN_APPLICATION_TOGGLE_FLOATING_KEYBOARD();

This message toggles the state of the floating keyboard within the current application. Applications may subclass this to bring up their own PenInputControl (or equivalent) object. Otherwise the application object will create its own.

Source: Unrestricted, though generally only supported on pen-based systems.

Destination: GenApplication object.

Interception: May be intercepted if the application has its own PenInputControl object.

MSG_GEN_APPLICATION_TOGGLE_EXPRESS_MENU

void	MSG_GEN_APPLICATION_TOGGLE_EXPRESS_MENU();

This message toggles (opens or closes) the parent field's express menu.

Source: Unrestricted.

Destination: GenApplication object.

| Up: GEOS SDK TechDocs | Up | Prev: 2.4 Measurement Type