GEOS SDK TechDocs
|
| 
5.4 Using Target
| 
5.6 Extending the Hierarchies
In some cases, you may need to send or receive information from some object other than the focus or target. The Model hierarchy is provided as an alternative. In most cases, the model provides a means of pointing to data selections other than that pointed to by the Target hierarchy. Only use it if the target hierarchy cannot serve your needs.
The model of an application is used to identify objects that represent the actual data that can be selected by the user. Typically, these selections are either secondary selections or are not visible. The selections are frequently operated on with the use of menus, dialog boxes, or other UI gadgetry. Only one object at each model level may have the model "exclusive," and for an object to "have the Model" of an application, that object must have a continuous path of model exclusives up to the application object.
Only GenSystem, GenApplication, and the document control objects can be directly used in the Model hierarchy without any modifications. To use other objects in the Model hierarchy, you must first subclass those objects' classes and add an instance field and several message handlers pertaining to the Model hierarchy. Any object which is a valid target node can be subclassed in this manner.
By default, an application will come up with certain objects having the model exclusive within their model levels. This allows the user to immediately begin operating on data. For an object to grab the default exclusive, it must first be modelable. Only objects which are modelable may have the model exclusive. A modelable object can be any child of a valid model node. Valid nodes for the Model hierarchy are the same as for the Target hierarchy. However, a document control object must also be set GDCA_MODELABLE to grab the model exclusive. Remember that just because an object is a valid node does not mean it can exhibit the behavior of the Model hierarchy; you must subclass most objects for this to occur.
For objects within a model level, the model will be granted first to any object with
HINT_DEFAULT_MODEL
in its instance data. If no object has this hint at a particular model level, then the model will be granted to the first modelable object at that level.
The easiest way to deliver a message to an object in the active Model hierarchy is to use
MSG_META_SEND_CLASSED_EVENT
with the
TravelOption
TO_MODEL. To send a message to the leaf node in the Model hierarchy, send this message with a class of null. The message will be sent down the hierarchy until it reaches the leaf object, where it will be processed.
This approach is desirable over using
MSG_META_GET_MODEL_EXCL
to return an optr for later use as the system may have corrupted the optr in the meantime.
To modify the Model hierarchy, use
MSG_META_GRAB_MODEL_EXCL
.
To remove the model exclusive from an object without setting it to another object, use
MSG_META_RELEASE_MODEL_EXCL
. Note that these messages only modify the model exclusive of a single object. Therefore, they only affect the model pointer of the parent; further up the Model hierarchy there is no effect. Changing the model exclusive of an object will only change the direction of the model path if all ancestors of the new model exclusive are also model exclusives.
To check which model exclusive a composite points to, send it a
MSG_META_GET_MODEL_EXCL
. This message will return the optr of the model child. The returned object may not have the model properties, though, for the reasons above. Never send a message directly to the object returned by this method as it may have been changed in the meantime. Use
MSG_META_SEND_CLASSED_EVENT
with the
TravelOption
TO_MODEL instead.
Your application may also wish to be notified when an object either gains or loses its model properties.
Whenever an object in GEOS gains the model of the application--not just the model exclusive--it sends a
MSG_META_GAINED_MODEL_EXCL
to that object.
Similarly, if an object loses the model of an application--not just the model exclusive--the system sends a
MSG_META_LOST_MODEL_EXCL
to that object.
If your application needs to know when an object either gains or loses its model properties, intercept
MSG_META_GAINED_MODEL_EXCL
and
MSG_META_LOST_MODEL_EXCL
. Be sure to pass these messages on to the superclass, however, to perform necessary default functionality. Within your message handlers for these messages, you may add whatever additional behavior you require.
GEOS SDK TechDocs
|
| 5.4 Using Target
| 5.6 Extending the Hierarchies