GenClass: 3.4 GenClass Basics: Attributes

GEOS SDK TechDocs

3.3 Keyboard Accelerators

3.5 States

GI_attrs, MSG_GEN_GET_ATTRIBUTES, MSG_GEN_SET_ATTRS

The GI_attrs attribute is a record specifying how an object will behave under various circumstances. In some cases, the GI_attrs instance field indicates that an object may initiate a busy state within the application. Several attributes only affect how an object will behave during activation. Prior to an object's activation, some of these attributes will not affect the object's behavior.

GA_SIGNAL_INTERACTION_COMPLETE

This flag instructs the UI that an Interaction has been completed. The specific UI may then decide whether to dismiss the Interaction or not. Most often, this attribute is attached to a GenTrigger within an independently displayable GenInteraction (dialog box). This attribute is useful for dismissing temporary dialogs that request information from the user. This attribute will cause the generic object to send a MSG_GEN_GUP_INTERACTION_COMMAND to its generic parent with the InteractionCommand IC_INTERACTION_COMPLETE. This message is then passed up the generic tree until it reaches an appropriate Interaction. See the Menus and Dialog Boxes chapter for more information.

GA_INITIATES_BUSY_STATE
This flag instructs the UI to mark the application as busy whenever the generic object is activated. You should only set this attribute for objects that may initiate long operations. This attribute requests that the UI visually change the cursor to show that the application is busy. (In OSF/Motif this is represented by an hourglass.) When the application finishes its operation, the cursor will revert to its former state. This attribute causes the object to send MSG_GEN_APPLICATION_MARK_BUSY to the object's application object along with MSG_GEN_APPLICATION_MARK_NOT_BUSY sent via the process' event queue. This allows the system to process the first message (showing the busy cursor) and only process the second message (removing the busy cursor) after the application finishes its current operation. (If the action is processed quickly, the cursor will often not appear.) The busy state cursor is only reflected in the current application; if the cursor roams outside the application bounds, the default behavior will occur.

GA_INITIATES_INPUT_HOLD_UP
This flag instructs the UI to mark the application as busy and to delay processing input messages until the UI and Application queues have been flushed. The application will then complete its current operation before beginning to process its input events. You should set this attribute when an object's activation may modify the UI, thereby preventing the user from clicking on objects that may become invalid after the operation. This attribute immediately sends a MSG_GEN_APPLICATION_HOLD_UP_INPUT to the application object along with a MSG_GEN_APPLICATION_RESUME_INPUT delayed via the process' event queue. This functionality is only reflected in the current application; if the cursor roams outside the application bounds, the default behavior will occur.

GA_INITIATES_INPUT_IGNORE

This flag instructs the UI to mark the application as busy and to completely ignore all subsequent input events to the application. The application will enter a modal state, meaning that all other application events will be ignored until the UI and Application queues are flushed. Usually, this state is conveyed to the user by broadcasting an audible beep whenever an input event is attempted. The generic object will immediately send a MSG_GEN_APPLICATION_IGNORE_INPUT to the application object along with a MSG_GEN_APPLICATION_ACCEPT_INPUT delayed via the application queue. This functionality is only reflected in the current application; if the cursor roams outside the application bounds, the default behavior will occur.

GA_READ_ONLY

This flag indicates that this object's only function is to display information to the user; the user will not be able to interact with this object. This attribute is set most often in lists or text objects.

GA_KBD_SEARCH_PATH

This flag indicates that this generic branch contains objects with keyboard accelerators and should therefore be searched when evaluating such events. This attribute bit is set internally by the system. There should be no need for your application to deal with this attribute directly.

GA_TARGETABLE

This flag indicates that this object is targetable and is eligible to receive the target exclusive within its target level. Most specific UIs will automatically grab the target for this object whenever the user interacts with it. This attribute is set by default within the following classes:

GenField

GenApplication
GenPrimary
GenDisplayControl
GenDisplay
GenView

GA_NOTIFY_VISIBILITY

This flag indicates that this object should send notification when it becomes visible and not visible. Objects thus will send MSG_GEN_APPLICATION_VISIBILITY_NOTIFICATION

Code Display 2-15 Using GI_attrs in a Dialog Box

@object GenInteractionClass MyDialogBox = {
    GI_comp = @MyButton, @MyOtherButton;
    GII_visibility = GIV_DIALOG;				/* build this Interaction as a dialog box.*/
}

@object GenTriggerClass MyButton = {
    GTI_actionMsg = MSG_MY_SPECIAL_MESSAGE;
    GTI_destination = process;
	/* MyButton, when activated, will send the message above to the
	 * process object. Only when that happens will it activate the
	 * behavior within the GI_attrs instance data below. */
    GI_attrs = @default | 
	/* This flag will close the MyDialogBox object */
	GA_SIGNAL_INTERACTION_COMPLETE |
	/* This flag will set the application to ignore all input events while the
	 * message above is processed. */
	GA_INITIATES_INPUT_IGNORE;
}

MSG_GEN_GET_ATTRIBUTES

byte	MSG_GEN_GET_ATTRIBUTES();

This message retrieves the GI_attrs instance data for the object the message is sent to. This message returns a byte length bitfield.

Source: Unrestricted.

Destination: Any generic object.

Return: Byte length GI_ attrs bitfield.

Interception: Generally not intercepted.

MSG_GEN_SET_ATTRS

void	MSG_GEN_SET_ATTRS(
        byte attrsToSet,
        byte attrsToClear);

This message sets the recipient's GI_attrs field. This message takes two arguments: the attributes to set and the attributes to clear. There is no need to repeat attributes that have been previously set. Note that these attributes will not take effect until the object is activated in the normal manner. (Sending this message does not in itself initiate the activity described).

You should only send this message while an object is not GS_USABLE, because these attributes are only checked when an object is specifically built. Setting the attributes of a GS_USABLE object may cause an error.

Source: Unrestricted.

Destination: Any non-usable generic object.

Parameters: attrsToSet GenAttributes to set in GI_ attrs .

attrsToClear GenAttributes to clear in GI_ attrs .

Interception: Generally not intercepted.

Code Display 2-16 Conditionally Altering the GI_attrs Field

@method MyProcessClass, MSG_DO_CUSTOM_ATTRS {
    byte MyAttrs;

	/* retrieve the GI_attrs field */
    MyAttrs = @call @MyObject::MSG_GEN_GET_ATTRIBUTES();

	/* If the GA_COMPLETES_INTERACTION bit is set, then set it 
	 * GA_INITIATES_BUSY_STATE also. Otherwise set it
	 * GA_INITIATES_INPUT_IGNORE. */

    if (MyAttrs & GA_COMPLETES_INTERACTION){
	@call @MyObject::MSG_GEN_SET_NOT_USABLE();
	@call @MyObject::MSG_GEN_SET_ATTRS(GA_INITIATES_BUSY_STATE, 0);

	/* Note that setting an object's GA_INITIATES_BUSY_STATE attribute will
	 * not in itself initiate a busy state. That object will only issue a busy
	 * state when it is activated in the normal fashion. */

    @call @MyObject::MSG_GEN_SET_USABLE();
    } else {
	@call @MyObject::MSG_GEN_SET_NOT_USABLE();
	@call @MyObject::MSG_GEN_SET_ATTRS(GA_INITITATES_INPUT_IGNORE, 0);
	@call @MyObject::MSG_GEN_SET_USABLE();
    }
}

GEOS SDK TechDocs

3.3 Keyboard Accelerators

3.5 States