GEOS SDK TechDocs
|
| 
4 Using VisClass
| 
4.2 Drawing to the Screen
To use visible objects, you must subclass the Vis classes and create a visible object tree. Otherwise, the visible objects will not be able to display themselves or accept user input, the two things that make visible objects worthwhile.
Nearly all visible objects you use will at least display themselves on the screen. Some may accept mouse or keyboard input; some may move themselves around the screen, resize themselves, or implement custom geometry management functions.
For a subclass of
VisClass
to display itself on the screen, it must handle the message
MSG_VIS_DRAW
. This message is sent to all visible objects in a given window when that window is subjected to an exposure event. In addition, the object must be part of a tree of visible objects, the top node of which is connected to a GenView or other windowed object. Displaying a basic visible object is discussed below.
For a visible object to handle mouse input, it will need to handle a subset of the mouse event messages. Typically, a visible object will want to know when the mouse is clicked within the object's bounds (
MSG_META_START_SELECT
) and when the mouse button is released (
MSG_META_END_SELECT
). Other messages dealing with mouse motion or other mouse buttons may also be of interest to the object. In addition, visible objects may request and handle Ink input. Handling of these messages is discussed in Handling Input
.
Most applications using visible object trees will add objects to and remove them from the trees.
MSG_VIS_ADD_CHILD
and
MSG_VIS_REMOVE
are the two messages used most often for tree management. When an object should be freed, it can be destroyed with
MSG_VIS_DESTROY
, which will remove it from the tree and then free it.
Some applications will want to use the built-in geometry management features of GEOS. The geometry manager can automatically resize and reposition an entire visible object tree properly according to pre-set constraints. (The constraints can also be changed at run-time.) How the system manages visible object geometry is discussed in Geometry Management .
The geometry manager, though extremely useful for non-overlapping objects, may not be sufficient for all the needs of a complex application. For an object to determine its own size and position, it has to handle some of the messages sent out by the geometry manager. You can also manually set the size and position of each visible object. This is discussed in Positioning Visible Objects .
Often applications may need to change something about a visible object or the tree it's in. When this happens, the application must force a visual update by invalidating either the geometry or the image (or both) of the object and then calling
MGS_VIS_VUP_UPDATE_WIN_GROUP
. To mark any object invalid, the application must call
MSG_VIS_MARK_INVALID
.
Many visible objects will have specific functions they perform. For example, if the user presses on a menu item labeled "New Game" or something similar, the visible object may return itself to its original location (as in the TicTac sample application). To get this type of functionality, you must define new messages for your subclass of
VisClass
and have the object handle them. In the case of the TicTac game pieces, each piece handles the
MSG_PIECE_NEW_GAME
message by resetting the object's position to its original position.
Visible objects are maintained and managed in a tree structure. The tree has three basic elements: The root (topmost) node must be an object of
VisContentClass
. Any nodes in the middle of the tree, nodes that are allowed to have children, must be of
VisCompClass
. Any leaf nodes (guaranteed not to have children) may be of either
VisClass
or
VisCompClass
. (Subclasses of the above classes may also be used.)
The visible object tree is displayed normally through a GenView object. The output of the GenView must be tied directly to the top node of the visible object tree; this is why the visible tree must be headed by a VisContent--only the VisContent has the methods to handle GenView messages.
The VisContent object may or may not do things other than manage the visible tree. For example, the content may draw some background graphics to the window before the other visible objects draw themselves, or it may implement some special geometry behavior to arrange its children.
The VisContent can have children. These children can be either standard visible objects or
composite
visible objects. Composites, like the content, are allowed to have children. For efficiency, standard visible objects can not have children. Therefore, only leaf objects in the tree may be of
VisClass
.
The visible object tree may have any number of layers of composites. You should pay attention to the functions required in your application and fit the structure of the tree to the application's needs.
These restrictions, combined with the link to the generic object tree through GenView, result in an object tree structure somewhat like that shown in the figure above. Of course, the actual generic and visible tree structure will vary from application to application. Also, note that the generic and visible sections are actually two different object trees; they are not connected through a parent-child relationship anywhere.
GEOS SDK TechDocs
|
| 4 Using VisClass
| 4.2 Drawing to the Screen