GEOS SDK TechDocs
|
| 
5.3 Using Focus
| 
5.5 Using Model
The specific UI handles most of the manipulation of the target hierarchy. Most specific UIs interpret keyboard and mouse events and know when to switch the target from one object to another. For example, in OSF/Motif, clicking on a window will switch the target to that window from the previous target window. Before the mouse is clicked, however, the target exclusive of that window will not change. In other specific UIs which incorporate real-estate cursor behavior, merely moving the cursor over a window will transfer the target to that window.
By default, an application will come up with certain objects having the target exclusive within their target levels. This allows the user to immediately begin typing or operating on data. For an object to grab the default exclusive, it must first be targetable. A targetable object can be any child of a valid target node. Valid nodes for the target hierarchy are:
In addition, however, a generic object must be set GA_TARGETABLE in its
GI_attrs
field to become a valid target object. This bit is set by default for the following classes:
If you wish a generic object to be targetable and it does not appear in this list, set it GA_TARGETABLE. If the object does not by default appear as a valid node in the Target hierarchy (such as for a custom gadget), you must subclass the object and add target instance fields and message handlers.
For all targetable objects within a target exclusive level, the target will be granted to the object with
HINT_DEFAULT_TARGET
in its instance data. If no object has this hint at a particular target level, then the target will be granted to the first targetable object at that level.
To grab the target exclusive in its level, a node should send itself
MSG_META_GRAB_TARGET_EXCL
. The default handler for this message grabs the target exclusive for the object from its parent and forces any other object on the caller's level to give the target up. The active exclusive will not be granted unless the caller is part of the active path after the grab.
When another node grabs the target exclusive, the node currently having the exclusive on that level must give it up.
MSG_META_RELEASE_TARGET_EXCL
releases the target exclusive for the other node.
Note that these messages only modify the exclusive at a single level. Therefore, they only affect the target optr of the parent's node; further up the target hierarchy there is no effect. Changing the target exclusive of an object will only change the direction of the target path if all parents of the new exclusive are also target exclusives.
MSG_META_GET_TARGET_EXCL
may be sent to any targetable composite node to get the optr of the node's child having the exclusive. This message may be used even on nodes in the inactive path.
When an object gains the active target exclusive and is a node in the active path, it receives
MSG_META_GAINED_TARGET_EXCL
. This indicates to the object that it will receive all keyboard input as the active keyboard object.
At some point later, when the object has lost the target exclusive, it will receive
MSG_META_LOST_TARGET_EXCL
.
Frequently, you may wish to send messages to objects in the active Target path. The easiest way to deliver a message to an object in the target hierarchy is to use
MSG_META_SEND_CLASSED_EVENT
with the
TravelOption
TO_TARGET. To send a message to the leaf node of the active path, send this message with a null class. The message will be sent down the hierarchy until it reaches the leaf object, where it will be processed. (See Delivering Messages to the Target
.)
This approach is desirable over using
MSG_META_GET_TARGET_EXCL
to return an optr for later use, as the system may have corrupted the optr in the meantime.
Code Display 11-3 Delivering Messages to the Target
@method MyProcessClass, MSG_SEND_MESSAGE_TO_TARGET_INTERACTION {
EventHandle event;
/* The classed event is recorded to be handled by the first object of class
* GenInteractionClass. */
event = @record GenTextClass::MSG_TEST_MESSAGE();
/* This message is then sent to the GenApplication object, from which it
* will travel down the target hierarchy until handled at the
* GenInteraction level. */
@call MyApplication::MSG_META_SEND_CLASSED_EVENT(event, TO_TARGET);
}
/* You may also declare an object with the TravelOption TO_APP_TARGET. This will * send the message to the application object and then down the target hierarchy. */
@object GenTriggerClass MyTargetTrigger = {
GI_visMoniker = "Send test message to the target";
GTI_actionMsg = MSG_TEST_MESSAGE;
GTI_destination = (TO_APP_TARGET);
ATTR_GEN_DESTINATION_CLASS = { (ClassStruc *)&GenTextClass };
}
/* To send a message to the target leaf node, use a null class. */
@method MyProcessClass, MSG_SEND_TEST_TO_TARGET_LEAF {
EventHandle event;
/* A classed event with the class of null is recorded. */
event = @record null::MSG_TEST_MESSAGE();
/* This event is sent to the GenApplication, where it will travel down the
* target hierarchy to the leaf object, where it will be handled. */
@call MyApplication::MSG_META_SEND_CLASSED_EVENT(event, TO_TARGET);
}
/* As an alternative, an object could be set to deliver its message to the
* leaf target node of the application. */
@object GenTriggerClass MyTargetLeafTrigger = {
GI_visMoniker = "Send test message to the target leaf object";
GTI_actionMsg = MSG_TEST_MESSAGE;
GTI_destination = (TO_APP_TARGET);
/* An ATTR_GEN_DESTINATION_CLASS of zero specifies a null class. */
ATTR_GEN_DESTINATION_CLASS = 0;
}
GEOS SDK TechDocs
|
| 5.3 Using Focus
| 5.5 Using Model