GEOS SDK TechDocs
|
| 
4 Supplemental Usage
| 
4.2 Dismissing Interactions
MSG_GEN_INTERACTION_INITIATE, MSG_GEN_INTERACTION_INITIATE_NO_DISTURB, MSG_GEN_INTERACTION_DISABLE_DISCARDING
For the most part, the Specific UI decides in what way Interactions should be initiated. For example, a popup built as a menu will create a menu title which, when activated, brings down the menu. A dialog box will create an activation trigger within the UI that, when activated, brings the dialog box on-screen. (Notice that it is meaningless to "initiate" a sub-group Interaction as these objects are not independently-displayable.)
You may wish to modify this behavior, either to prevent the user from directly initiating an Interaction, or to add additional ways to bring these Interactions on-screen.
Although in most cases the user is responsible for activating menus (by activating the menu title), an application may manually open a menu with
MSG_GEN_INTERACTION_INITIATE
.
A GIV_DIALOG Interaction may be initiated in several ways:
MSG_GEN_INTERACTION_INITIATE
or a
MSG_GEN_INTERACTION_INITIATE_NO_DISTURB
to bring the dialog on-screen. You may also put Interactions on the GAGCNLT_WINDOWS GCN list to automatically bring them on-screen when an application is launched. Any Interaction must be fully usable and enabled to be brought up in such a manner. Note: If a dialog box is also marked GIA_INITIATED_VIA_USER_DO_DIALOG, it should be initiated with
UserDoDialog()
,
not
MSG_GEN_INTERACTION_INITIATE. These methods are exclusive.
UserDoDialog()
if it is set GIA_INITIATED_VIA_USER_DO_DIALOG. This routine is useful when you wish to block the calling thread until the user responds to the dialog box. A dialog box initiated via
UserDoDialog()
should also be marked GIA_NOT_USER_INITIATABLE. Note that this dialog box may only be brought up with
UserDoDialog()
; it cannot be brought up with MSG_GEN_INTERACTION_INITIATE.
Within most specific UIs a trigger will appear whose sole function is to initiate the dialog. Activating the trigger will bring the dialog box on-screen. You can prevent the display of this default trigger by setting the Interaction GIA_NOT_USER_INITIATABLE in its
GII_attrs
instance field. (See GenInteraction Attributes
).
Your GenInteraction subclass may intercept
MSG_GEN_INTERACTION_INITIATE
to determine when a dialog is being brought on-screen and then perform any needed actions at that time. This is useful if you need to update the UI objects within the dialog before building its visual implementation. You should always call the superclass
after
setting any of this initial data to avoid unnecessary visual updates of the dialog box.
MSG_GEN_INTERACTION_INITIATE_NO_DISTURB
may also be subclassed, but there is little need to intercept it.
GenInteraction dialog boxes may be marked
HINT_INTERACTION_DISCARD_WHEN_CLOSED
.This hint informs the system to discard the dialog box's object block when it is no longer being used, but there is a timing problem if the dialog box needs to be initialized before it is brough on-screen. (The system will think it is off-screen and discard it before initialization is complete.)
In that case, send the dialog box
MSG_GEN_INTERACTION_DISABLE_DISCARDING
to ensure that the dialog box doesn't get discarded between the time that the initialization is performed and the time when the dialog box appears on-screen.
void MSG_GEN_INTERACTION_INITIATE();
This message brings an Interaction on-screen, giving it focus and target if possible. The Interaction must be both within the generic tree and set GS_USABLE before receiving this message. The Interaction must also be fully usable and enabled before it can be initiated. Interactions marked GIA_INITIATED_VIA_USER_DO_DIALOG should not be sent this message. To initiate those dialogs, you must use
UserDoDialog()
. (See Thread Blocking Routines
.)
You may intercept this message to determine when a dialog is coming on-screen. This is useful if you need to set up UI gadgetry in the dialog to show some initial status. The gadgetry should be set up before calling the superclass to avoid unnecessary visual updating of the object.
Source: Unrestricted.
Destination: Any GS_USABLE GenInteraction, though usually only meaningful for GIV_DIALOG interactions.
Parameters: None.
Return: Nothing.
Interception: May be intercepted to find out when an Interaction is appearing on-screen. This is useful for cases in which the UI gadgetry of a dialog box needs to be set up before being visually built. The superclass should be called after setting up the UI to avoid unnecessary visual changes once the interaction is on-screen.
void MSG_GEN_INTERACTION_INITIATE_NO_DISTURB();
This message brings an Interaction on-screen but does not give the dialog the focus or target. This message may place the dialog behind other windows. The Interaction must be both within the generic tree and set GS_USABLE before receiving this message. The Interaction must also be fully usable and enabled before it can be initiated. Interactions marked GIA_INITIATED_VIA_USER_DO_DIALOG should not be sent this message. To initiate those dialogs, you must use
UserDoDialog()
. (See Thread Blocking Routines
.)
Source: Unrestricted.
Destination: Any GS_USABLE GenInteraction, though usually only meaningful for GIV_DIALOG Interactions. Not allowed for GIA_MODAL or GIA_INITIATED_VIA_USER_DO_DIALOG Interactions.
Parameters: None.
Return: Nothing.
Interception: May be intercepted to find out when an Interaction is appearing on-screen. This is useful for cases in which the UI gadgetry of a dialog box needs to be set up before being visually built. The superclass should be called after setting up the UI to avoid unnecessary visual changes once the interaction is on-screen.
void MSG_GEN_INTERACTION_DISABLE_DISCARDING();
This message informs a Interaction with
HINT_INTERACTION_DISCARD_WHEN_CLOSED
that it should not be discarded until it has been brought on-screen. This message is used to ensure that a dialog box that needs initialization is not discarded between the time that initialization commences and the time that the dialog finally appears on-screen.
Source: Unrestricted.
Destination: Any GIV_DIALOG GenInteraction that is marked
HINT_INTERACTION_DISCARD_WHEN_CLOSED
and needs initialization.
Parameters: None.
Return: Nothing.
GEOS SDK TechDocs
|
| 4 Supplemental Usage
| 4.2 Dismissing Interactions