GEOS SDK TechDocs
|
| 
2.1 Instance Fields
| 
3 GenClass Basics
GenClass
provides a multitude of pre-defined vardata instance fields. You may add these vardata entries to a generic object directly within its object declaration. Vardata instance fields perform several key roles for a generic object. Specifically, they provide two distinct uses:
Any of these data may be accessed and altered using object system routines. For more information, see the GEOS Programming chapter.
Vardata attributes may contain the same functionality as other instance fields. Variable attributes, however, will only be allocated space within an object declaration if they are actually declared; instance data fields always take up space within an object, whether used or not. Therefore, vardata attributes are ideal for data that should only take up space if actually used. Vardata attributes are prefaced with
ATTR_
. Several ATTRs are included in
GenClass
. See ATTR vardata fields
for a complete list of these vardata attributes.
Code Display 2-2 ATTR vardata fields
@vardata void ATTR_GEN_PROPERTY; @vardata void ATTR_GEN_NOT_PROPERTY;
@vardata DestinationClassArgs ATTR_GEN_DESTINATION_CLASS;
@reloc ATTR_GEN_DESTINATION_CLASS, 0, optr;
@vardata char[] ATTR_GEN_INIT_FILE_KEY; @vardata char[] ATTR_GEN_INIT_FILE_CATEGORY; @vardata void ATTR_GEN_INIT_FILE_PROPAGATE_TO_CHILDREN; @vardata void ATTR_GEN_USES_HIERARCHICAL_INIT_FILE_CATEGORY;
@vardata Point ATTR_GEN_POSITION; @vardata sword ATTR_GEN_POSITION_X; @vardata sword ATTR_GEN_POSITION_Y;
@vardata void ATTR_GEN_SEND_APPLY_MSG_ON_APPLY_EVEN_IF_NOT_MODIFIED; @vardata void ATTR_GEN_SEND_APPLY_MSG_ON_APPLY_EVEN_IF_NOT_ENABLED;
@vardata dword ATTR_GEN_VISIBILITY_DATA;
@vardata word ATTR_GEN_VISIBILITY_MESSAGE;
@vardata optr ATTR_GEN_VISIBILITY_DESTINATION;
@reloc ATTR_GEN_VISIBILITY_DESTINATION, 0, optr;
@vardata GenFilePath ATTR_GEN_PATH_DATA;
@vardata ChunkHandle ATTR_GEN_FEATURE_LINK;
@vardata GenDefaultMonikerType ATTR_GEN_DEFAULT_MONIKER;
@vardata optr ATTR_GEN_OUTPUT_TRAVEL_START;
@reloc ATTR_GEN_OUTPUT_TRAVEL_START, 0, optr;
/* Generic Help attributes */
@vardata char[] ATTR_GEN_HELP_FILE;
@vardata byte ATTR_GEN_HELP_TYPE;
@vardata void ATTR_GEN_HELP_FILE_FROM_INIT_FILE;
@vardata optr ATTR_GEN_FOCUS_HELP;
@vardata optr ATTR_GEN_FOCUS_HELP_LIB;
@reloc ATTR_GEN_FOCUS_HELP_LIB, 0, optr;
@vardata char[] ATTR_GEN_HELP_CONTEXT;
/* Generic Window attributes */
@vardata MemHandle ATTR_GEN_WINDOW_CUSTOM_LAYER_ID;
@reloc ATTR_GEN_WINDOW_CUSTOM_LAYER_ID, 0, optr;
@vardata WinPriority ATTR_GEN_WINDOW_CUSTOM_WINDOW_PRIORITY;
@vardata LayerPriority ATTR_GEN_WINDOW_CUSTOM_LAYER_PRIORITY;
@vardata MemHandle ATTR_GEN_WINDOW_CUSTOM_PARENT;
@vardata void ATTR_GEN_CUSTOM_WINDOW;
@vardata void ATTR_GEN_WINDOW_ACCEPT_INK_EVEN_IF_NOT_FOCUSED;
@vardata KeyboardOverride ATTR_GEN_WINDOW_KBD_OVERRIDE;
@vardata Point ATTR_GEN_WINDOW_KDB_POSITION;
ATTR_GEN_PROPERTY
and
ATTR_GEN_NOT_PROPERTY
affect a generic object's ability to behave as a properties group. These attributes override the property group's default behavior. For more information, see Generic Properties
.
ATTR_GEN_DESTINATION_CLASS
specifies an object class that should handle all messages sent out along a destination path. The type
DestinationClassArgs
contains a pointer to a
ClassStruct
. Typically, this attribute is used with a
TravelOption
destination to form a search path. The message for that generic object travels down a path specified in the
TravelOption
until it encounters an object class of type
ATTR_GEN_DESTINATION_CLASS
; at that point, the message will be handled. For more information, see Destination Classes
.
ATTR_GEN_INIT_FILE_KEY
,
ATTR_GEN_INIT_FILE_CATEGORY
,
ATTR_GEN_INIT_FILE_PROPAGATE_TO_CHILDREN
, and ATTR_GEN_USES_HIERARCHICAL_INIT_FILE_CATEGORY allow a generic object to load options from the .INI file upon startup (after receiving a
MSG_META_ATTACH
). Generic objects with these attributes will receive a
MSG_GEN_LOAD_OPTIONS
(with the category and key of the proper entry in the .INI file) and may intercept that message to provide additional behavior. For more information, see Initialization File Management
.
ATTR_GEN_POSITION
,
ATTR_GEN_POSITION_X
, and
ATTR_GEN_POSITION_Y
override default geometry management of an object and set a precise position for the object to appear within the UI, offset from the parent object. ATTR_GEN_POSITION specifies both a horizontal and a vertical position to place the object. ATTR_GEN_POSITION_X and ATTR_GEN_POSITION_Y specify either a horizontal or vertical position to align the object along. You should avoid using these attributes because they override default behavior and may result in different (and potentially unsightly) appearances under different specific UIs. For more information, see Altering Default Geometry Management
.
ATTR_GEN_SEND_APPLY_MSG_ON_APPLY_EVEN_IF_NOT_MODIFIED
and
ATTR_GEN_SEND_APPLY_MSG_ON_APPLY_EVEN_IF_NOT_ENABLED
affect generic objects that contain an apply message--a message that an object sends out when it wishes to apply changes made within that object. By default, an apply message will not be sent out if the object's state has not changed since the last apply or if the object is not enabled; these attributes tell the object to send out its apply message regardless of these conditions. For more information, see Altering Delayed Mode Activity
.
ATTR_GEN_VISIBILITY_DATA
,
ATTR_GEN_VISIBILITY_MESSAGE
, and
ATTR_GEN_VISIBILITY_DESTINATION
set the data, message or destination to use with the visibility notification mechanism in
GenClass
. The visibility mechanism allows an application to know when an object becomes visible and not visible. An object provides this notification if its GA_NOTIFY_VISIBILITY bit is set. For more information, see Notification of Visibility
.
ATTR_GEN_PATH_DATA
stores an object's generic path information in the form of a
GenFilePath
structure. This structure contains disk and path information including path name and file name; generic objects can use this attribute to store current or default paths and files. For more information, see Generic Paths
.
ATTR_GEN_FEATURE_LINK
contains a link to the next feature used by the GenControl mechanism when a controller's features map to multiple objects. It is unlikely you will use this attribute. For more information, see Feature Links
.
ATTR_GEN_DEFAULT_MONIKER specifies a default moniker for a generic object. This is generally used for graphic monikers that occur several places within the system. For more information, see Default Monikers .
ATTR_GEN_OUTPUT_TRAVEL_START
allows you to set a specific object to begin the
TravelOption
. Normally, objects that contain a
TravelOption
in their destination field use their own object as the point of reference for sending messages along travel paths. (I.e sending a message TO_FOCUS would send a message along the focus path, starting at the sending object.) This can be used for optimization purposes, enabling you to skip several layers of hierarchies.
ATTR_GEN_HELP_FILE , ATTR_GEN_HELP_TYPE, ATTR_GEN_HELP_FILE_FROM_INIT_FILE, ATTR_GEN_FOCUS_HELP, ATTR_GEN_FOCUS_HELP_LIB, and ATTR_GEN_HELP_CONTEXT specify the configuration of the help files for a generic object. Focus help starts help notification when the generic object gains the focus. For more information on Help files, see Help Management .
ATTR_GEN_WINDOW_CUSTOM_LAYER_ID , ATTR_GEN_WINDOW_CUSTOM_WINDOW_PRIORITY, ATTR_GEN_WINDOW_CUSTOM_LAYER_PRIORITY, ATTR_GEN_WINDOW_CUSTOM_PARENT, and ATTR_GEN_CUSTOM_WINDOW specify a window's interaction and place within the window system. ATTR_GEN_WINDOW_ACCEPT_INK_EVEN_IF_NOT_FOCUSED, ATTR_GEN_WINDOW_KBD_OVERRIDE, and ATTR_GEN_WINDOW_KBD_POSITION affect how input flows within a generic window. For more information, see Window Management .
Hints to the specific UI suggest added functionality to your application, and are prefaced with
HINT_
(such as
HINT_SEEK_REPLY_BAR
). Hints may also have data structures attached to them. There are a large number of pre-defined hints with
GenClass
. See Hints to the Specific UI
for details on the operation of hints.
Many of the hints provided in
GenClass
manage the geometry of generic objects. For complete information on these hints, see the Managing UI Geometry chapter.
Code Display 2-3 Geometry Hints
/* These hints are explained within the Geometry Management chapter. */
@vardata void HINT_DONT_ALLOW_CHILDREN_TO_WRAP; @vardata void HINT_ALLOW_CHILDREN_TO_WRAP; @vardata word HINT_WRAP_AFTER_CHILD_COUNT; @vardata word HINT_WRAP_AFTER_CHILD_COUNT_IF_VERTICAL_SCREEN;
@vardata void HINT_BOTTOM_JUSTIFY_CHILDREN; @vardata void HINT_LEFT_JUSTIFY_CHILDREN; @vardata void HINT_RIGHT_JUSTIFY_CHILDREN; @vardata void HINT_TOP_JUSTIFY_CHILDREN;
@vardata void HINT_FULL_JUSTIFY_CHILDREN_HORIZONTALLY; @vardata void HINT_FULL_JUSTIFY_CHILDREN_VERTICALLY; @vardata void HINT_DONT_FULL_JUSTIFY_CHILDREN;
@vardata SpecSizeSpec HINT_CUSTOM_CHILD_SPACING; @vardata SpecSizeSpec HINT_CUSTOM_CHILD_SPACING_IF_LIMITED_SPACE; @vardata void HINT_DONT_INCLUDE_ENDS_IN_CHILD_SPACING; @vardata void HINT_INCLUDE_ENDS_IN_CHILD_SPACING; @vardata void HINT_MINIMIZE_CHILD_SPACING;
@vardata void HINT_LEFT_JUSTIFY_MONIKERS; @vardata void HINT_CENTER_MONIKER; @vardata void HINT_DO_NOT_USE_MONIKER; @vardata void HINT_ALIGN_LEFT_MONIKER_EDGE_WITH_CHILD;
@vardata void HINT_CENTER_CHILDREN_HORIZONTALLY; @vardata void HINT_CENTER_CHILDREN_ON_MONIKERS; @vardata void HINT_CENTER_CHILDREN_VERTICALLY;
@vardata optr HINT_ALIGN_LEFT_EDGE_WITH_OBJECT;
@reloc HINT_ALIGN_LEFT_EDGE_WITH_OBJECT, 0, optr;
@vardata optr HINT_ALIGN_TOP_EDGE_WITH_OBJECT;
@reloc HINT_ALIGN_TOP_EDGE_WITH_OBJECT, 0, optr;
@vardata optr HINT_ALIGN_RIGHT_EDGE_WITH_OBJECT;
@reloc HINT_ALIGN_RIGHT_EDGE_WITH_OBJECT, 0, optr;
@vardata optr HINT_ALIGN_BOTTOM_EDGE_WITH_OBJECT;
@reloc HINT_ALIGN_BOTTOM_EDGE_WITH_OBJECT, 0, optr;
@vardata CompSizeHintArgs HINT_FIXED_SIZE; @vardata CompSizeHintArgs HINT_INITIAL_SIZE; @vardata CompSizeHintArgs HINT_MAXIMUM_SIZE; @vardata CompSizeHintArgs HINT_MINIMUM_SIZE; @vardata void HINT_SIZE_WINDOW_AS_DESIRED;
@vardata void HINT_DRAW_IN_BOX;
@vardata void HINT_EXPAND_HEIGHT_TO_FIT_PARENT; @vardata void HINT_EXPAND_WIDTH_TO_FIT_PARENT;
@vardata void HINT_MAKE_REPLY_BAR;
@vardata void HINT_NO_TALLER_THAN_CHILDREN_REQUIRE; @vardata void HINT_NO_WIDER_THAN_CHILDREN_REQUIRE;
@vardata void HINT_ORIENT_CHILDREN_HORIZONTALLY; @vardata void HINT_ORIENT_CHILDREN_VERTICALLY; @vardata void HINT_ORIENT_CHILDREN_ALONG_LARGER_DIMENSION; @vardata void HINT_SAME_ORIENTATION_AS_PARENT;
@vardata void HINT_PLACE_MONIKER_ABOVE; @vardata void HINT_PLACE_MONIKER_BELOW; @vardata void HINT_PLACE_MONIKER_TO_LEFT; @vardata void HINT_PLACE_MONIKER_TO_RIGHT; @vardata void HINT_PLACE_MONIKER_ALONG_LARGER_DIMENSION; @vardata void HINT_NO_BORDER_ON_MONIKERS
@vardata void HINT_SEEK_MENU_BAR; @vardata void HINT_AVOID_MENU_BAR;
@vardata void HINT_SEEK_REPLY_BAR;
@vardata void HINT_SEEK_X_SCROLLER_AREA; @vardata void HINT_SEEK_Y_SCROLLER_AREA;
@vardata void HINT_SEEK_LEFT_OF_VIEW; @vardata void HINT_SEEK_TOP_OF_VIEW; @vardata void HINT_SEEK_RIGHT_OF_VIEW; @vardata void HINT_SEEK_BOTTOM_OF_VIEW;
@vardata void HINT_SEEK_TITLE_BAR_LEFT; @vardata void HINT_SEEK_TITLE_BAR_RIGHT;
@vardata void HINT_USE_INITIAL_BOUNDS_WHEN_RESTORED;
@vardata void HINT_DIVIDE_WIDTH_EQUALLY; @vardata void HINT_DIVIDE_HEIGHT_EQUALLY;
@vardata void HINT_KEEP_INITIALLY_ONSCREEN; @vardata void HINT_DONT_KEEP_INITIALLY_ONSCREEN; @vardata void HINT_KEEP_PARTIALLY_ONSCREEN; @vardata void HINT_DONT_KEEP_PARTIALLY_ONSCREEN; @vardata void HINT_KEEP_ENTIRELY_ONSCREEN; @vardata void HINT_KEEP_ENTIRELY_ONSCREEN_WITH_MARGIN;
@vardata void HINT_POPS_UP_TO_RIGHT; @vardata void HINT_POPS_UP_BELOW;
@vardata void HINT_NOT_MOVABLE;
@vardata SpecWinSizePair HINT_POSITION_WINDOW_AT_RATIO_OF_PARENT; @vardata void HINT_POSITION_WINDOW_AT_MOUSE;
@vardata void HINT_WINDOW_NO_TITLE_BAR; @vardata void HINT_WINDOW_NO_SYS_MENU; @vardata void HINT_WINDOW_MINIMIZE_TITLE_BAR; @vardata void HINT_WINDOW_ALWAYS_DRAW_WITH_FOCUS;
@vardata void HINT_STAGGER_WINDOW; @vardata void HINT_CENTER_WINDOW; @vardata void HINT_TILE_WINDOW;
@vardata void HINT_EXTEND_WINDOW_TO_BOTTOM_RIGHT; @vardata void HINT_EXTEND_WINDOW_NEAR_BOTTOM_RIGHT;
@vardata SpecWinSizePair HINT_SIZE_WINDOW_AS_RATIO_OF_PARENT; @vardata SpecWinSizePair HINT_SIZE_WINDOW_AS_RATIO_OF_FIELD; @vardata void HINT_WINDOW_NO_CONSTRAINTS;
@vardata SpecWinSizePair HINT_POSITION_ICON_AS_RATIO_OF_FIELD;
Other hints in
GenClass
do not affect geometry. These hints are listed below and are explained within this chapter. Within
GenClass
, some hints are internal and are not listed in this code display.
Code Display 2-4 Hints Explained Within This Chapter
/* These hints are explained within this chapter (or they are self-explanatory). */
@vardata void HINT_FREQUENTLY_USED; @vardata void HINT_INFREQUENTLY_USED; @vardata void HINT_AN_ADVANCED_FEATURE;
@vardata void HINT_DEFAULT_DEFAULT_ACTION; @vardata void HINT_ENSURE_TEMPORARY_DEFAULT; @vardata void HINT_PREVENT_DEFAULT_OVERRIDES;
@vardata void HINT_SAME_CATEGORY_AS_PARENT;
@vardata void HINT_USE_TEXT_MONIKER; @vardata void HINT_USE_ICONIC_MONIKER;
@vardata void HINT_DEFAULT_FOCUS; @vardata void HINT_DEFAULT_TARGET; @vardata void HINT_DEFAULT_MODEL;
@vardata void HINT_PRESERVE_FOCUS; @vardata void HINT_DO_NOT_PRESERVE_FOCUS;
@vardata void HINT_GENERAL_CONSUMER_MODE;
@vardata void HINT_NEVER_ADOPT_MENUS; @vardata void HINT_ALWAYS_ADOPT_MENUS;
@vardata void HINT_NAVIGATION_ID; @vardata void HINT_NAVIGATION_NEXT_ID
@vardata void HINT_DISMISS_WHEN_DISABLED;
@vardata void HINT_TOOLBOX;
@vardata void HINT_SHOW_SHORTCUT; @vardata void HINT_DONT_SHOW_SHORTCUT; @vardata void HINT_DRAW_SHORTCUT_BELOW;
@vardata void HINT_CAN_CLIP_MONIKER_WIDTH; @vardata void HINT_CAN_CLIP_MONIKER_HEIGHT; @vardata void HINT_SHOW_ENTIRE_MONIKER;
@vardata BackgroundColors HINT_GADGET_BACKGROUND_COLORS; @vardata word HINT_GADGET_TEXT_COLOR;
@vardata SystemAttrs HINT_IF_SYSTEM_ATTRS; @vardata void HINT_ENDIF; @vardata void HINT_ELSE;
HINT_FREQUENTLY_USED, HINT_INFREQUENTLY_USED, and HINT_AN_ADVANCED_FEATURE are descriptive hints that describe the generic object's role within the UI. It is, of course, left up to the specific UI to implement any special behavior based on these hints.
HINT_DEFAULT_DEFAULT_ACTION , HINT_ENSURE_TEMPORARY_DEFAULT, and HINT_PREVENT_DEFAULT_OVERRIDES affect the default activation of objects within the UI. Objects with default activation can be activated indirectly (e.g., pressing the ENTER key within a dialog box activates a default trigger). For more information, see Default Actions .
HINT_SAME_CATEGORY_AS_PARENT indicates to the specific UI that this object should be treated in the same manner as its parent. Currently, this hint only affects GenInteractions. By default, GIV_SUB_GROUP GenInteractions within a GIV_POPUP menu have separator lines drawn around them to set them apart from other children. This hint removes those lines.
HINT_USE_TEXT_MONIKER and HINT_USE_ICONIC_MONIKER indicates that the generic object should choose either a text moniker or an iconic moniker if there exists a choice within the object's moniker list. Currently, these hints are not implemented.
HINT_DEFAULT_FOCUS , HINT_DEFAULT_TARGET, and HINT_DEFAULT_MODEL specify that the generic object is the default focus, target, or model node at this level in the application. HINT_PRESERVE_FOCUS and HINT_DO_NOT_PRESERVE_FOCUS affect how the focus node changes after an object's activation. For a complete discussion of the focus and target hierarchies, see the Input chapter.
HINT_GENERAL_CONSUMER_MODE
instructs the specific UI to show the object in GCM mode. This hint takes an argument of type
GeneralConsumerModeFlags
; this record contains two three-bit flags: GCMF_LEFT_ICON and GCMF_RIGHT_ICON, which specify which icon to use on both the left and right sides of the title bar. Each icon must be of type
GCMIcon
; current types are GCMI_NONE, GCMI_EXIT, and GCMI_HELP.
HINT_NEVER_ADOPT_MENUS and HINT_ALWAYS_ADOPT_MENUS affect the behavior of menus placed within a GenDisplay. Menus can either sit within the GenDisplay or appear in the associated GenPrimary when that GenDisplay is the target. Menus within GenDisplays are discouraged, however, as they are a fairly advanced UI metaphor.
HINT_NAVIGATION_ID and HINT_NAVIGATION_NEXT_ID allow the field navigation path within a windowed object. HINT_NAVIGATION_NEXT_ID sets the object to navigate to from the current object. An object with a matching HINT_NAVIGATION_ID must exist. For more information, see Keyboard Navigation Hints .
HINT_DISMISS_WHEN_DISABLED instructs the specific UI to dismiss the object when it is no longer fully enabled. This is typically useful for independently-displayable windows that should be dismissed in such cases.
HINT_TOOLBOX indicates that the generic object and all objects below it in the visual hierarchy are part of a "toolbox" and should draw themselves appropriately. Objects in toolboxes are typically much smaller than other components. For more information on toolboxes, see the Menus and Dialogs chapter.
HINT_SHOW_SHORTCUT , HINT_DONT_SHOW_SHORTCUT, and HINT_DRAW_SHORTCUT_BELOW affect the display of keyboard accelerators for generic objects. For more information, see Keyboard Accelerators .
HINT_CAN_CLIP_MONIKER_WIDTH and HINT_CAN_CLIP_MONIKER_HEIGHT instruct the specific UI to clip the object's moniker height or width if not enough space is provided for them. Objects with HINT_SHOW_ENTIRE_MONIKER will force the object to leave enough space to show its entire moniker, if possible.
HINT_GADGET_BACKGROUND_COLORS
causes grouping objects in toolboxes to draw custom background colors. The hint takes an argument of type
BackgroundColors
. Two colors can each be chosen for both the unselected state and the selected state; they will be blended together depending on the state of the object. If both colors are set to the same value, a solid color results. HINT_GADGET_TEXT_COLOR
selects the text color of a visual moniker, typically within a toolbox. This hint takes an argument of type
TextColors
.
HINT_IF_SYSTEM_ATTRS
, HINT_ENDIF, and HINT_ELSE may be used together to conditionally add hints to an object based on certain system criteria. 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 deleted. For more information, see System Attributes
.
Remember that these vardata entries are hints; they can be ignored by the specific UI and their implementation varies from object to object. Some hints, for example, are only relevant for certain object classes. Your mileage may vary.
GEOS SDK TechDocs
|
| 2.1 Instance Fields
| 3 GenClass Basics