Menus and Dialog Boxes: 2.4 GenInteraction Instance Data: GenInteraction Attributes

GII_attrs, MSG_GEN_INTERACTION_GET_ATTRS, MSG_GEN_INTERACTION_SET_ATTRS

The GII_attrs instance field describes how the Interaction behaves under various circumstances. These attributes only affect the behavior of dialog boxes. If the Interaction given these attributes is not a dialog box, the attributes will have no effect. This field specifies how a GIV_DIALOG Interaction may be initiated and whether input to other parts of the UI is allowed while the Interaction is active. The GII_attrs instance field is a bitfield and therefore any combination of these attributes may be set.

None of these attributes is set by default.

GIA_NOT_USER_INITIATABLE: This attribute specifies that the user cannot bring up the dialog directly. Unless this attribute is set, most specific UIs will place a default activation trigger within a proper place in the UI to initiate the dialog box. This attribute prevents this trigger from appearing. To bring up a dialog box set GIA_NOT_USER_INITIATABLE, your application must send the dialog a MSG_GEN_INTERACTION_INITIATE. Usually, these Interactions should be direct children of either a GenPrimary or GenApplication.
GIA_INITIATED_VIA_USER_DO_DIALOG: This attribute specifies that the application brings up this Interaction through UserDoDialog () . You should use this routine in special cases where you need the user to respond to a dialog box before continuing with your application thread. (This routine blocks the calling thread until the user responds to the dialog box.) Any dialog boxes marked with this attribute should not be initiated with MSG_GEN_INTERACTION_INITIATE. The UI won't include a default activation trigger for dialog boxes with this attribute.
GIA_MODAL: This attribute specifies that while this dialog is up, all other input to the application should be ignored. This attribute will create an application modal dialog box.
GIA_SYS_MODAL: This attribute specifies that while this dialog is up, all other input to the system (including other applications) should be ignored. This attribute will create a system modal dialog box.

You may retrieve or set the GII_attrs of any Interaction at run-time. To retrieve the GenInteractionAttrs , send the Interaction a MSG_GEN_INTERACTION_GET_ATTRS . You can set the GenInteractionAttrs of any Interaction by sending it a MSG_GEN_INTERACTION_SET_ATTRS . Make sure that any Interaction you set these attributes for is not currently GS_USABLE or an error will result.

If your application contains several dialog boxes sitting directly under a GenPrimary (typically with their GIA_NOT_USER_INITIATABLE attribute), the application may take longer to start up. This happens because the system will have to process each of the dialogs individually and determine at that point that a trigger should not be created for them.

You may instead wish to create an organizational Interaction to manage these non-user initiatable Interactions. To do this, create a single GIT_ORGANIZATIONAL GIA_NOT_USER_INITIATABLE dialog box under the GenPrimary. All "real" dialogs should then be placed as children of this "holding" Interaction. When the application starts up, it only needs to process this one Interaction.

Grouping dialogs in this way also allows easier initiation and dismissal of the dialogs all at once. Simply encapsulate MSG_GEN_INTERACTION_INITIATE or MSG_GEN_GUP_INTERACTION_COMMAND with IC_DISMISS and use MSG_GEN_SEND_TO_CHILDREN on the one Interaction.

MSG_GEN_INTERACTION_GET_ATTRS

byte	MSG_GEN_INTERACTION_GET_ATTRS();

This message retrieves the current GII_attrs instance field from the Interaction sent the message.

Source: Unrestricted.

Destination: Any GenInteraction object.

Parameters: None.

Return: GenInteractionAttrs of the Interaction.

Interception: Generally not intercepted.

MSG_GEN_INTERACTION_SET_ATTRS

void	MSG_GEN_INTERACTION_SET_ATTRS(
        byte	setAttrs,
        byte	clearAttrs);

This message sets the GII_attrs instance data for the GenInteraction sent the message. The Interaction must not be GS_USABLE when receiving this message. The new attributes will take effect when the Interaction is next made GS_USABLE.

Source: Unrestricted.

Destination: Any non-usable GenInteraction object.

Parameters: setAttrs GenInteractionAttrs to set.

clearAttrs: GenInteractionAttrs to clear.

Return: Nothing.

Interception: Generally not intercepted.

Warnings: Make sure that the object is not GS_USABLE when sending it this message.

GEOS SDK TechDocs |

2.3 GenInteraction Types | Next:

3 GenInteraction Usage