GEOS SDK TechDocs
|
| 
3 GenInteraction Usage
| 
3.2 Types
When first creating an Interaction, you must decide in what form to visually present your communication between the application and the user. This concern may be somewhat cosmetic in form but may also affect the functionality of the Interaction itself. For instance, more than one
GenInteractionType
will support different actions with different visibility types.
The simplest GenInteraction is one used to arrange the geometry of other objects. To do this, a GenInteraction should be GIV_SUB_GROUP (the default).
You can use hints provided in
GenClass
to arrange the appearance of objects within the GenInteraction. Interactions usually provide the greatest flexibility for geometry manipulation. For full information, see the Managing UI Geometry chapter.
Note that a GIV_SUB_GROUP Interaction may only appear within a parent window as it is not itself independently displayable.
Code Display 7-4 Arranging a Group of Children
/* This Interaction creates a typical number keypad arrangement. */
@object GenInteractionClass MyKeyPad = {
/* The Interaction by default is GIV_SUB_GROUP and GIT_ORGANIZATIONAL,
* so there is no need to set these types. */
GI_comp = Row789, Row456, Row123;
/* The Interaction's three children will be arranged vertically. The
* UI will also draw a border around the Interaction itself. */
HINT_ORIENT_CHILDREN_VERTICALLY;
HINT_DRAW_IN_BOX;
}
@object GenInteractionClass Row789= {
GI_comp = Key7, Key8, Key9;
/* Each row is then arranged horizontally to gain three rows
* of three items each. */
HINT_ORIENT_CHILDREN_HORIZONTALLY;
}
@object GenInteractionClass Row456= {
GI_comp = Key4, Key5, Key6;
HINT_ORIENT_CHILDREN_HORIZONTALLY;
}
@object GenInteractionClass Row123= {
GI_comp = Key1, Key2, Key3;
HINT_ORIENT_CHILDREN_HORIZONTALLY;
}
/* Each of the child `keys' will be a GenTrigger with appropriate visual * moniker. (For simplicity, only one trigger is shown here.) */
@object GenTriggerClass Key9 = {
GI_visMoniker = "9";
}
Many hints from
GenClass
may affect the appearance of GIV_SUB_GROUP Interactions. See the Managing UI Geometry chapter for details.
Of special interest to sub-group Interactions is
HINT_DRAW_IN_BOX
. This hint will enclose the associated Interaction within a line border. You should use this hint when you wish to distinguish a collection of objects within an Interaction from some other objects.
Most specific UIs implement GIV_POPUP as a menu. Menus are interactions with options that only appear when the menu is activated by the user. Popups make it possible for a user to browse and choose among a variety of commands without cluttering up the UI with dozens of objects. A popup may appear at almost any location within the UI. If a popup is placed as a direct child of a GenPrimary, it may appear in an appropriate menu bar location across the top of the window.
A popup is most often one of GIT_ORGANIZATIONAL, GIT_PROPERTIES, or GIT_COMMAND. (See GenInteraction Types
.) What type of popup you select depends on the type of children the Interaction contains. For example, an application may implement a font menu as a GIT_PROPERTIES popup. A GIT_COMMAND popup might issue commands relating to the appearance of text within a text editor. Depending on the
GenInteractionType
, a popup may appear in forms other than a menu. (The specific UI has final say over the appearance of a popup.)
A GIV_POPUP Interaction must contain a group of children. If the Interaction appears as a menu, these children will become menu items. Most often, these children will be GenTriggers or GenItems within GenItemGroups.
Code Display 7-5 Using a GenInteraction to Create a Menu
/* This example is taken from the Hello World sample application. */
@object GenInteractionClass HelloMenu = {
GI_visMoniker = 'M', "Menu"; /* The moniker of the menu is used in
* the primary window's menu bar (if the
* specific UI employs a menu bar). */
GI_comp = @HelloColorBox; /* The only child of the menu (the only
* item in the menu) is the dialog box. */
GII_visibility = GIV_POPUP; /* This attribute designates the
* interaction as a menu or a sub-menu. */
}
@object GenInteractionClass HelloColorBox = {
GI_comp = @HelloBlueTrigger, @HelloGoldTrigger;
GI_visMoniker = 'C', "Color";
GII_visibility = GIV_DIALOG;
}
@object GenTriggerClass HelloBlueTrigger = {
GI_visMoniker = 'B', "Blue"; /* The 'B' indicates the keyboard navigation
* character for this trigger. */
GTI_destination = process; /* Send the message to the Process object. */
GTI_actionMsg = MSG_HELLO_CHANGE_TO_BLUE; /* Send this message. */
}
@object GenTriggerClass HelloGoldTrigger = {
GI_visMoniker = 'G', "Gold"; /* The 'G' indicates the keyboard navigation
* character for this trigger. */
GTI_destination = process; /* Send the message to the Process object. */
GTI_actionMsg = MSG_HELLO_CHANGE_TO_GOLD; /* Send this message. */
}
If a child of the GIV_POPUP Interaction is another Interaction, the specific UI might change the visual implementation of that child. What change takes place depends on the specific UI. In OSF/Motif, for example, placing a sub-group Interaction within a popup Interaction causes the UI to draw lines separating the sub-group from the other children in the popup. (You may prevent this line by adding
HINT_SAME_CATEGORY_AS_PARENT
.)
Placing a popup interaction within another popup is a special case and will create nested menus under most specific UIs. To do this, merely create a GIV_POPUP Interaction as a child of another GIV_POPUP Interaction. The specific UI will automatically create the second menu as a sub-menu of the first. The item in the menu bringing up the sub-menu may be labeled with an arrow under certain specific UIs. Menus may be nested to an arbitrary number of levels.
Code Display 7-6 Nested Menus
@object GenInteractionClass TextMenu = {
GI_comp = @JustificationSubMenu;
GI_visMoniker = `T', "Text";
GII_visibility = GIV_POPUP;
}
@object GenInteractionClass JustificationMenu = {
GI_comp = @JustificationList;
GI_visMoniker = `J', "Justification";
GII_visibility = GIV_POPUP;
}
@object GenItemGroupClass JustificationList = {
GI_comp = @LeftEntry, @RightEntry, @CenterEntry, @FullEntry;
/* These children are not shown. */
}
List Objects (GenItemGroups and GenBooleanGroups) within a GIV_POPUP Interaction may be used to show object properties in a menu. The menu should be GIT_PROPERTIES in this case. Depending on the Specific UI, a properties menu may be implemented in a different fashion from other menus. (In OSF/Motif, there is no visual difference between a properties menu and other menus.) Other types have no effect on the behavior or appearance of GIV_POPUPs.
The GIV_DIALOG visibility will instruct the specific UI to build the Interaction as a dialog box. A dialog box is an independently-displayable interface element used to display information or other UI objects. Therefore, it is similar to a window although there are some differences. (Most dialog boxes, for example, are not resizable whereas most windows are.)
Dialog boxes also enhance the functionality of other
GenInteractionType
s. Many GII
_types
are only significant as dialog boxes. For example, a GIT_NOTIFICATION Interaction will only appear with an "OK" trigger if it is also a dialog box. A GIT_PROPERTIES Interaction may contain properties within any visibility, but only if built as a dialog can it implement delayed mode. (If a GIT_PROPERTIES Interaction is built as a menu or sub-group, it will always operate in immediate mode.) Delayed mode allows the user to change the properties of an object and later apply those changes all at once. Within a dialog box, an "Apply" trigger will make these changes.
Most specific UIs will build a dialog box with an activation trigger present in the UI that brings up the dialog box. These dialog boxes are known as user initiatable. There are ways to override this behavior if you need a non-user initiatable dialog box or a dialog box that blocks the calling thread until answered (forcing the user to respond to the dialog box immediately). See Modality for Dialogs .
By default, dialog boxes are not resizable.
HINT_INTERACTION_MAKE_RESIZABLE
may be used on a non-modal dialog box to make that dialog resizable. In OSF/Motif, the Specific UI will supply such a dialog with a means to alter its shape.
HINT_INTERACTION_MAKE_RESIZABLE
is only meaningful for GIV_DIALOG Interactions.
MSG_GEN_INTERACTION_POP_IN, MSG_GEN_INTERACTION_POP_OUT, MSG_GEN_INTERACTION_TOGGLE_POPOUT
Popouts are special GenInteractions that may act as either sub-group Interactions or as dialog boxes, depending on their state. Usually, popouts act as normal sub-group Interactions until the user or the application "pops" them out into a dialog box. Popouts are normally "popped out" into their dialog box state by double-clicking within the confines of the GenInteraction. This popout state is reflected with either the presence or absence of the ATTR_GEN_INTERACTION_POPPED_OUT vardata entry.
You can pop out a GIV_POPOUT GenInteraction in its sub-group state by sending it MSG_GEN_INTERACTION_POP_OUT. Similarly, you can pop a GIV_POPOUT back into its sub-group state from the dialog box state by sending it MSG_GEN_INTERACTION_POP_IN. MSG_GEN_INTERACTION_TOGGLE_POPOUT toggles a popout from whatever state it currently is into its other state.
By default, popouts in their dialog box state contain a special trigger to pop them back into their sub-group state. They may also be popped back in by double-clicking within the popped-out GenInteraction. Popouts also normally provide a close trigger; this trigger dismisses the dialog box but does not return the popout to its sub-group state. You should provide a trigger somewhere within your UI that sends MSG_GEN_INTERACTION_POP_IN or MSG_GEN_INTERACTION_POP_OUT to the popout, so that the user can bring any popout they dismiss back on-screen. Alternatively, you can add ATTR_GEN_INTERACTION_POPOUT_NOT_CLOSABLE on the Popout to prevent the creation of a "Close" trigger.
void MSG_GEN_INTERACTION_POP_IN();
This message `pops in' a GIV_POPOUT GenInteraction into its default sub-group state. This message has no effect if the GenInteraction is not a GIV_POPOUT or if the GenInteraction is already `popped in.'
Parameters: Nothing.
Return: Nothing.
void MSG_GEN_INTERACTION_POP_OUT();
This message `pops out' a GIV_POPOUT GenInteraction into its dialog box state. This message has no effect if the GenInteraction is not a GIV_POPOUT or if the GenInteraction is already `popped out.'
Parameters: Nothing.
Return: Nothing.
void MSG_GEN_INTERACTION_TOGGLE_POPOUT();
This message toggles the state of a GIV_POPOUT GenInteraction from its `popped in' state to its `popped out' state (or `popped out' and hidden from view) and vice-versa. The specific UI has control over how this message is implemented.
Parameters: Nothing.
Return: Nothing.
GEOS SDK TechDocs
|
| 3 GenInteraction Usage
| 3.2 Types