Menus and Dialog Boxes: 5.1 Interaction Commands: InteractionCommand Types

GEOS SDK TechDocs

5 Interaction Commands

5.2 Dialog Control

Many of these InteractionCommand s are sent out by standard response triggers provided with the Specific UI. Different types of Interactions may provide different standard response triggers with InteractionCommand s. For example, the "OK" trigger for a GIT_NOTIFICATION dialog box in OSF/Motif sends out the InteractionCommand IC_OK.

The InteractionCommand represents the actions that can be performed on an Interaction. The predefined commands are as follows:

• IC_NULL
  This InteractionCommand is a special case for alerting a UserDoDialog() or UserStandardDialog() dialog box that it is being dismissed because of system shutdown. Because of thread blocking, you should always check for this case to occur in any UserDoDialog() routines. You should never set any custom triggers to this InteractionCommand .
• IC_DISMISS
  This command instructs the UI to dismiss the Interaction. An Interaction receiving this command will come down whether or not the user has selected the Interaction to remain up (such as by pinning the dialog box).
• IC_APPLY
  This command instructs the UI to apply properties selected within a GIT_PROPERTIES Interaction. This InteractionCommand causes MSG_GEN_APPLY to be sent to the Interaction's children.
• IC_RESET
  This command instructs the UI to reset properties within a GIT_PROPERTIES Interaction. This InteractionCommand causes MSG_GEN_RESET to be sent to the Interaction's children.
• IC_OK
  This command instructs the UI to signal an acknowledgment to a GIT_NOTIFICATION Interaction.
• IC_YES
  This command instructs the UI to signal a positive response to a GIT_AFFIRMATION Interaction.
• IC_NO
  This command instructs the UI to signal a negative response to a GIT_AFFIRMATION Interaction.
• IC_STOP
  This command instructs the UI to halt a GIT_PROGRESS Interaction.
• IC_EXIT
  This command instructs the UI to exit the application (not just the window). This InteractionCommand is only supported for GenTriggers under GIV_POPUP GenInteractions. This value should only be used with ATTR_GEN_TRIGGER_INTERACTION_COMMAND.
• IC_HELP
  This command instructs the UI to bring up the proper help context for this dialog. This value should only be used with ATTR_GEN_TRIGGER_INTERACTION_COMMAND.
• IC_INTERACTION_COMPLETE
  This command notifies the UI that an interaction has been completed. This InteractionCommand is sent out by any trigger with the attribute GA_SIGNAL_INTERACTION_COMPLETE before the trigger's main action has been sent out. Note that this InteractionCommand is always sent out in addition to another IC. You should never set any custom triggers to this InteractionCommand .

IC_DISMISS, IC_APPLY, IC_RESET, IC_OK, IC_YES, IC_NO, and IC_STOP correspond to standard response triggers provided with the Specific UI for dialogs of various GenInteractionType . (See GenInteraction Types .)

You may replace any of these standard response triggers by adding your own triggers with an InteractionCommand . You should do this by setting the trigger's ATTR_GEN_TRIGGER_INTERACTION_COMMAND vardata to the proper InteractionCommand to replace. (See Replacing Default Triggers .)

Adding Custom Response Triggers

In some cases, you may want to add your own response triggers. In many of these cases, a trigger tied to one of the predefined InteractionCommand s will be sufficient for your needs. If a dialog box does not contain one of the pre-defined response triggers by default, you can add any of these yourself.

You are not limited to one of these predefined types, however. UserDoDialog() and GIT_MULTIPLE_RESPONSE UserStandardDialog () allow you to define your own InteractionCommand types. Applications can define their own InteractionCommand by starting an enumeration at the special value IC_CUSTOM_START. This is to avoid conflicting with other predefined values, which still have their usual meaning to the dialog.

Code Display 7-23 Using IC_CUSTOM_START

/* You may define values directly. */

#define IC_SAVE_FILE IC_CUSTOM_START+1;
#define IC_KILL_FILE IC_CUSTOM_START+2;

/* You may also use typedef to enumerate those values. */

typedef enum {
    IC_SAVE_FILE = IC_CUSTOM_START+1,
    IC_KILL_FILE = IC_CUSTOM_START+2
} MyInteractionCommand;

/* Any triggers set up with these InteractionCommands would appear like so: */

@object GenTriggerClass MyTrigger = {
    GI_visMoniker = "Save File";
    ATTR_GEN_TRIGGER_INTERACTION_COMMAND = { IC_SAVE_FILE };
    HINT_SEEK_REPLY_BAR;
}

/* An Interaction invoked with UserDoDialog() (with MyTrigger as one of its
 * children) will return IC_SAVE_FILE when that trigger is activated. Your
 * application can then perform any required actions. */

GEOS SDK TechDocs

5 Interaction Commands

5.2 Dialog Control