GenClass: 7.2 Special Message Passing: Generic Upward Queries

| Up: GEOS SDK TechDocs | Up | Prev: 7.1 Parent and Child Message Passing | Next: 7.3 Object-Specific Queries 
MSG_GEN_GUP_CALL_OBJECT_OF_CLASS, MSG_GEN_GUP_SEND_TO_OBJECT_OF_CLASS, MSG_GEN_GUP_TEST_FOR_OBJECT_OF_CLASS, MSG_GEN_GUP_FIND_OBJECT_OF_CLASS, MSG_GEN_GUP_QUERY, MSG_GEN_GUP_INTERACTION_COMMAND, MSG_GEN_GUP_FINISH_QUIT

GenClass provides the capability to search up the generic tree beyond the parent. Using the following messages, the UI can continue passing classed events up the generic tree until it reaches an object of the proper class. This behavior is known as a Generic UPward query (GUP).

For example, if you specify GenInteractionClass in your classed event and later send a GUP message to any object in the generic tree, the stored message will be handled at the first available GenInteraction object it encounters.

MSG_GEN_GUP_CALL_OBJECT_OF_CLASS performs a GUP, returning values from the passed message. You must cast the return values into the proper type based on the return values of the passed message. MSG_GEN_GUP_SEND_TO_OBJECT_OF_CLASS performs a GUP but does not allow return values.

MSG_GEN_GUP_TEST_FOR_OBJECT_OF_CLASS performs a GUP whose sole function is to search for the existence of an object of the specified class among the object's parents.

MSG_GEN_GUP_FIND_OBJECT_OF_CLASS performs a GUP searching for any object of the passed class, but it also returns the optr of the object found. Note that it is unwise to later use this optr as the generic tree may have changed.

MSG_GEN_GUP_CALL_OBJECT_OF_CLASS

void	MSG_GEN_GUP_CALL_OBJECT_OF_CLASS(
        EventHandle event);

This message performs a generic upward query, passing the classed event upward until it reaches an object of the passed class. This message allows return values and should be cast into whatever return values are expected of the passed message. This is most easily done by enclosing the message sent within parentheses.

An object of the expected class should be present or the event will not be delivered to any object. To check for the existence of such a class, use MSG_GEN_GUP_TEST_FOR_OBJECT_OF_CLASS .

Source: Unrestricted.

Destination: Any generic object.

Parameters: event The classed event to deliver to an object up the generic tree.

Return: The return values of the classed event (cast to the proper type).

Interception: Generally not intercepted. Custom gadgets may handle to supplement or supersede default functionality.

MSG_GEN_GUP_SEND_TO_OBJECT_OF_CLASS

void	MSG_GEN_GUP_SEND_TO_OBJECT_OF_CLASS(
        EventHandle event);

This message performs a generic upward query, passing the classed event upward until it reaches an object of the described class. Since this message performs a send, it does not allow return values. An object of the expected class should be present; otherwise, the event will not be delivered to any object. To check for the existence of such a class, use MSG_GEN_GUP_TEST_FOR_OBJECT_OF_CLASS .

Source: Unrestricted.

Destination: Any generic object.

Parameters: event The classed event to deliver to an object up the generic tree.

Interception: Generally not intercepted. Custom gadgets may handle to supplement or supersede default functionality.

Code Display 2-29 Nesting Classed Events

/* The following method can be used by any object in the generic tree below the
 * primary to set all menus and GenInteractions below the primary window enabled
 * all at once. */
@method MyProcessClass, MSG_ENABLE_ALL_MY_MENUS {
    EventHandle menuEvent, primaryEvent;
/* The first classed event (menuEvent) encapsulates MSG_GEN_SET_ENABLED for any
 * object of GenInteractionClass (typically menus). The @record keyword
 * encapsulates the message to be handled by GenInteractionClass. The
 * VisUpdateMode delays updates via the Application queue to avoid constant visual
 * updates and "flashing." */
    menuEvent = @record GenInteractionClass::MSG_GEN_SET_ENABLED( 
					VUM_DELAYED_VIA_APP_QUEUE);
/* The second classed event binds MSG_GEN_SEND_TO_CHILDREN to the GenPrimaryClass.
 * Sending this message to the GenPrimary will send the menuEvent to all
 * its children. In this case, sending this event to the Primary will send
 * MSG_GEN_SET_ENABLED to all its GenInteraction children. */
    primaryEvent = @record GenPrimaryClass::MSG_GEN_SEND_TO_CHILDREN(menuEvent);
/* Finally, to send this message to the GenPrimary from any object below the
 * GenPrimary, simply send a MSG_GEN_GUP_SEND_TO_OBJECT_OF_CLASS with the
 * PrimaryEvent above. The GUP message will send the message
 * MSG_GEN_SEND_TO_CHILDREN up the generic tree until it encounters the GenPrimary,
 * at which point the Primary will send the MenuEvent MSG_GEN_SEND_TO_CHILDREN to
 * all its GenInteraction children. */
    @send @MyObject::MSG_GEN_GUP_SEND_TO_OBJECT_OF_CLASS(primaryEvent);
}

MSG_GEN_GUP_TEST_FOR_OBJECT_OF_CLASS

Boolean	MSG_GEN_GUP_TEST_FOR_OBJECT_OF_CLASS(
        ClassStruct  *class);

This message searches up the generic tree for any object of the specific class. This message is useful for testing the existence of required classes before sending MSG_GEN_GUP_CALL_OBJECT_OF_CLASS and MSG_GEN_GUP_SEND_TO_OBJECT_OF_CLASS .

Source: Unrestricted.

Destination: Any generic object.

Parameters: class ClassStruct to search for among the object's parents.

Return: Will return true if the class is found, false if not.

Interception: Generally not intercepted. Custom gadgets may handle to supplement or supersede default functionality.

MSG_GEN_GUP_FIND_OBJECT_OF_CLASS

optr	MSG_GEN_GUP_FIND_OBJECT_OF_CLASS(
        ClassStruct  *class);

This message performs a function similar to that of MSG_GEN_GUP_TEST_FOR_OBJECT_OF_CLASS , but it returns the optr of the class found, if any. This optr can then be used as the recipient of other messages. You should not use an optr returned by this message at a later time, as the object may have been removed.

Source: Unrestricted.

Destination: Any generic object.

Parameters: class ClassStruct to search for.

Return: The optr of the object of the requested class, or a null optr if no such object was found.

Interception: Generally not intercepted. Custom gadgets may handle to supplement or supersede default functionality.

MSG_GEN_GUP_QUERY

void 	MSG_GEN_GUP_QUERY(
        GenReturnParams 		*retValue,
        word 		queryType);

This message is used to query up the generic composite tree.

Source: Anyone.

Destination: Any usable generic object, though only certain objects will answer certain queries.

Parameters: retValue Structure to hold return values.

queryType
GenUpwardQueryType .

The GenUpwardQueryType should be one of the following:

GUQT_DELAYED_OPERATION
This query type determines if a gadget should be operating in "delayed mode," i.e., whether it should wait for a MSG_GEN_APPLY before sending notification to its output, or whether it should send notification whenever it changes state.
GUQT_FIELD
Returns field object in GRP_ cx :GRP_ dx and window (if realized) handle in GRP_ bp . This is a reasonably safe thing to do, since the field window will remain open until all applications within the field are shut down. Only field objects or substitutes for them should intercept this message.
GUQT_SCREEN
Returns screen object in GRP_ cx :GRP_ dx and window (if any) handle in GRP_ bp . This is a reasonably safe thing to do, since the screen window will remain open until all applications within the field are shut down. Screen object being returned will be default screen for the field.

Return: Nothing returned explicitly. retValue struct filled with values which depend on query type.

Structures: 

  typedef struct {
	word 	GRP_ax;
	word 	GRP_bp;
	word 	GRP_cx;
	word 	GRP_dx;
} GenReturnParams;

MSG_GEN_GUP_INTERACTION_COMMAND

Boolean 	MSG_GEN_GUP_INTERACTION_COMMAND(
        InteractionCommand 		command);

This message travels up the generic tree until it reaches a non-GIT_ORGANIZATIONAL GenInteraction. Once there, it performs the indicated InteractionCommand . See InteractionCommand declaration for the different command types and how specific user interfaces interpret the commands. If the GenInteraction is a dialog brought up with UserDoDialog() , InteractionCommand will be returned to the caller, after performing the command, via MSG_GEN_INTERACTION_RELEASE_BLOCKED_THREAD_WITH_RESPONSE .

Source: Unrestricted. Normally sent by a MSG_GEN_INTERACTION_ACTIVATE_COMMAND handler or by a custom trigger's action message handler to perform some default command after perform some application-specific function.

Destination: Any generic object. Will travel up generic tree, stopping at first non organizational interaction.

Parameters: command Standard InteractionCommand.

Return: Returns true if handled.

Interception: Not normally intercepted.

MSG_GEN_GUP_FINISH_QUIT

void 	MSG_GEN_GUP_FINISH_QUIT(
        Boolean 		abortFlag, 
        Boolean 		notifyParent);

Message to be used by nodes that implement a GCN active list. This should be used if MSG_META_QUIT is handled and sent to the active list items by that node. When a node has finished sending a MSG_META_QUIT to the active list or if the quit is aborted, this allows the notification of the above node in the generic tree.

Source: Sent by active list nodes that implement quit mechanism.

Destination: Any generic object involved in quit mechanism.

Parameters: abortFlag Pass true to abort. This will be passed on to MSG_META_FINISH_QUIT .

notifyParent
Pass true to notify parent of finished quit sequence.

Interception: Generally not intercepted. Default handler sends MSG_META_FINISH_QUIT to self, then sends to generic parent if flag indicates such. MSG_META_FINISH_QUIT is normally the message to intercept to know when a quit is aborted or finished.

| Up: GEOS SDK TechDocs | Up | Prev: 7.1 Parent and Child Message Passing | Next: 7.3 Object-Specific Queries