Menus and Dialog Boxes: 3.2 GenInteraction Usage: Types

Possibly more important than how an Interaction is visually displayed is what role that Interaction should play within your UI. That role depends in part on what children the Interaction contains. What the Interaction does with those children is determined by the GenInteractionType of that object. Interactions of different visibility may function in essentially the same manner, but Interactions of different types may differ greatly in their functionality.

For example, if an Interaction contains a GenItemGroup with three GenItem children, it will not affect the basic functionality if that Interaction is built as a dialog, popup, or sub-group. Each item will still perform its default function (such as sending a message). The GII _type of Interaction might affect that functionality, however, by forcing the Items to send out their messages as a group or individually (for example in a GIT_PROPERTIES Interaction).

You should pick the GenInteractionType based on what actions you wish to perform on the children you select for the Interaction. By default, an Interaction is of type GIT_ORGANIZATIONAL. In some cases, the functionality you need will reside entirely with the children; in those cases, a GIT_ORGANIZATIONAL will most likely suffice.

Certain GenInteractionType Interactions, if built as GIV_DIALOG, may create a reply bar with standard response triggers . A reply bar is a special area of a dialog Interaction to place commands for user responses. Standard response triggers perform additional actions for dialog Interactions, apart from any functionality your application provides. You do not need to add these triggers yourself; they are added by the Specific UI.

Standard response triggers perform one of several pre-defined InteractionCommand commands. Depending on the particular type of Interaction, each command may perform different actions. An InteractionCommand is a special data type that the Specific UI recognizes. The Specific UI decides what action to take upon receiving this command; depending on the value of the InteractionCommand , the Specific UI may perform several different actions.

For example, the GIT_NOTIFICATION type, if built as a dialog box, may create an "OK" trigger automatically. The trigger will become one of the dialog box's children. This trigger sends out the InteractionCommand IC_OK when activated. The Specific UI will also decide how to implement that IC_OK message. (In OSF/Motif, for example, IC_OK will dismiss the dialog box as one of its actions.)

You can create your own response triggers within an Interaction. You can also replace any standard response trigger by supplying one of your own. For complete information on how InteractionCommand s and response triggers work, see Interaction Commands .

Organizational Interactions

An organizational interaction is the simplest type of interaction. It is also the default GenInteractionType . An organizational Interaction only functions to contain objects--without indicating any meaning to the makeup of those objects. Because of this, a GIT_ORGANIZATIONAL Interaction should not interpret any InteractionCommand types. See Interaction Commands .

GIT_ORGANIZATIONAL Interactions are only used, therefore, to group their children; there is never any implied meaning to the children they contain. The Interaction may have a certain visual form defined in its GenInteractionVisibility field, but presumably the Interaction should perform its activity under any visible arrangement.

You will most often need an organizational Interaction to arrange objects within another window, whether that "window" is a GenPrimary or a GIV_DIALOG GenInteraction. For example, you may need organizational Interactions solely to arrange a group of generic children in a horizontal or vertical row. There are several hints in GenClass that may affect the visual implementation of an organizational Interaction. See the Managing UI Geometry chapterfor full details.

Organizational Interactions may appear as sub-groups, menus, or dialog boxes; each of its items should already contain all the functionality needed. For example, an edit menu (GIV_POPUP Interaction) with three triggers (Cut, Copy, and Paste) could be organizational if each of those triggers is capable of performing its action purely through the sending of a message (a function of GenTriggerClass ).

No standard response triggers are provided with a GIT_ORGANIZATIONAL Interaction, even if it is built as a dialog box, though you may supply your own. See Standard Response Triggers .

Code Display 7-7 Organizational Interactions

/* This properties dialog box will group a collection of GIT_ORGANIZATIONAL 
 * Interactions. */

@object GenInteractionClass MyMasterInteraction = {
    GI_comp = FirstOrganizational, SecondOrganizational;
    GII_visibility = GIV_DIALOG;
    GII_type = GIT_PROPERTIES;
}

@object GenInteractionClass FirstOrganizational = {
/* GenInteractions are GIT_ORGANIZATIONAL by default. */
    GI_comp = One, Two, Three;
}

@object GenInteractionClass SecondOrganizational = {
    GI_comp = Four, Five, Six;
}

@object GenTriggerClass One = {
/* This trigger, after sending out MY_SPECIAL_MESSAGE to the process, will send a
 * MSG_GEN_GUP_INTERACTION_COMMAND with IC_INTERACTION_COMPLETE to the first
 * non-GIT_ORGANIZATIONAL Interaction it encounters up the tree
 * (MyMasterInteraction). This behavior is due to the GenAttribute
 * GA_SIGNAL_INTERACTION_COMPLETE. (See GenClass.) */

    GTI_actionMsg = MY_SPECIAL_MESSAGE;
    GTI_destination = process;
    GI_attrs = GA_SIGNAL_INTERACTION_COMPLETE;
}

Properties Interactions

GIT_PROPERTIES Interactions allow the Interaction to display and set attributes of a specific selected object (the "current selection"). In many cases, this current selection will be the target of the application. (See the Input chapter.) Users can change the UI gadgets in the properties group to change the attributes of the selected object. When the user selects a different object, the UI gadgetry changes to reflect the attributes of the new selection.

For example, a properties dialog may alter text properties within a text editor. If some text is selected, changing properties in the text dialog will change the appearance of the text.

Properties Interactions may appear as sub-groups, popups, or dialog boxes. If a properties Interaction takes the form of a dialog box, the Specific UI may create response triggers with the InteractionCommand types IC_APPLY, IC_RESET and IC_DISMISS. These triggers will either apply changes made in the properties group, reset those changes to their initial state, or close the dialog, respectively. In OSF/Motif these triggers are labeled "Apply" or "OK," "Reset," and "Close" or "Cancel."

Code Display 7-8 GenInteraction as Properties Dialog Box

@object GenInteractionClass MyInteraction = {
    GI_visMoniker = "Dialog Box";
    GI_comp = PropertiesList;
    GII_visibility = GIV_DIALOG;
    GII_type = GIT_PROPERTIES;
}

/* The GenItemGroup below is a list of three properties. */

@object GenItemGroupClass PropertiesList = {
    GI_visMoniker = "Properties List";
    GI_comp = @PropOne, @PropTwo, @PropThree;
    GIGI_behaviorType = GIGBT_NON_EXCLUSIVE;
}

@object GenItemClass PropOne = {
    GI_visMoniker = "A";
    GII_identifier = 1;
}

@object GenItemClass PropTwo = {
    GI_visMoniker = "B";
    GII_identifier = 2;
}

@object GenItemClass PropThree = {
    GI_visMoniker = "C";
    GII_identifier = 3;
}

There are two ways that an application can deal with UI gadgetry in a property dialog. Either the application can work completely off the state change notification messages sent by the UI gadgetry when the properties are changed, or the application may need to do some extra work after the properties are changed. This extra work can include checking for valid settings in the UI gadgetry, querying the UI gadgetry for their states, or dealing with the UI gadgetry as a group rather than individually (i.e. fetching each of their states and using them all at once to make a single change instead of making separate changes for each state).

Delayed and Immediate Mode

Properties dialogs work in one of two modes: immediate and delayed. In immediate mode, the UI gadgetry within a properties box reflects the actual state of those objects. Changing selections within the properties Interaction changes the state of those objects immediately. For example, if a "Fonts" dialog box containing a list of font selections is in immediate mode, selecting each separate font will cause the selected text to immediately display itself in the selected font.

In delayed mode, the UI gadgetry within the properties box reflects a separate "user" state rather than the actual state. The user is free to change settings within the properties Interaction without causing such changes to be made on the object immediately. The UI does this by storing two states for the UI gadgetry: the actual state (which reflects the current state of the objects) and a user state (which reflects the state specified in the dialog box). The user can apply changes made within a delayed mode properties Interaction with use of an "Apply" mechanism. Usually, the Specific UI will provide an "Apply" trigger for such a case.

If either the Specific UI or hints determine that the properties dialog box should be run in delayed mode, an apply trigger will be supplied. In OSF/Motif, an "Apply" trigger will be placed in a reply bar along with a "Close" trigger that dismisses the property box.

Properties Hints

The GIT_PROPERTIES type and GIV_DIALOG visibility indicate to the Specific UI to build a property dialog box. The Specific UI will also determine whether this box should run in immediate or delayed mode. Because the application works completely through its UI gadgets within the dialog, it will support either mode. However, there are good reasons for wanting the properties to work in one mode or another. You can supply additional hints for this purpose.

These hints only affect the behavior of properties dialog boxes (GIV_DIALOG). Therefore, if an Interaction is a GIV_POPUP or GIV_SUB_GROUP, these hints will have no effect. If the Interaction is a GIV_CONTROL_GROUP or GIV_NO_PREFERENCE, these hints may force the object to appear as a dialog box.

HINT_INTERACTION_COMPLEX_PROPERTIES indicates that the properties dialog box contains complex properties and therefore a means to reset the properties to their initial state should be supplied if available. In OSF/Motif, for example, a "Reset" response trigger is supplied.

HINT_INTERACTION_SIMPLE_PROPERTIES indicates that the properties dialog box contains simple properties and therefore a means to reset the properties to their initial state is probably unneeded.

HINT_INTERACTION_RELATED_PROPERTIES indicates that the properties dialog contains properties that are closely related. Therefore, the specific UI should run the objects as a group in delayed mode and provide an "Apply" trigger. This might be useful if you set several graphics area properties (such as color, texture, and dithering) and only wish to send out the changes after the final selection has been made for all the properties.

HINT_INTERACTION_UNRELATED_PROPERTIES indicates that the properties dialog contains unrelated properties that may be set individually. Therefore, the Interaction can be run in immediate mode and no "Apply" trigger is needed.

HINT_INTERACTION_SLOW_RESPONSE_PROPERTIES indicates that the properties dialog contains properties that may take a long time to be reflected in the state of the object. The specific UI may create an "Apply" trigger operating in delayed mode so that the user can set these attributes all at once.

HINT_INTERACTION_FAST_RESPONSE_PROPERTIES indicates that this properties dialog contains properties in which changes can be quickly reflected. The Interaction will be run in immediate mode without any "Apply" and "Reset" triggers.

Modifying Triggers for Custom Properties

HINT_INTERACTION_REQUIRES_VALIDATION

If an application needs to do additional work on a properties dialog box, such as validation of the attributes, you should define a "custom" properties dialog box. You can do this by replacing the default "Apply" and "Reset" triggers with ones of your own design.

HINT_INTERACTION_REQUIRES_VALIDATION indicates that this properties dialog should prompt the user for verification before implementing changes to the properties group. The Interaction will thus be implemented in delayed mode while also allowing a custom "Apply" trigger. The trigger action should be handled in the normal fashion to add any additional functionality to validate before proceeding with the apply.

You can modify the standard IC_APPLY trigger by adding your own apply trigger with ATTR_GEN_TRIGGER_INTERACTION_COMMAND set to IC_APPLY. This trigger will replace the default IC_APPLY trigger that the Specific UI would have supplied otherwise. HINT_SEEK_REPLY_BAR places the trigger in the property dialog's reply bar. In the GenInteraction itself, you might want to include HINT_INTERACTION_REQUIRES_VALIDATION or another more appropriate hint to ensure that the properties dialog will be working in delayed mode.

An application-supplied trigger allows the application to define whatever action output and method it desires. When the user activates this trigger, the action message will be sent out to the action output (as usual for GenTriggers); the default IC_APPLY functionality will not be performed. In the handler for this custom message, the application can do whatever is necessary with the properties dialog (such as validation of the attributes).

When finished, the application can either manually fetch the state of the attributes or send MSG_GEN_GUP_INTERACTION_COMMAND with IC_APPLY to the GenInteraction. (This is the default behavior of an IC_APPLY InteractionCommand .) You may choose not to send out this message if you wish to replace instead of supplement the default behavior.

Finally, you can send MSG_GEN_GUP_INTERACTION_COMMAND with IC_INTERACTION_COMPLETE to notify the GenInteraction that the user has finished a single usage of the Interaction. (You may also mark such a trigger with GA_SIGNAL_INTERACTION_COMPLETE.) Upon this notification, the specific UI will decide if the GenInteraction should be dismissed. Instead, you may send IC_DISMISS to unconditionally dismiss the Interaction.

Code Display 7-9 Replacing the Default IC_APPLY Trigger

@object GenInteraction LineProperties = {
    GI_visMoniker = "Line Properties";
    GI_comp = LineWidth, LineStyle, LinePropertiesApply;
    GII_type = GIT_PROPERTIES;
    GII_visibility = GIV_DIALOG;
    HINT_INTERACTION_REQUIRES_VALIDATION;						/* Forces delayed mode. */
}

@object GenItemGroupClass LineWidth = {
    /* ... */
}

@object GenItemGroupClass LineStyle = {
    /* ... */
}

@object GenTriggerClass LinePropertiesApply = {
    GTI_destination = process;
    GTI_actionMsg = MSG_MY_PROCESS_PROPERTIES_APPLY;
	/* Setting GA_SIGNAL_INTERACTION_COMPLETE will dismiss the dialog
	 * after applying the properties. */
    GI_attrs = @default | GA_SIGNAL_INTERACTION_COMPLETE;
	/* Setting this attribute to IC_APPLY tells the specific UI to replace
	* the standard response trigger with this one. */

    ATTR_GEN_TRIGGER_INTERACTION_COMMAND = { IC_APPLY };
    HINT_SEEK_REPLY_BAR;
}

The moniker for an application-supplied apply trigger may be set by the application or (preferably) left blank so that the Specific UI can provide an appropriate moniker. The Specific UI uses the IC_APPLY data in the ATTR_GEN_TRIGGER_INTERACTION_COMMAND vardata and any properties hints to determine what moniker to use. (In OSF/Motif this is either "Apply" or "OK.")

If the application wants to alter a moniker but does not need to do any other work, the trigger's output fields should be left blank. Because the trigger has ATTR_GEN_TRIGGER_INTERACTION_COMMAND , if the output fields are null, the trigger will send MSG_GEN_GUP_INTERACTION_COMMAND with the ATTR_GEN_TRIGGER_INTERACTION_COMMAND data to itself. This message will travel up to the appropriate properties GenInteraction where it will be handled, as usual. If doing this, you should make sure to mark any replacement triggers GA_SIGNAL_INTERACTION_COMPLETE so that the Specific UI can determine whether to dismiss the dialog or not when the trigger is activated. (See Replacing the Default IC_APPLY moniker .)

Code Display 7-10 Replacing the Default IC_APPLY moniker

@object GenTriggerClass LinePropertiesApply = {
    GI_visMoniker = "Set Line Properties";
    GI_attrs = @default | GA_SIGNAL_INTERACTION_COMPLETE;
    ATTR_GEN_TRIGGER_INTERACTION_COMMAND = { IC_APPLY };
    HINT_SEEK_REPLY_BAR;
}

An alternate way to supplement an apply trigger's default behavior is to subclass GenInteractionClass and intercept MSG_GEN_GUP_INTERACTION_COMMAND . If the InteractionCommand sent is IC_APPLY, the application's supplemental apply work may then be done. Then call the superclass to finish with the default apply behavior.

Note that this method cannot be used to override the default GA_SIGNAL_INTERACTION_COMPLETE behavior as that is done separately with MSG_GEN_GUP_INTERACTION_COMMAND and IC_INTERACTION_COMPLETE.

For either default or custom properties dialogs, if the properties dialog contains a large number of attributes, it may be useful to provide a means to reset the properties to their former state. This is often done with a hint such as HINT_INTERACTION_COMPLEX_PROPERTIES .

Just as you may use ATTR_GEN_TRIGGER_INTERACTION_COMMAND with IC_APPLY to provide a custom apply trigger, you may use ATTR_GEN_TRIGGER_INTERACTION_COMMAND with IC_RESET to provide a custom reset trigger. This is useful if the application needs to do some additional work when the user resets the attributes or if the application wishes to override the default reset moniker ("Reset" in OSF/Motif). You may still perform the default reset behavior (sending MSG_GEN_RESET to the UI objects) by sending MSG_GEN_GUP_INTERACTION_COMMAND with IC_RESET to the properties Interaction.

Command Interactions

GIT_COMMAND Interactions allow the user to set up parameters for and issue commands. For example, a "rename file" command in a file manager application needs to request the new name for the file from the user. This can be done with a command dialog that shows the file's current name and has a text entry field for the file's new name. A reply bar with a "Rename" action trigger could be provided to initiate the rename action when the user has finished entering the new name.

Command Interactions can appear as menus, dialogs, or sub-groups within a larger window. If the Interaction is displayed as a dialog, the specific UI may provide a response trigger with the IC_DISMISS InteractionCommand that closes the dialog without executing any commands. In OSF/Motif, this trigger is labeled "Close" or "Cancel." You should supply your own additional command triggers yourself. You may also add custom response triggers with ATTR_GEN_TRIGGER_INTERACTION_COMMAND set to a custom InteractionCommand

Command dialogs provide applications with a place to group related commands. They also provide a convenient place to locate UI gadgetry needed to set up parameters used by commands. A command dialog usually contains one or more command triggers in the dialog reply bar. The Specific UI will usually create a trigger to close the dialog box (with IC_DISMISS) but will not supply any command triggers; you must set up any command triggers or custom response triggers yourself.

Code Display 7-11 Using a Command Dialog Box

/* The Command Dialog created below contains one command trigger (RenameTrigger)
 * which sends MSG_MY_PROCESS_RENAME to the process object. */

@object GenInteractionClass RenameBox = {
    GI_visMoniker = "Rename";
    GI_comp = @RenameSource, @RenameDest, @RenameTrigger;
    GII_type = GIT_COMMAND;
    GII_visibility = GIV_DIALOG;
}

@object GenTextClass RenameSource = {
    /* Single-line text entry object */
}

@object GenTextClass RenameDest = {
    /* Single-line text entry object */
}

@object GenTriggerClass RenameTrigger = {
    GI_visMoniker = "Rename";
    GTI_destination = process;
    GTI_actionMsg = MSG_MY_PROCESS_RENAME;
    GI_attrs = @default | GA_SIGNAL_INTERACTION_COMPLETE;
    HINT_SEEK_REPLY_BAR;
}

The Rename trigger in the above example is marked HINT_SEEK_REPLY_BAR to place it in the reply bar of the Interaction, though this is not necessary. The GA_SIGNAL_INTERACTION_COMPLETE attribute on the command trigger indicates that when the user activates this trigger, their use of the dialog is complete and the Specific UI may dismiss the dialog, if it desires. By default, non-modal command dialogs in OSF/Motif are not dismissed. You may use hints to override this behavior.

You may wish to modify this closing behavior, however. For example, if the user chooses an invalid destination name, you might not want to close that dialog; instead, the dialog should remain up and the user should be alerted that he has chosen an incorrect destination. In this case, you should remove the GA_SIGNAL_INTERACTION_COMPLETE attribute from the trigger. You should then handle the closing behavior, after validating the destination, in the MSG_MY_PROCESS_RENAME handler. To dismiss the command dialog, send MSG_GEN_GUP_INTERACTION_COMMAND with IC_DISMISS to it. (You may also use IC_INTERACTION_COMPLETE if you wish to defer to the Specific UI whether to close the dialog box.)

The Specific UI will also create a standard response trigger to dismiss the command dialog box. If some action needs to take place when the user attempts to close this dialog box, you should replace the default Close trigger by adding your own trigger to replace the IC_DISMISS InteractionCommand . As with IC_APPLY and IC_RESET, use ATTR_GEN_TRIGGER_INTERACTION_COMMAND with IC_DISMISS to replace the default trigger. You should also mark this trigger HINT_SEEK_REPLY_BAR if you wish it to appear in the Interaction's reply bar.

Code Display 7-12 Replacing the Default Close Trigger

@object GenInteractionClass RenameBox = {
    GI_visMoniker = "Rename";
    GI_comp = RenameSource, RenameDest, RenameTrigger, RenameClose;
    GII_type = GIT_COMMAND;
    GII_visibility = GIV_DIALOG;
}

@object GenTextClass RenameSource = {
    /* Single-line text entry object */
}

@object GenTextClass RenameDest = {
    /* Single-line text entry object */
}

@object GenTriggerClass RenameTrigger = {
    GI_visMoniker = "Rename";
    GTI_destination = process;
    GTI_actionMsg = MSG_MY_PROCESS_RENAME;
    GI_attrs = @default | GA_SIGNAL_INTERACTION_COMPLETE;
    HINT_SEEK_REPLY_BAR;
}

@object GenTriggerClass RenameClose = {
    GTI_destination = process;
    GTI_actionMsg = MSG_MY_PROCESS_CLOSE_RENAME;
    ATTR_GEN_TRIGGER_INTERACTION_COMMAND = { IC_DISMISS };
    HINT_SEEK_REPLY_BAR;
}

Progress Interactions

GIT_PROGRESS Interactions report the progress of an operation. You will need progress dialogs most often to show the status of an ongoing operation. Progress Interactions may appear as either a dialog or as part of a larger window. (Typically progress reports should not appear within a popup, as popups will not remain on-screen.)

If a progress Interaction takes the form of a dialog box, the Specific UI may create a response trigger with the InteractionCommand IC_STOP. This trigger will halt the operation (and therefore the progress report) and may close the dialog box if the Specific UI or the application desires this. In OSF/Motif this trigger is labeled "Stop." The Specific UI will not supply a default way to close the dialog other than this IC_STOP trigger. In OSF/Motif this means that a system menu for a non-modal progress dialog will have its "Close" trigger disabled.

For example, you can use a progress dialog to report the progress of a disk format. Gadgets within the progress dialog might reflect the current state of the disk format (for example, a bar indicating the time-percentage of the operation completed). A "Stop" trigger in the reply bar allows the user to abort the disk format. Your application should intercept the InteractionCommand IC_STOP in this case so that you can perform any actions required in the halting operation.

A progress dialog may be either modal or non-modal, depending on the application and the operation in progress. The GenInteractionType GIT_PROGRESS is designed for cases where the application supports stopping an in-progress operation.

While the Specific UI will supply an IC_STOP trigger in the reply bar for halting the on-going operation, the trigger by itself does nothing. You must either replace this IC_STOP trigger with one that performs the required halting operation, or you must provide a subclass of GenInteraction to intercept MSG_GEN_GUP_INTERACTION_COMMAND with IC_STOP. Providing a replacement IC_STOP trigger is the easiest method.

Code Display 7-13 Replacing the Default IC_STOP Trigger

/* This Progress Dialog shows the progress of a data transfer. Its first child
 * shows the number of packets sent in the operation, and the second child is an
 * IC_STOP trigger to halt the transfer operation. */

@object GenInteractionClass FileTransferProgress = {
    GI_visMoniker = "File Transfer Status";
    GI_comp = FileTransferPktCount, FileTransferStop;
    GII_visibility = GIV_DIALOG;
    GII_type = GIT_PROGRESS;
}

/* The GenText object shows the title "Packets Sent" and updates the GTI_text field
 * with the current number of packets sent. */

@object GenTextClass FileTransferPktCount = {
    GI_visMoniker = "Packets sent:";
    GTXI_text = "0";
}

/* When the user activates the "Abort File Transfer" trigger, the trigger sends out
 * MSG_MY_PROCESS_ABORT_FILE_TRANSFER to the process. This action should also
 * close the dialog box. Since this trigger may initiate a destructive action,
 * HINT_TRIGGER_DESTRUCTIVE_ACTION makes sure that the focus does not lie on the
 * dialog box (and therefore the trigger cannot be activated by a default
 * activation method such as hitting RETURN). */

@object GenTriggerClass FileTransferStop = {
    GI_visMoniker = "Abort File Transfer";
	/* OSF/Motif will dismiss this dialog box if marked
	 * GA_SIGNAL_INTERACTION_COMPLETE because it is GIT_PROGRESS. */
    GI_attrs = @default | GA_SIGNAL_INTERACTION_COMPLETE;
    GTI_destination = process;
	/* The handler for MSG_MY_PROCESS_ABORT_FILE_TRANSFER must stop the
	 * operation. You may also dismiss the dialog at that time. */
    GTI_actionMsg = MSG_MY_PROCESS_ABORT_FILE_TRANSFER;
    ATTR_GEN_TRIGGER_INTERACTION_COMMAND = { IC_STOP };
    HINT_SEEK_REPLY_BAR;
    HINT_TRIGGER_DESTRUCTIVE_ACTION;					/* Don't place focus here. */
}

Notification Interactions

GIT_NOTIFICATION Interactions allow your application to send notices to the user. You should use a notification Interaction when you wish to notify the user of an event without needing to prompt the user for further information.

GIT_NOTIFICATION interactions normally appear as dialogs. If so, the Specific UI will create a response trigger with the InteractionCommand IC_OK. This command will close the dialog box in most Specific UIs. In OSF/Motif, this trigger is labeled "OK." The Specific UI will not supply a way to close the dialog without responding with this trigger. In OSF/Motif, this means that the system menu in a non-modal notification dialog will have its "Close" trigger disabled.

A notification Interaction may in theory be of any visibility, but it usually takes the form of a modal dialog box. Therefore, the user should only need to acknowledge the dialog box (usually by activating the "OK" trigger).

You will usually require a notification dialog when you need to let the user know that something has occurred that may or may not require his immediate attention. For example, a notification dialog would be appropriate to notify the user that new e-mail has arrived; a notification dialog would also be appropriate to notify the user that an error has occurred.

Notifications that require immediate attention should be marked GIA_MODAL or HINT_INTERACTION_MODAL , depending on the application's dependence on their modality. Interactions that do not require immediate attention may be marked HINT_INTERACTION_NO_DISTURB so that when brought up, they do not disturb the focus or target of the application. This is especially useful for cases such as e-mail notification, where switching the focus away from another application at each new notice might become irritating to the user.

Code Display 7-14 An E-mail Notification Dialog

/* The Notification dialog is marked HINT_INTERACTION_NO_DISTURB so that it
 * will not grab the focus and target. The notification itself has only one child:
 * the text to display to the user. The Specific UI will also create an IC_OK
 * trigger that is used to acknowledge and dismiss the notification. */

@object GenInteractionClass NewMailNotice = {
    GI_visMoniker = "Mailbox";
    GI_comp = NewMailText;
    GII_type = GIT_NOTIFICATION;
    GII_visibility = GIV_DIALOG;
    HINT_INTERACTION_NO_DISTURB;
}

@object GenGlyphClass NewMailText = {
    GI_visMoniker = "New mail has arrived";
}

By default the IC_OK trigger will just dismiss the dialog. If some other action might need to be taken when the user acknowledges the notification, you should provide a custom IC_OK trigger to replace the specific UI supplied one.

Code Display 7-15 Replacing the IC_OK Trigger

/* This Notification dialog now contains two explicit children: the text to
 * display to the user and a custom trigger to acknowledge the notification. */

@object GenInteractionClass NewMailNotice = {
    GI_visMoniker = "Mailbox";
    GI_comp = NewMailText, NewMailAcknowledge;
    GII_type = GIT_NOTIFICATION;
    GII_visibility = GIV_DIALOG;
    HINT_INTERACTION_NO_DISTURB;
}

@object GenGlyphClass NewMailText = {
    GI_visMoniker = "New mail has arrived";
}

/* When the user clicks on the Acknowledge Trigger, MSG_MY_PROCESS_NEW_MAIL_ACK is
 * sent to the process class. Marking the trigger as IC_OK replaces the default
 * trigger. Note that the Specific UI is still allowed to pick the visual moniker
 * for this trigger as its GI_visMoniker field is left blank. */

@object GenTriggerClass NewMailAcknowledge = {
    GTI_destination = process;
    GTI_actionMsg = MSG_MY_PROCESS_NEW_MAIL_ACK;
    GI_attrs = @default | GA_SIGNAL_INTERACTION_COMPLETE;
    ATTR_GEN_TRIGGER_INTERACTION_COMMAND = { IC_OK };
    HINT_SEEK_REPLY_BAR;
}

Affirmation Interactions

GIT_AFFIRMATION Interactions allow your application to provide the user with a choice of yes or no. GIT_AFFIRMATIONs normally appear as dialog boxes. If so, the Specific UI will create response triggers with the commands IC_YES and IC_NO. In OSF/Motif, the triggers are labeled "Yes" and "No." The Specific UI will not provide a default manner to close the dialog without responding to one of these. In OSF/Motif, this means that non-modal dialog boxes will have their "Close" triggers disabled.

For example, your application may need to prompt the user with a yes or no question (such as "Do you want to continue?"). Depending on the value returned in the InteractionCommand , the dialog box may continue or abort any impending operations. In most cases, you will want to use an affirmation interaction when you wish to force the user to make a choice.

An affirmation dialog allows the user to make a single yes or no choice, without an option to ignore the choice and close the dialog. In general, this type of dialog is normally modal or used with UserDoDialog() to block the calling thread until the user responds. When the user chooses, the caller will be unblocked and UserDoDialog() will return IC_YES or IC_NO. Alternatively, you can supply replacement IC_YES or IC_NO (or both) triggers which send out custom messages when activated.

Code Display 7-16 An Affirmation Dialog for Deleting a File

/* Rather than using UserDoDialog(), this dialog is simply marked GIA_MODAL.
 * This approach has the advantage of allowing any views that are run by the
 * process thread to be updated if they are exposed by the application. */

/* This dialog keeps the default IC_NO trigger to dismiss the dialog but
 * replaces the default IC_YES trigger. */

@object GenInteractionClass DeleteAffirmation = {
    GI_comp = DeleteAffirmationText, DeleteAffirmationYes;
    GII_type = GIT_AFFIRMATION;
    GII_visibility = GIV_DIALOG;
    GII_attrs = @default | GIA_MODAL;
}

@object GenGlyphClass DeleteAffirmationText = {
    GI_visMoniker = "Are you sure you want to delete this file?";
}

/* This trigger replaces the default IC_YES trigger. */

@object GenTriggerClass DeleteAffirmationYes = {
    GI_attrs = @default | GA_SIGNAL_INTERACTION_COMPLETE;
    GTI_destination = process;
    GTI_actionMsg = MSG_MY_PROCESS_DELETE_FILE;
    ATTR_GEN_TRIGGER_INTERACTION_COMMAND = {IC_YES};
    HINT_SEEK_REPLY_BAR;
}

Multiple Response Interactions

GIT_MULTIPLE_RESPONSE Interactions allow the UI to provide the user with a number of choices, one of which must be selected. GIT_MULTIPLE_RESPONSE Interactions normally appear as dialog boxes. The Specific UI itself supplies no standard response triggers; you must add your own response triggers. (See Standard Response Triggers .) There is no default provision to just close or cancel the dialog, ignoring the choice. In OSF/Motif, this means the system menu for a non-modal dialog will have its "Close" trigger disabled.

The GIT_MULTIPLE_RESPONSE type allows you to build a custom dialog box. By default, a multiple-response dialog provides no standard response triggers and no way to close the dialog. You must therefore provide any response triggers you might need (including an IC_DISMISS InteractionCommand ). If not, the dialog will only be dismissable by the application, not by the user. In general, you should use a GIT_MULTIPLE_RESPONSE when you wish to prompt the user with several choices, one of which must be chosen.

Code Display 7-17 A Fragmentation Warning Dialog Box

@object GenInteractionClass DatabaseFragmentWarning = {
    GI_comp = DBFragmentText, DBFragmentCompact, DBFragmentContinue;
    GII_type = GIT_MULTIPLE_RESPONSE;
    GII_visibility = GIV_DIALOG;
    GII_attrs = @default | GIA_MODAL;
}

@object GenGlyphClass DBFragmentText = {
    GI_visMoniker = "Database is getting fragmented."
}

/* As none of the following triggers are standard trigger replacements, there is no
 * need to use ATTR_GEN_TRIGGER_INTERACTION_COMMAND. */

@object GenTriggerClass DBFragmentCompact = {
    GI_visMoniker = "Run Compaction utility.";
    GTI_destination = process;
    GTI_actionMsg = MSG_MY_PROCESS_DB_COMPACT;
    GI_attrs = @default | GA_SIGNAL_INTERACTION_COMPLETE;
    HINT_SEEK_REPLY_BAR;
}

@object GenTriggerClass DBFragmentContinue = {
    GI_visMoniker = "Continue without Compacting.";
    GTI_destination = process;
    GTI_actionMsg = MSG_MY_PROCESS_DB_CONTINUE;
    GI_attrs = @default | GA_SIGNAL_INTERACTION_COMPLETE;
    HINT_SEEK_REPLY_BAR;
}

Toolboxes

Toolboxes are useful to display small icons for commonly used operations. Toolboxes are normally provided by controllers. (See the Generic UI Controllers chapter.) In many cases toolboxes are non-modal GIT_ORGANIZATIONAL dialog boxes. Any GenInteraction may be marked HINT_TOOLBOX , however. (In some cases, you may wish a toolbox to be GIT_MULTIPLE_RESPONSE.) GeoDraw provides a toolbox to alter the properties of graphics objects. This toolbox appears at appropriate times in the GeoDraw application and will remain on-screen until the user explicitly closes it by selecting "Close" in its system menu.

Toolbox dialogs should never steal the focus or target of the application; this prevents the user from constantly having to reselect current objects. The hint HINT_TOOLBOX provides this functionality. This hint prevents a toolbox Interaction from grabbing the focus whenever an object within the toolbox is activated.

GEOS SDK TechDocs |

3.1 Visibilities | Next:

4 Supplemental Usage