GEOS SDK TechDocs
|
| 
5.2 Common Hierarchy Basics
| 
5.4 Using Target
The specific UI handles most of the manipulation of the focus hierarchy. Most specific UIs interpret keyboard and mouse events and know when to switch the focus from one object to another. For example, in OSF/Motif, clicking on a window will switch the focus to that window from the previous focus window. Before the mouse is clicked, however, the focus 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 focus to that window.
By default, an application will come up with certain objects having the focus exclusive within their focus 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 focusable. A focusable object can be any child of a valid focus node. Valid nodes for the focus hierarchy are:
Note that a GenView must have the GVA_FOCUSABLE bit set in its GVI_
attrs
field. If an object you need to act as a focus node is not in the above list (for example, a custom gadget), you must subclass the object and add instance fields and message handlers to handle focus functionality.
If an independently displayable object is focusable, the focus will be given to the object which is visually "on top" of all other objects. For all other objects within a focus exclusive level, the focus will be granted to the object with
HINT_DEFAULT_FOCUS
in its instance data. If no objects have this hint at a particular focus level, then the focus will be granted to the first focusable child.
To grab the focus exclusive in its level, a node should send itself
MSG_META_GRAB_FOCUS_EXCL
. The default handler for this message grabs the focus exclusive for the object from its parent and forces any other object on the caller's level to give the focus 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 focus exclusive, the node currently having the exclusive on that level must give it up.
MSG_META_RELEASE_FOCUS_EXCL
releases the focus exclusive for the other node.
Note that these messages only modify the exclusive at a single level. Therefore, they only affect the focus optr of the parent's node; further up the focus hierarchy there is no effect. Changing the focus exclusive of an object will only change the direction of the focus path if all parents of the new exclusive are also focus exclusives.
MSG_META_GET_FOCUS_EXCL
may be sent to any focusable 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 focus exclusive and is a node in the active path, it receives
MSG_META_GAINED_FOCUS_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 focus exclusive, it will receive
MSG_META_LOST_FOCUS_EXCL
.
Frequently, you may wish to send messages to objects in the active Focus path. The easiest way to deliver a message to an object in the focus hierarchy is to use
MSG_META_SEND_CLASSED_EVENT
with the
TravelOption
TO_APP_FOCUS. 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 Focus
.)
This approach is desirable over using
MSG_META_GET_FOCUS_EXCL
to return an optr for later use, as the system may have corrupted the optr in the meantime.
Code Display 11-2 Delivering Messages to the Focus
@method MyProcessClass, MSG_SEND_MESSAGE_TO_FOCUS_INTERACTION {
EventHandle event;
/* The classed event is recorded to be handled by the first object of class
* GenInteractionClass. */
event = @record GenInteractionClass::MSG_TEST_MESSAGE();
/* This message is then sent to the GenApplication object, from which it
* will travel down the focus hierarchy until handled at the
* GenInteraction level. */
@call MyApplication::MSG_META_SEND_CLASSED_EVENT(event, TO_FOCUS);
}
/* You may also declare an object with the TravelOption TO_APP_FOCUS. This will * send the message to the application object and then down the focus hierarchy. */
@object GenTriggerClass MyFocusTrigger = {
GI_visMoniker = "Send test message to the focus";
GTI_actionMsg = MSG_TEST_MESSAGE;
GTI_destination = (TO_APP_FOCUS);
ATTR_GEN_DESTINATION_CLASS = { (ClassStruc *)&GenInteractionClass };
}
/* To send a message to the focus leaf node, use a null class. */
@method MyProcessClass, MSG_SEND_TEST_TO_FOCUS_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
* focus hierarchy to the leaf object, where it will be handled. */
@call MyApplication::MSG_META_SEND_CLASSED_EVENT(event, TO_FOCUS);
}
/* As an alternative, an object could be set to deliver its message to the
* leaf focus node of the application. */
@object GenTriggerClass MyFocusLeafTrigger = {
GI_visMoniker = "Send test message to the focus leaf object";
GTI_actionMsg = MSG_TEST_MESSAGE;
GTI_destination = (TO_APP_FOCUS);
/* An ATTR_GEN_DESTINATION_CLASS of zero specifies a null class. */
ATTR_GEN_DESTINATION_CLASS = 0;
}
GEOS SDK TechDocs
|
| 5.2 Common Hierarchy Basics
| 5.4 Using Target