GenClass: 6.2 Vardata: Hints to the Specific UI

| Up: GEOS SDK TechDocs | Up | Prev: 6.1 Optional Attributes (ATTRs) | Next: 6.3 Dynamically Managing VarData

Hints permit the developer to add suggested behavior to the user interface without requiring the specific UI to implement that functionality. Hints therefore provide the specific UI with less stringent guidelines than other attributes. The specific UI has the option of completely ignoring a hint if it cannot understand it or implement it in the requested fashion.

For example, some hints deal with the spacial arrangement of objects and can be ignored if the specific UI cannot accommodate their requests. Developers should use hints to add suggested user interface behavior throughout their UI. This suggested use, however, should not be crucial to their application.

For example, the hint HINT_LIST_CHECKBOXES has no effect under OSF/Motif because the OSF/Motif specification does not include checkboxes. However, in some other specific UI (OpenLook, for example) that feature may be implemented.

Code Display 2-25 Setting Hints

@object GenInteractionClass MyInteraction = {
    GI_comp = @OneTrigger, @TwoTrigger, @ThreeTrigger;
	/* Hints are added directly in an object's declaration. Note that each
	 * vardata entry will expand the size of the object in memory. */
     HINT_ORIENT_CHILDREN_HORIZONTALLY;
	/* This hint instructs the specific UI to arrange the object's children
	 * in one or more horizontal rows, if possible. */
}
/* Hints are entered separately in C if multiple hints are desired. */
@object MyObjectClass MyObject = {
    GI_comp = @MyObjectChild;
    HINT_LIST_CHECKBOXES;
    HINT_ORIENT_CHILDREN_HORIZONTALLY;
}

System Attributes

SystemAttrs, HINT_IF_SYSTEM_ATTRS, HINT_ELSE, HINT_ENDIF

The system attributes are global flags that describe what sort of environment is running the generic object. HINT_IF_SYSTEM_ATTRS is used to conditionally add hints to an object based on these SystemAttrs . If the SystemAttrs set in the HINT_IF_SYSTEM_ATTRS field are true for the current system, then the hints that follow (until a HINT_ENDIF is encountered) are included. If no HINT_ENDIF is encountered, then only the next hint is included. If the SystemAttrs do not match the current system, the following group of hints is instead deleted.

The following SystemAttrs are defined:

SA_TINY
If set, the screen must be either horizontally or vertically tiny.
SA_HORIZONTALLY_TINY
If set, the screen must be horizontally tiny.
SA_VERTICALLY_TINY
If set, the screen must be vertically tiny.
SA_COLOR
If set, the system must have a color screen.
SA_PEN_BASED
If set, the system must be pen-based.
SA_KEYBOARD_ONLY
If set, the system must be set keyboard-only.
SA_NO_KEYBOARD
If set, the system must be set no-keyboard.
SA_NOT
If this flag is set, any other set bits indicate criteria that must not match. This is the equivalent of a logical NOT operation.

The HINT_ELSE hint can be used between HINT_IF_SYSTEM_ATTRS and HINT_END_IF. This allows the inclusion of a separate set of hints to be included when the system conditions in HINT_IF_SYSTEM_ATTRS are not satisfied.

Code Display 2-26 System Attributes

/* The SA_NOT bit acts as a logical not operation. In this case, the hint 
 * HINT_EXPAND_HEIGHT_TO_FIT_PARENT will only be included in the object 
 * declaration if the system is not pen-based. In addition, if the system is tiny,
 * the other hints will be included. The HINT_ENDIF marks the end of these
 * conditional hints. */
    HINT_IF_SYSTEM_ATTRS = SA_NOT | SA_PEN_BASED;
	HINT_EXPAND_HEIGHT_TO_FIT_PARENT;
    HINT_IF_SYSTEM_ATTRS = SA_TINY;
	HINT_MINIMIZE_SIZE;
	HINT_DISPLAY_CURRENT_SELECTION;
    HINT_ENDIF;
/* Example within an object declaration. */
@object GenInteractionClass GroupingObject = {
    GI_comp = @One, @Two, @Three, @Four, @Five, @Six;
    HINT_IF_SYSTEM_ATTRS = SA_HORIZONTALLY_TINY;
    	HINT_ORIENT_CHILDREN_VERTICALLY;
    	HINT_WRAP_AFTER_CHILD_COUNT = 3;
    HINT_ELSE;
    	HINT_ORIENT_CHILDREN_HORIZONTALLY;
    HINT_ENDIF;
}

Default Actions

HINT_DEFAULT_DEFAULT_ACTION, HINT_ENSURE_TEMPORARY_DEFAULT, HINT_PREVENT_DEFAULT_OVERRIDES

Normally, objects in the user interface are activated by direct action (e.g., clicking on them). Objects may also be indirectly activated, however. The object activated indirectly is known as the default action object. For example, within a window, pressing ENTER or sending the window MSG_GEN_ACTIVATE_INTERACTION_DEFAULT will activate the object marked as the default action.

HINT_DEFAULT_DEFAULT_ACTION marks an object as the default action for the window it appears in. This hint is only relevant for GenTriggers or dialog GenInteractions (that are brought up by an activation trigger). The default activation object is usually activated by pressing the ENTER key within the window.

Normally, whenever a trigger is activated within a window, it will become the default activation object the next time around. Even if a trigger has HINT_DEFAULT_DEFAULT_ACTION, if some other trigger is activated, that other trigger will become the default action in the future. To prevent these automatic default overrides, add HINT_PREVENT_DEFAULT_OVERRIDES to the object's instance data.

HINT_ENSURE_TEMPORARY_DEFAULT ensures that an object that can be navigated to (via the TAB key for example) will act as a default activation object even if the specific UI does not normally allow such behavior. (OSF/Motif does this automatically.)

Keyboard Navigation Hints

HINT_NAVIGATION_ID, HINT_NAVIGATION_NEXT_ID

Most specific UIs allow keyboard navigation within windows, usually through use of the TAB key. Normally, the navigation path follows the order of the children within the windowed object, and this is sufficient for most needs.

HINT_NAVIGATION_ID sets a navigation identifier for an object. Objects may "jump" to this object by including HINT_NAVIGATION_NEXT_ID in their instance data with a value equal to the matching navigation ID of the object to travel to.

Code Display 2-27 Navigation IDs

/* Essentially, this code allows keyboard navigation to skip the Two 
 * trigger. Hitting the TAB key on the `One' trigger navigates the focus to the
 * Three trigger. */
@object GenTriggerClass One = {
    GI_visMoniker = "TAB here to get to Three";
    HINT_NAVIGATION_NEXT_ID = 3;
}
@object GenTriggerClass Two = {
    GI_visMoniker = "2";
}
@object GenTriggerClass Three = {
    GI_visMoniker = "3";
    HINT_NAVIGATION_ID = 3;
}

Note that an object with a matching navigation ID must exist, so this method is not recommended. If possible, your UI should be constructed in such a way to allow the default behavior.

| Up: GEOS SDK TechDocs | Up | Prev: 6.1 Optional Attributes (ATTRs) | Next: 6.3 Dynamically Managing VarData