VisClass

Automatic geometry management occurs when the geometry of the visible tree is marked invalid somewhere and a visual update is initiated. The tree's geometry can be marked invalid in several ways--an object can be added to or removed from the tree, an object can be manually marked invalid (with MSG_VIS_MARK_INVALID ), or an object can be opened or closed ( MSG_VIS_OPEN or MSG_VIS_CLOSE ).

When automatic geometry management is invoked, the geometry manager will recalculate the entire affected branch's geometry. It will calculate geometry for each affected window group, from the topmost affected window object down to the bottommost affected object. If the geometry manager encounters window groups below the topmost window, it will check first to see if the lower window's size is controlled by its children (e.g., a GenView that follows the geometry of its content). If the lower window is scrollable or otherwise not subject to its children's geometry, the geometry manager will finish calculating the geometry above the lower window before proceeding.

Calculating geometry is an involved, complex task. The process involves composites and their children negotiating on desired sizes. How the geometry is calculated depends primarily on the relationships between the objects and how their flags are set.

For example, if a GenView is set up to be exactly the same size as its VisContent object, the calculations will be different than if the GenView were scrollable. The same is true for visible composites that manage their children: If the composite resizes itself large enough to hold all its children, the children must be resized first.

The negotiation between parent and child in the visible tree takes the form of a single message: MSG_VIS_RECALC_SIZE . This is the single most important message in calculating the tree's geometry, though others are also significant. This message is sent by a composite to each of its children in turn; it passes a suggested size, and the child returns its desired size.

The composite collects all the desired sizes of its children and compares that to the size it thinks it should be. If necessary, it makes another pass through the children, or it passes on its desired size to its parent composite. Depending on the situation and the disparity between parent and children sizes, the geometry calculation may take a single pass or several. If the sizes can not be resolved through this negotiation, the geometry manager will make a decision after several passes, typically expanding the parent as much as possible to fit all the children.

After a visible object has calculated its size, its size will be set either by itself or by its parent. Often this is done with MSG_VIS_SET_SIZE . Once all sizes have been determined and set, the objects set their positions with MSG_VIS_POSITION_BRANCH , which propagates down the tree. It sets the position of the topmost composite and then sets each of its children's positions appropriately.

When geometry calculations are complete, the geometry manager will send a MSG_VIS_NOTIFY_GEOMETRY_VALID to all visible objects with the flag VGA_NOTIFY_GEOMETRY_VALID set in its VI_geoAttrs field.

Several other messages may be used during geometry updates. Some of them may be intercepted to alter the behavior of the default method. These messages are listed below. Others can be used to invalidate a visible object's geometry or to cause a geometry update on the tree.

MSG_VIS_UPDATE_GEOMETRY

This message is typically called by the UI during a window group update. It calculates the geometry of the entire branch receiving it. It's not likely you'll subclass this method--altering its behavior can be used for certain optimizations, however.

MSG_VIS_NOTIFY_GEOMETRY_VALID

This message will be sent to an object when all its geometry messages have been handled and its geometry has been fully resolved (at least for the moment). This message will be sent only if VGA_NOTIFY_GEOMETRY_VALID is set in the object's VI_geoAttrs field. There is no default behavior for this message; it should be intercepted only if the object needs to do calculations after the geometry has settled down.

MSG_VIS_RECALC_SIZE

This message is normally sent by the geometry manager to a composite object. The composite is expected to send it to all its children; the children will then determine their sizes, and the composite will figure the total size and return. A composite that manages its own children can also use this message to query its children for their desired sizes.

MSG_VIS_RECALC_SIZE_AND_INVAL_IF_NEEDED

This message is an optimized MSG_VIS_RECALC_SIZE . Composites should use this version when sending a recalculation message to their children. This message only causes recalculation if needed and will invalidate the object if the size gets recalculated. It invalidates the object's image at its old bounds and only invalidates its geometry if the bounds change. It is highly unlikely that you'll subclass this method.

MSG_VIS_GET_CENTER

This message returns the amount of space on each side the object wants reserved for itself. It does not, as the name suggests, return the coordinates of the object's center. Instead, it returns the distance in each direction the object requires (you may think of it as external margins).

MSG_VIS_RESET_TO_INITIAL_SIZE

This message propagates down the visible tree and causes every object that receives it to reset itself to its original size. It does this by clearing VGA_GEOMETRY_CALCULATED in the object's VI_geoAttrs field, causing the object to believe it is being put on-screen for the first time. This message will also set the object's flags to indicate that its geometry has become invalid. It's highly unlikely your application will subclass this method.

MSG_VIS_POSITION_BRANCH

This message is sent by the geometry manager when an entire visible branch should be repositioned. If an application wants to do something special, it should subclass the handler for this message. Typically, though, only subclasses of VisCompClass and perhaps VisContentClass will change this method.

MSG_VIS_POSITION_AND_INVAL_IF_NEEDED

This message is an optimized MSG_VIS_POSITION_BRANCH that causes a branch reposition only if it's necessary. It will also invalidate both the object's and the parent's original images and, if the position changes, the geometry as well. It is highly unlikely that you'll subclass this method.

MSG_VIS_INVAL_ALL_GEOMETRY

This message invalidates all geometry under the recipient object, forcing invalidation of all children. This is a brute-force message used only when absolutely necessary.

MSG_VIS_UPDATE_GEOMETRY

void	MSG_VIS_UPDATE_GEOMETRY();

This message is sent during a visual update to cause objects to recalculate their geometry. Applications can use this message to ensure that geometry gets updated for a visual branch even if the branch is not currently drawn on the screen.

Source: Visual update mechanism.

Destination: Any visible object.

Interception: May be intercepted for optimizations. A thorough knowledge of the geometry update mechanism and the specifics of the visible tree's geometry is strongly recommended, however.

MSG_VIS_NOTIFY_GEOMETRY_VALID

void	MSG_VIS_NOTIFY_GEOMETRY_VALID();

This message is sent by the geometry manager to objects that have VGA_NOTIFY_GEOMETRY_VALID set. The message is sent only after all geometry messages have been handled for the object. It has no default behavior.

Source: Visible update mechanism.

Destination: Any visible object--typically a child of the object sending the message.

Interception: This message has no default behavior. It should be intercepted by any object that needs to do something after its geometry has been made valid.

MSG_VIS_RECALC_SIZE

SizeAsDWord MSG_VIS_RECALC_SIZE(
        int	width,
        int	height);

This message takes the suggested height and width of the object and recalculates the object's desired size based on them. Composite objects are expected to pass this message to their children and then calculate their sizes based on those of their children. The default behavior of the handler for this is to return the current size no matter what the suggested size is.

Source: Visible update mechanism.

Destination: Any visible object.

Parameters: width Suggested new width of the object as determined by the object's parent.

height

Suggested new height of the object as determined by the object's parent.

Return: A dword value representing the object's desired size as calculated by the object. The high word of the return value represents the width and the low word the height. Use the macros DWORD_WIDTH and DWORD_HEIGHT to extract the width and height; see DWORD_HEIGHT .

Interception: Default behavior is to return the object's current size no matter what the passed width and height are. Any object that wants special sizing behavior based either on the object's children or on the suggested size should subclass the method.

MSG_VIS_RECALC_SIZE_AND_INVAL_IF_NEEDED

SizeAsDWord MSG_VIS_RECALC_SIZE_AND_INVAL_IF_NEEDED(
        int	width,
        int	height);

This message is the same as MSG_VIS_CALC_RESIZE except that it is somewhat optimized. It will recalculate only if certain flags are set for the object, and it will mark the geometry invalid only if recalculation is done.

Source: Visible update mechanism.

Destination: Any visible object.

Parameters: width Suggested new width of the object as determined by the object's parent.

height

Suggested new height of the object as determined by the object's parent.

Return: A dword value representing the object's desired size as calculated by the object. The low word of the return value represents the width and the high word the height.

Interception: Unlikely--Default behavior is to return the object's current size no matter what the passed width and height are. Any object that wants special sizing behavior based either on the object's children or on the suggested size should subclass the method.

MSG_VIS_GET_CENTER

void	MSG_VIS_GET_CENTER(
        GetCenterParams *retValue);

This message returns the amount of space needed by the object in each direction from its center. It does not, as the name suggests, return the coordinates of the center of the object. Instead, the object must determine the amount of space it requires from its center to each edge for geometry management and return them in the structure passed.

Source: Visible update mechanism.

Destination: Any visible object

Parameters: retValue A pointer to an empty GetCenterParams structure, defined below.

Return: The method must fill the GetCenterParams structure pointed to by the retValue parameter.

Interception: Any object that wants to effect a different centering than the default should subclass this method. For example, if a set of objects can be overlapped, or if they should have extra space between them, they should subclass this message and alter the returned values appropriately.

Structures: The GetCenterParams structure is defined as follows:

typedef struct {
    word   GCP_aboveCenter;    /* space above */
    word   GCP_belowCenter;    /* space below */
    word   GCP_leftOfCenter;   /* space left */
    word   GCP_rightOfCenter;  /* space right */
}  GetCenterParams;

MSG_VIS_RESET_TO_INITIAL_SIZE

void	MSG_VIS_RESET_TO_INITIAL_SIZE(
        VisUpdateMode updateMode);

This message propagates down an entire visual branch, causing the objects in it to reset their sizes to their original width and height. First it invalidates the object's geometry, then it recalculates the geometry starting at the top.

Source: Visible update mechanism.

Destination: Any visible object.

Parameters: updateMode A VisUpdateMode indicating when the visual update of the tree should occur.

Return: Nothing.

Interception: Unlikely.

MSG_VIS_POSITION_BRANCH

void	MSG_VIS_POSITION_BRANCH(
        word	xOrigin,
        word	yOrigin);

This message repositions an entire visible branch. It propagates down the branch, causing each visible object to reposition itself based on the new origins passed. Composites must pass the appropriate altered positions to their children.

Source: Visible update mechanism.

Destination: Any visible object.

Parameters: xOrigin The new horizontal position of the object relative to the document or window it's in. This value is set into the object's VI_bounds . R_left bound, and the right bound is set according to the object's size.

yOrigin

The new vertical position of the object relative to the document or window it's in. This value is set into the object's VI_bounds . R_top bound, and the bottom bound is set according to the object's size.

Return: Nothing.

Interception: The default behavior is to set the object to the passed position. Composite objects that want to position their children a special way should subclass this (and not call the superclass) method. Non-composites will rarely, if ever, subclass this message.

MSG_VIS_POSITION_AND_INVAL_IF_NEEDED

Boolean	MSG_VIS_POSITION_AND_INVAL_IF_NEEDED(
        word	xPosition,
        word	yPosition);

This message is an optimized version of MSG_VIS_POSITION_BRANCH . It repositions the branch only if necessary and will mark the image invalid only if the position was changed. It returns a flag indicating whether or not the object was repositioned.

Source: Visible update mechanism.

Destination: Any visible object--typically sent by a composite to its children.

Parameters: xPosition The new horizontal position of the object relative to the document or window it's in. A negative value means that the object should choose its own position as best it can.

yPosition

The new vertical position of the object relative to the document or window it's in. A negative value means that the object should choose its own position as best it can.

Return: If the object was repositioned, the message will return true . Otherwise, it will return false .

Interception: Unlikely.

MSG_VIS_INVAL_ALL_GEOMETRY

void	 MSG_VIS_INVAL_ALL_GEOMETRY(
        VisUpdateMode		updateMode);

This is a brute-force, desperation message used to invalidate all geometry in the recipient's tree; that is, all geometry of the recipient and all objects under it in the tree will be invalidated. You should only use this message when the whole tree should be recalculated.

Source: Unrestricted.

Destination: The object requiring geometry recalculation.

Parameters: updateMode A visual update mode indicating when the visual update of the recalculation should occur.

Return: Nothing.

Interception: Generally not intercepted.

VisClass: 4.4 Using VisClass: Handling Input

Input events, what they mean, and how they are generated are discussed fully in the Input chapter. The visible world has some default behavior for handling input messages such as MSG_META_START_SELECT , MSG_META_END_SELECT , and MSG_META_PTR . For the most part, however, visible objects that want to respond to input must subclass and handle the input messages that interest them.

Composite objects will automatically pass mouse messages on to the proper child directly under the mouse pointer. Non-composite objects (direct subclasses of VisClass ) have no special default behavior for input handling.

Note that VisClass does not intelligently handle layering of objects. That is, if one object is visibly on top of another object, it will not necessarily receive the input events--the events may be passed to the partially hidden object. This is due to the order in which drawing and mouse events are handled by a visible object's children.

Take the example of a visible composite with two children. Each child draws a filled rectangle covering its bounds; the first child has a width and height of 40, and the second child has a width and height of 20. The composite's declaration shows

    ...
    VCI_comp = LargeChild, SmallChild;

    ...

Because drawing occurs in the order the children are listed, the small child will be drawn over the large child, as shown in the figure below. If each object can intercept and handle mouse events (e.g., MSG_META_START_SELECT ), clicks will never reach the small object without special behavior added to the composite. This is because input events are handled in the same order as drawing; the input event will be given to the first child whose bounds include the event's coordinates.

So, a click event on (10, 10), which is in the middle of the small square, would first be passed to the LargeChild object. The large child would see that the click was within its bounds, and it would take the event. The event would never be handled by the small object.

Therefore, if you need to have overlapping objects which handle user input, you will have to add special features for bounds detection. In the example of the two squares, if neither were to move, the composite could simply pass the event to the small child first and then to the large child, assuming the small child is always on top. If the objects could be moved forward and back so they hide each other, the composite (or the objects themselves) will need some other, more complex, detection behavior.

Mouse Events

MSG_META_PTR, MSG_META_START_SELECT, MSG_META_END_SELECT, MSG_META_DRAG_SELECT, MSG_META_DRAG, MSG_META_START_MOVE_COPY, MSG_META_DRAG_MOVE_COPY, MSG_META_START_OTHER, MSG_META_END_OTHER, MSG_META_DRAG_OTHER

Composite objects will automatically pass mouse messages on to the first child directly under the mouse pointer. Non-composite objects (direct subclasses of VisClass ) have no special default behavior for input handling.

Typically, a visible object that needs to handle mouse input will subclass MSG_META_START_SELECT (or one of the other press events such as MSG_META_START_MOVE_COPY ). This message is sent when the user presses on the "select" mouse button while the pointer is over the object. In this method, the object should grab the mouse (as shown below). When it has the mouse grab, it will receive MSG_META_PTR each time the mouse is moved; the object should subclass this message to provide the desired reaction to mouse moves. Finally, when the user releases the select button, the object will receive a MSG_META_END_SELECT . At this point, it should release the mouse grab.

Typically, mouse events will arrive with coordinates specified in 16 bits. This is the default graphics space, and it represents a coordinate system more than 25 yards on a side. Nearly all applications will find this graphic system big enough for their uses. However, if you need larger coordinates, you can use the large document space with 32-bit coordinates. To do this, you must set the GVA_WINDOW_COORDINATE_MOUSE_EVENTS in the GVI_attrs field of your GenView object and set up your visible objects correctly. For more information on supporting 32-bit graphic spaces with visible objects, see Visible Layers and 32-Bit Graphics .

Grabbing the Mouse

MSG_VIS_GRAB_MOUSE, MSG_VIS_FORCE_GRAB_MOUSE, MSG_VIS_GRAB_LARGE_MOUSE, MSG_VIS_FORCE_GRAB_LARGE_MOUSE, MSG_VIS_RELEASE_MOUSE

When an object "grabs the mouse," it requests that the UI send all future mouse events directly to that object. Normally, mouse events will travel down the visible object tree until they reach either the leaf object under the pointer or an object under the pointer that handles them. When an object has the mouse grab, the mouse events will go to the object with the grab regardless of the location of the pointer.

Typically, if an object wants to receive mouse events, it will subclass MSG_META_START_SELECT . This message is sent to the object when the pointer is over the object's bounds and the user presses the select button. In this handler, the object grabs the UI's gadget exclusive and then grabs the mouse. A good example of this can be found in the TicTac sample application's handler for MSG_META_START_SELECT .

After an object grabs the mouse, it receives all pointer and drag events that occur. These are primarily MSG_META_PTR messages, and the object must subclass MSG_META_PTR to achieve the proper behavior it wants. When the user lets go of the select button, the object will receive a MSG_META_END_SELECT . If it grabbed the mouse (which it probably did if it receives this message), it must relinquish both the gadget exclusive and its mouse grab.

An example of getting and releasing the mouse grab (taken from the TicTac sample application) is shown in Grabbing and Releasing the Mouse . The object subclasses these messages to let the user drag it around the screen.

The UI allows the visible object to get the normal mouse grab by using four different messages. Each of these is detailed below. If you're using a large document (32-bit coordinates), you will use the "large" mouse grabs. Otherwise, the normal mouse grab messages will do.

MSG_VIS_GRAB_MOUSE

void	MSG_VIS_GRAB_MOUSE();

A visible object sends itself this message (with @call ) when it wants to acquire the normal mouse grab. The message MSG_VIS_RELEASE_MOUSE must be used to relinquish the grab.

Source: Unrestricted.

Destination: Any visible object--typically sent by the object to itself.

Interception: Highly unlikely.

MSG_VIS_FORCE_GRAB_MOUSE

void	MSG_VIS_FORCE_GRAB_MOUSE();

A visible object sends itself this message (with @call ) when it wants to forcibly grab the mouse input. The object will acquire the mouse grab even if another object currently has it; the other object will receive a MSG_VIS_LOST_GADGET_EXCL when it loses the mouse by a forced grab. The object must release the grab later with MSG_VIS_RELEASE_MOUSE .

Source: Unrestricted.

Destination: Any visible object--typically sent by the object to itself.

Interception: Highly unlikely.

MSG_VIS_GRAB_LARGE_MOUSE

void	MSG_VIS_GRAB_LARGE_MOUSE();

A visible object sends itself this message (with @call ) when it wants to acquire the mouse grab and when it wants 32-bit coordinates. If the object wants 16-bit coordinates, it should use MSG_VIS_GRAB_MOUSE , above. The object must relinquish the mouse grab with MSG_VIS_RELEASE_MOUSE .

Source: Unrestricted.

Destination: Any visible object--typically sent by the object to itself.

Interception: Highly unlikely.

MSG_VIS_FORCE_GRAB_LARGE_MOUSE

void	MSG_VIS_FORCE_GRAB_LARGE_MOUSE();

A visible object sends itself this message (with @call ) when it wants to forcibly grab the mouse input and when it wants large (32-bit) input coordinates. If it wants normal (16-bit) coordinates, it should use MSG_VIS_FORCE_GRAB_MOUSE , above. The object will acquire the mouse grab even if another object currently has it; the other object will receive a MSG_VIS_LOST_GADGET_EXCL when it loses the mouse by a forced grab. The object must release the grab later with MSG_VIS_RELEASE_MOUSE .

Source: Unrestricted.

Destination: Any visible object--typically sent by the object to itself.

Interception: Highly unlikely.

MSG_VIS_VUP_ALTER_INPUT_FLOW

void	MSG_VIS_VUP_ALTER_INPUT_FLOW(@stack
        PointDWord		translation,
        WindowHandle		window,
        optr		object,
        word		grapTypeAndFlags);

This message is the primitive employed by the grab/release messages shown above. Objects will rarely use this unless they are large objects (using 32-bit coordinates). Large objects and composites should subclass this message. In the case of a mouse grab, they should add in their 32-bit offset amounts to the translation structure before passing the event on to their superclasses. This will result in large mouse events being properly translated for the duration of the mouse grab.

Source: Unrestricted.

Destination: Any visible object--typically a VisContent which uses a 32-bit graphics space for its children.

Parameters: translation The offsets to the origin of the "local" 16-bit graphics space.

window

The handle of the view window associated with this input flow alteration.

object

The optr of the object altering the input flow.

grabTypeAndFlags

The type and flags for the input flow grab affected by this alteration. The high byte contains a record of VisInputFlowGrabType , described below; the low byte contains a VisInputFlowGrabFlags record, also described below.

Return: Nothing.

Interception: Any VisContent object that uses a large graphics space should subclass this method. In the handler, it should apply the stated translation, then call its superclass. Each subsequent mouse event will have the translation applied before being passed on to the composite's children.

Structures: The types of VisInputFlowGrabType are listed below:

VIFGT_ACTIVE

The affected grab type is the active grab.

VIFGT_PRE_PASSIVE

The affected grab type is the pre-passive grab.

VIFGT_POST_PASSIVE

The affected grab type is the post-passive grab.

The flags of VisInputFlowGrabFlags are listed below:

VIFGF_NOT_HERE

Flag set to indicate that the message should not be handled in this method but rather passed up the tree with this flag cleared. It is used to distinguish between requests made by other objects and requests made by an object sent to itself. It also allows an object to redirect the message to another node not in the visible hierarchy by handling the message and passing it in a direction other than up the visible tree. This overrides all the other flags in this record.

VIFGF_FORCE

Flag set if the grab should be forced. Note that both VIFGF_GRAB and VIFGT_ACTIVE must also be specified.

VIFGF_GRAB

Flag set if the grab is being made, clear if the grab is being released. In either case, object must be passed--if a release, the grab will not be released unless the objects match. Note also that only one object may have the active grab, but many objects may have either passive grab at a given time.

VIFGF_KBD

Flag set if action is a keyboard grab or release.

VIFGF_MOUSE

Flag set if action is a mouse grab or release.

VIFGF_LARGE

Flag set if large mouse events are affected by the flow alteration. VIFGF_MOUSE must also be set.

VIFGF_PTR

Flag set if mouse grab and pointer events are requested. If flag clear, only button-related events will be sent. VIFGF_MOUSE must also be set.

MSG_VIS_RELEASE_MOUSE

void	MSG_VIS_RELEASE_MOUSE();

A visible object sends itself this message if it has the mouse grab and wants to release it. Typically, this message will be called in the object's MSG_META_END_SELECT handler. It works for both large and small grabs.

Source: Any visible object.

Destination: Any visible object--typically sent by the object to itself.

Interception: Unlikely.

Code Display 15-2 Grabbing and Releasing the Mouse

/* This code display shows the  MSG_META_START_SELECT, MSG_META_END_SELECT,
 * and MSG_VIS_LOST_GADGET_EXCL handlers from the TicTac sample application.
 *
 * The sequence of input events and the messages they generate follow the
 * following basic patterns:
 * 1.	User presses select button
 *	MSG_META_START_SELECT generated, sent to object under mouse pointer
 *	If object under pointer is a game piece,
 *		Game piece grabs gadget exclusive
 *		Game piece grabs mouse
 * 2.	User holds button and drags mouse
 *	MSG_META_DRAG_SELECT generated, sent to object with mouse grab
 *		Game piece sets internal "dragging" flag
 *		Game piece draws outline
 *	MSG_META_PTR messages generated during drag, sent to object with mouse grab
 *		Game piece erases previous outline
 *		Game piece draws new outline at new pointer position
 * 3.	User releases button
 *	MSG_META_END_SELECT generated, sent to object with mouse grab
 *		Game piece releases gadget exclusive (MSG_VIS_RELEASE_GADGET_EXCL)
 *		MSG_VIS_LOST_GADGET_EXCL generated, sent to mouse grab (game piece)
 *		Game piece erases old outline, if any
 *		Game piece moves itself, erases old bounds, draws new bounds
 *		Game piece releases mouse grab (MSG_VIS_RELEASE_MOUSE)
 */

/***********************************************************************
 *		MSG_META_START_SELECT for TicTacPieceClass
 ***********************************************************************
 * SYNOPSIS:		Grabs the mouse and calls for future pointer events.
 * 		When the user clickes in the view, TicTacView will pass
 * 		the click event to TicTacBoard. Since TicTacBoardClass
 * 		does not intercept the event, VisContentClass passes
 * 		it on to its child object currently under the pointer.
 * PARAMETERS:
 * 	void	(MouseReturnParams *retVal,
 *		 word xPosition, word yPosition, word inputState);
 *
 * STRATEGY:		When the piece object receives this message, it means
 * 		it has been clicked on by the user and the mouse button
 * 		is still down. The piece must grab the mouse so that it
 * 		gets all future mouse events, and it must request that
 * 		all future mouse events be sent to it. This ensures
 * 		that if the pointer leaves the object's bounds while
 * 		the button is still pressed, the piece object will still
 * 		receive all the pointer events (otherwise they would be
 * 		sent to whatever object was under the new pointer position).
 ***********************************************************************/

@method TicTacPieceClass, MSG_META_START_SELECT {

	/* Grab the gadget exclusive so we're allowed to grab the mouse. */
    @call @visParent::MSG_VIS_TAKE_GADGET_EXCL(oself);

	/* Grab the mouse. This requests that all future pointer
	 * events be passed directly to this game piece. */
    @call self::MSG_VIS_GRAB_MOUSE();

	/* Finally, return that this particular click event has been processed.
	 * If this flag is not returned, the system will send out the click
	 * event again. */
    retVal->flags = MRF_PROCESSED;					 /* this event processed */
}

/***********************************************************************
 *		MSG_META_END_SELECT for TicTacPieceClass
 ***********************************************************************
 * SYNOPSIS:		This message is received when the selection button has
 * 		been released and this game piece had the mouse grab.
 * 		All it does is release the gadget exclusive.
 * PARAMETERS:
 * 	void	(MouseReturnParams *retVal,
 * 		 word xPosition, word yPosition, word inputState);
 ***********************************************************************/

@method TicTacPieceClass, MSG_META_END_SELECT {
    @call @visParent::MSG_VIS_RELEASE_GADGET_EXCL(oself);
    retVal->flags = MRF_PROCESSED;					/* this event processed */
}

/***********************************************************************
 *		MSG_VIS_LOST_GADGET_EXCL for TicTacPieceClass
 ***********************************************************************
 * SYNOPSIS:		This message is received when the selection button has
 * 		been released and this game piece had the mouse grab.
 * 		It first checks to see if the new, proposed bounds are
 * 		on the game board. If the bounds are valid, then
 * 		it sets the objects VI_bounds field to the new values
 * 		and causes the object to erase its original drawing
 * 		and draw itself at its new bounds. If the bounds are
 * 		not on the game board, it will retain the original bounds
 * 		and redraw using them.
 * PARAMETERS:		void ();
 ***********************************************************************/

@method TicTacPieceClass, MSG_VIS_LOST_GADGET_EXCL {
    WindowHandle win;				/* window handle of view window */
    GStateHandle gstate;				/* temporary gstate to draw to */

    /* See if piece was being dragged or not. If so, clear the outline. */

    if (pself->TTP_dragging) {

	    /* Get the window handle of the view window and create a
	     * temporary gstate for it to draw to. */

	win = @call TicTacView::MSG_GEN_VIEW_GET_WINDOW();
	gstate = GrCreateState(win);

	    /* Set the line color and mode for drawing the outline. */

	GrSetLineColor(gstate, CF_INDEX, C_BLACK, 0, 0);
	GrSetMixMode(gstate, MM_INVERT);

	    /* Erase outline on screen. */

	    /* If the game piece type is TTPT_BOX, draw a rectangle
	     * outline. Otherwise draw an ellipse outline. */

	if (pself->TTP_pieceType == TTPT_BOX) {
	    GrDrawRect(gstate, pself->TTP_horizPos, pself->TTP_vertPos,
			 ((pself->TTP_horizPos) + PIECE_WIDTH),
			 ((pself->TTP_vertPos) + PIECE_HEIGHT));
	} else {
	    GrDrawEllipse(gstate, pself->TTP_horizPos, pself->TTP_vertPos,
			 ((pself->TTP_horizPos) + PIECE_WIDTH),
			 ((pself->TTP_vertPos) + PIECE_HEIGHT));
	}

	    /* Check to see if the new bounds are on the game board. If
	     * they are, set the object's bounds to the new values. If
	     * the are not, retain the original values and set the values
	     * to those last stored. */

	if (@call TicTacBoard::MSG_TICTAC_VALIDATE_BOUNDS(
			((pself->TTP_vertPos) + PIECE_HEIGHT),
			((pself->TTP_horizPos) + PIECE_WIDTH),
			pself->TTP_vertPos, pself->TTP_horizPos)) {

	    /* Invalidate the original drawing of the game piece. Send
	     * the VI_bounds rectangle as the parameters because they have
	     * not been changed since the START_SELECT. This message is
	     * the equivalent of calling GrInvalRect() with the same bounds */

	    @call self::MSG_VIS_BOUNDS_CHANGED(pself->VI_bounds.R_bottom,
					pself->VI_bounds.R_right,
					pself->VI_bounds.R_top,
					pself->VI_bounds.R_left);

	    /* Set the game piece object's bounds to the new coordinates. */

	    pself->VI_bounds.R_left = pself->TTP_horizPos;
	    pself->VI_bounds.R_right = (pself->TTP_horizPos) + PIECE_WIDTH;
	    pself->VI_bounds.R_top = pself->TTP_vertPos;
	    pself->VI_bounds.R_bottom = (pself->TTP_vertPos) + PIECE_HEIGHT;

	} else {

	    /* If the bounds are not on the game board, then reset the
	     * current positions to be the original bounds. */

	    pself->TTP_horizPos = pself->VI_bounds.R_left;
	    pself->TTP_vertPos = pself->VI_bounds.R_top;
	}

	    /* Now, the game piece must draw itself at its newly-set
	     * bounds (will draw itself over its original picture if the
	     * new bounds were invalid). */

	@call self::MSG_VIS_DRAW(0, gstate);

	    /* Finally, destroy the temporary gstate used for drawing. */

	GrDestroyState(gstate);

	    /* Clear flag to indicate we are no longer dragging. */

	pself->TTP_dragging = FALSE;
    }
	/* Release the mouse grab now that the move has finished.
	 * Other objects in the view (other game pieces, for example)
	 * may now receive pointer, select, and drag events. */

    @call self::MSG_VIS_RELEASE_MOUSE();
}

Passive Grabs

MSG_VIS_ADD_BUTTON_PRE_PASSIVE, MSG_VIS_REMOVE_BUTTON_PRE_PASSIVE, MSG_VIS_ADD_BUTTON_POST_PASSIVE, MSG_VIS_REMOVE_BUTTON_POST_PASSIVE

The type of mouse grab described in the previous section is also known as an "active" mouse grab. An object can also have two other types of mouse grabs: pre-passive and post-passive . While only one object may have the active mouse grab at any given time, any number of objects may have pre- or post-passive grabs on the mouse.

An object with a pre-passive mouse grab receives a copy of the input event before the event goes to its true destination. The copy will be a message of the form MSG_META_PRE_PASSIVE_... (e.g., if the event is MSG_META_PTR , the pre-passive event is MSG_META_PRE_PASSIVE_PTR ). All pre-passive events will be handled before the true event is delivered to the object with the active grab. If any of the pre-passive copies of the event is returned with the flag MRF_PREVENT_PASS_THROUGH, the active event will not be sent to its destination. You can use this feature to set up input filters, having an object receive all mouse events pre-passive and filtering out those that should not be delivered. The message MSG_VIS_REMOVE_BUTTON_PRE_PASSIVE removes any pre-passive mouse grab from the object.

A post-passive mouse grab is similar to a pre-passive except that the post-passive object receives the event after it is sent to its normal destination. The post-passive object will receive a MSG_META_POST_PASSIVE_... with the same flags and position information as sent with the input event. An object that has the post-passive grab can release it by sending itself a MSG_VIS_REMOVE_BUTTON_POST_PASSIVE .

MSG_VIS_ADD_BUTTON_PRE_PASSIVE

void	MSG_VIS_ADD_BUTTON_PRE_PASSIVE();

A visible object sends itself this message (with @call ) when it wants to gain a pre-passive mouse grab. The object will receive all subsequent mouse events in the form of MSG_META_PRE_PASSIVE_... before the event's destination object receives them; this message will carry the same input information as passed with the input event. The object should handle MSG_META_PRE_PASSIVE_... and, if the event is not to be sent normally to its destination, should return the flag MRF_PREVENT_PASS_THROUGH from that handler. The pre-passive grab will be released when the object sends itself a MSG_VIS_REMOVE_BUTTON_PRE_PASSIVE .

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself when it wants to gain a pre-passive mouse grab.

Interception: Unlikely--Note that the object must, however, intercept any MSG_META_PRE_PASSIVE... events it is interested in.

MSG_VIS_REMOVE_BUTTON_PRE_PASSIVE

void	MSG_VIS_REMOVE_BUTTON_PRE_PASSIVE();

This message removes the pre-passive grab from a visible object.

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself when it has a pre-passive grab and wants to release it.

Interception: Unlikely.

MSG_VIS_ADD_BUTTON_POST_PASSIVE

void	MSG_VIS_ADD_BUTTON_POST_PASSIVE();

A visible object sends itself this message (with @call ) when it wants to gain the post-passive mouse grab. The object will receive all subsequent mouse events in the form of MSG_META_POST_PASSIVE_... after the event's destination object receives them; this message will carry the same input information as passed with the input event. The object should handle the appropriate MSG_META_POST_PASSIVE_... to properly receive the events. The post-passive grab will be released when the object receives a MSG_VIS_REMOVE_BUTTON_POST_PASSIVE .

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself when it wants to receive post-passive input events.

Interception: Unlikely--Note that the object must, however, handle any MSG_META_POST_PASSIVE_... events it is interested in.

MSG_VIS_REMOVE_BUTTON_POST_PASSIVE

void	MSG_VIS_REMOVE_BUTTON_POST_PASSIVE();

This message removes any post-passive mouse grab from the object.

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself to release a post-passive mouse grab.

Interception: Unlikely.

The Gadget Exclusive and Focus Hierarchy

MSG_VIS_TAKE_GADGET_EXCL, MSG_VIS_RELEASE_GADGET_EXCL, MSG_VIS_LOST_GADGET_EXCL, MSG_VIS_VUP_QUERY_FOCUS_EXCL, MSG_VIS_FUP_QUERY_FOCUS_EXCL, MSG_VIS_VUP_ALLOW_GLOBAL_TRANSFER

The gadget exclusive is a marker in the system used by the UI to indicate which object has exclusive access to input gadget functionality. Only one gadget at a time may have the gadget exclusive, and the gadget exclusive may be forcibly taken from an object by another object (for example, when a system-modal dialog comes up during a drag operation).

At times, an object will force the mouse input to go to a different object from that which has the current active grab. This is done almost exclusively by the Specific UI library and is rarely, if ever, done by applications. Three messages can be used in determining which object has the current "gadget exclusive," or active mouse grab. These are shown below.

In addition, individual objects can get information about the current state of the Focus hierarchy with MSG_VIS_VUP_QUERY_FOCUS_EXCL and MSG_VIS_FUP_QUERY_FOCUS_EXCL , also shown below.

To deal with a quick-transfer operation, a visible object may also have to use the message MSG_VIS_VUP_ALLOW_GLOBAL_TRANSFER . This message may be used to remove the mouse grab from the GenView in which the visible object resides, thereby allowing mouse events to reach other objects outside the view window.

MSG_VIS_TAKE_GADGET_EXCL

void	MSG_VIS_TAKE_GADGET_EXCL(
        optr	child);

This message causes the passed object to be given the gadget exclusive. Any object currently having the gadget exclusive will subsequently receive a MSG_VIS_LOST_GADGET_EXCL . This is used primarily by the Specific UI.

Source: Unrestricted. Typically sent by a visible object that will next grab the mouse.

Destination: Any visible object--normally sent by an object to its visible parent.

Parameters: child The optr of the object to which the gadget exclusive will be given (normally the calling object).

Return: Nothing.

Interception: Unlikely.

See Also: MSG_VIS_GRAB_MOUSE , MSG_VIS_LOST_GADGET_EXCL

MSG_VIS_RELEASE_GADGET_EXCL

void	MSG_VIS_RELEASE_GADGET_EXCL(
        optr	child);

This message causes the passed object to release the gadget exclusive. The object specified by child will then receive a MSG_VIS_LOST_GADGET_EXCL .

Source: Unrestricted. Typically sent by an object that has a mouse grab and expects to release it.

Destination: Any visible object--normally sent by the object to it's parent.

Parameters: child The optr of the object which is to lose the gadget exclusive (normally the calling object).

Return: Nothing.

Interception: Unlikely.

See Also: MSG_VIS_RELEASE_MOUSE , MSG_VIS_LOST_GADGET_EXCL

MSG_VIS_LOST_GADGET_EXCL

void	MSG_VIS_LOST_GADGET_EXCL();

This message, when received, indicates that the recipient has lost its hold on the gadget exclusive. When an object receives this, it should release the active mouse grab, if appropriate.

Source: Unrestricted--typically sent by the UI.

Destination: The visible object losing the gadget exclusive.

Interception: Mouse grabs should be released in this handler.

MSG_VIS_VUP_QUERY_FOCUS_EXCL

void	MSG_VIS_VUP_QUERY_FOCUS_EXCL(
        ObjectAndGrabParams *retValue);

This message queries up the visible hierarchy to find the object having the current focus in the current window. The current window is taken to be the window in which the object receiving the message resides.

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself to find the focus optr in its window.

Parameters: retValue A pointer to an empty ObjectAndGrabParams structure, shown below.

Return: The ObjectAndGrabParams structure pointed to by retVal will be filled with the appropriate data.

Interception: Unlikely.

Structures: The structure of the ObjectAndGrabParams is shown below:

typedef struct {
    word		OAGP_grabFlags;  /* flags */
    word		OAGP_unused;     /* reserved */
    optr		OAGP_object;     /* object with focus */
}  ObjectAndGrabParams;

The OAGP_grabFlags field contains a record of HierarchicalGrabFlags

, defined in the Input chapter. The allowable flags are

HGF_SYS_EXCL

Indicates this object has the system exclusive.

HGF_APP_EXCL

Indicates this object has the application's exclusive.

HGF_GRAB

Indicates this object wishes to grab the exclusive (if clear, the object wishes to release), when passed as a parameter. In the structure, it merely indicates that the object in OAGP_object has the exclusive.

HGF_OTHER_INFO

Twelve bits used by the specific UI depending on the type of hierarchical grab.

MSG_VIS_FUP_QUERY_FOCUS_EXCL

void	MSG_VIS_FUP_QUERY_FOCUS_EXCL(
        ObjectAndGrabParams *retValue);

This message queries the focus hierarchy to see which object has the current focus. The current focus object does not have to be in the caller's visible tree.

Source: Unrestricted.

Destination: Any visible object.

Parameters: retValue A pointer to an empty ObjectAndGrabParams structure, shown above in the entry for MSG_VIS_VUP_QUERY_FOCUS_EXCL .

Return: The ObjectAndGrabParams structure pointed to by retVal will be filled with the appropriate data.

Interception: Unlikely. This message is not deliverd to all visible objects, rather only those marked as VTF_WIN_GROUP or VTF_IS_INPUT_NODE. If you are implementing a new focus node, and need this message, and are not a window group, you will need to set the VTF_IS_INPUT_NODE bit in your init routine.

Structures: The structure of the ObjectAndGrabParams is shown in the entry for MSG_VIS_VUP_QUERY_FOCUS_EXCL .

MSG_VIS_VUP_ALLOW_GLOBAL_TRANSFER

void	MSG_VIS_VUP_ALLOW_GLOBAL_TRANSFER();

This message is sent by a visible object to itself when a quick-transfer operation is underway and the pointer has to be allowed to leave the bounds of the object's view window. This message will travel up to the content object, which will indicate to the GenView that the pointer events must be allowed to go to other windows in the system.

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself when the global transfer must be allowed outside its window.

Interception: Unlikely.

The Mou se Status

MSG_VIS_VUP_SET_MOUSE_INTERACTION_BOUNDS, MSG_VIS_VUP_GET_MOUSE_STATUS, MSG_VIS_VUP_TERMINATE_ACTIVE_MOUSE_FUNCTION, MSG_VIS_VUP_BUMP_MOUSE

The UI can control the mouse image and events as they occur. Because the UI is based on the visible classes, the messages that control the mouse status are also available to you, though they will probably be of very little utility. These messages are given below.

MSG_VIS_VUP_SET_MOUSE_INTERACTION_BOUNDS

void	MSG_VIS_VUP_SET_MOUSE_INTERACTION_BOUNDS(@stack
        int	bottom,
        int	right,
        int	top,
        int	left);

A visible object requesting the mouse grab sends this message up the visible tree. This message will be handled by a content object. It indicates a new set of draggable bounds in case the user initiates a drag-scrolling operation. This message is sent automatically when the visible object requests the grab.

Source: A visible object requesting a mouse grab.

Destination: The sender sends this message to itself.

Parameters: bottom, right, top, left
The four bounds of the new bounding rectangle. Default is the bounds of the object sending the message.

Return: Nothing.

Interception: Unlikely.

MSG_VIS_VUP_GET_MOUSE_STATUS

word	MSG_VIS_VUP_GET_MOUSE_STATUS();

This message is rarely used by any objects outside the UI library. It returns the information passed with the last mouse event. The word return value contains two byte-sized sets of flags. The high byte is a list of the active UI functions, and the low byte represents the current button information.

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself when it can not locally store the latest mouse information.

Parameters: None.

Return: A word containing two values: The high word is a record of type UIFunctionsActive , and the low word is a word of ButtonInfo .

Interception: Unlikely.

MSG_VIS_VUP_TERMINATE_ACTIVE_MOUSE_FUNCTION

void	MSG_VIS_VUP_TERMINATE_ACTIVE_MOUSE_FUNCTION();

This message is sent by a visible object to itself to terminate any active mouse function, forcing it to be a function of type "other." This message is used only by the Specific UI library in cases where input synchronization problems occur in specific places. Applications should generally not use this message.

Source: A visible object handling active input events.

Destination: Sent by the visible object to itself.

Interception: This message should not be subclassed.

MSG_VIS_VUP_BUMP_MOUSE

void	MSG_VIS_VUP_BUMP_MOUSE(
        int	xBump,
        int	yBump);

This message causes the UI to bump the pointer image on the screen by the passed offsets as if the user had moved the mouse. It's unlikely your objects will subclass this message; you may, however, use it to bump the mouse. It is most often used by specific UI objects (menus, scrollers) that make the mouse follow their movements.

Source: Unrestricted.

Destination: Any visible object.

Parameters: xBump The horizontal amount to bump the mouse.

yBump

The vertical amount to bump the mouse.

Return: Nothing.

Interception: Unlikely.

Keyboard Events

MSG_META_GRAB_KBD, MSG_META_FORCE_GRAB_KBD, MSG_META_RELEASE_KBD

The keyboard, like the mouse, may be grabbed by visible objects. Keyboard events arrive in the form MSG_META_KBD_CHAR ; a single message represents all different types of keyboard events (unlike mouse events, which can be much more diverse).

To grab the keyboard, the visible object should send itself the message MSG_META_GRAB_KBD . If the grab should be made in any circumstances, the object should use MSG_META_FORCE_GRAB_KBD . To release the keyboard grab, the object should send itself MSG_META_RELEASE_KBD .

MSG_META_GRAB_KBD

void	MSG_META_GRAB_KBD();

A visible object will send itself this message (using @call ) when it wants to gain the keyboard grab. To release the grab, it must send itself a MSG_META_RELEASE_KBD . If it wants to gain the exclusive regardless of whether another object has it, it should use MSG_META_FORCE_GRAB_KBD .

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself to gain the keyboard grab.

Interception: Unlikely--Note that the object must, however, intercept MSG_META_KBD_CHAR to receive the subsequent keyboard events.

MSG_META_FORCE_GRAB_KBD

void	MSG_META_FORCE_GRAB_KBD();

A visible object will send itself this message (using @call ) when it wants to gain the keyboard grab whether or not another object currently has it. To release the grab, the object must later send itself MSG_META_RELEASE_KBD .

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself to force a keyboard grab.

Interception: Unlikely.

MSG_META_RELEASE_KBD

void	MSG_META_RELEASE_KBD();

A visible object that has the keyboard grab must send itself this message to release the grab.

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself to release its keyboard grab.

Interception: Unlikely.

Ink and P en Events

MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK

If a visible object expects and wants Ink input, it should subclass the message MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK . This message queries the visible object, which should return specific values based on the current input state and object bounds.

This message has two default handlers; the default VisClass handler always returns false , indicating that the visible object does not expect Ink input. You can, however, substitute a second default handler for the VisClass handler by adding the following line to your Goc file after the object's class definition:

@method  VisObjectHandlesInkReply, <YourClass>,
                MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK;

This will, in essence, substitute the system-provided routine VisObjectHandlesInkReply() for a subclassed message handler. This routine will do the right thing for the object in interacting with the input manager. All subsequent input events will be considered Ink events.

MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK

void	MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK(
        VisCallChildrenInBoundsFrame					*data);

This message is subclassed by objects that handle Ink input. See above for directions on handling this message. The parameters are five data words that may be modified and the bounds of a rectangle. This message will be sent to all objects whose bounds fall within the passed rectangle.

Source: Unrestricted.

Destination: Any visible object.

Parameters: data A pointer to a VisCallChildrenInBoundsFrame structure containing the bounding rectangle and five words of data. This structure is described below.

Return: Three fields of the VisCallChildrenInBoundsFrame structure pointed to by data will have meaning on return. See the Interception paragraph below to determine whether the return values should be set or not in a subclassed handler.

VCCIBF_data1

Memory handle of the top object desiring ink.

VCCIBF_data2

Chunk handle of the top object desiring ink.

VCCIBF_data3

Upper bound of the object desiring ink.

Interception: If an object wants to receive ink messages, it should do the following things in its handler for this message: First compare the passed VCCIBF_data3 value with the top bound of the object. Then, if the upper bound of the object is less than the VCCIBF_data3 value (or if the value in VCCIBF_data1 is zero), then the object should return the values indicated in the Return paragraph above. Otherwise, if these conditions are not met, it should return with the structures and registers unchanged.

Structures: The VisCallChildrenInBoundsFrame structure is shown below:

typedef struct {
	word		VCCIBF_data1;
	word		VCCIBF_data2;
	word		VCCIBF_data3;
	word		VCCIBF_data4;
	word		VCCIBF_data5;
		/* Five data words as described above */
	Rectangle		VCCIBF_bounds;
		/* bounds must be in the coordinate
		 * system of the parent of the caller */
} VisCallChildrenInBoundsFrame;

VisClass: 5 Working with Visible Object Trees

Visible objects can not be used unless they are placed within object trees. The top object of the tree must be of a subclass of VisContentClass . Other objects in the tree can be of any visible object class. Keep in mind, however, that VisClass objects can not have children; only the composite classes ( VisCompClass and VisContentClass ) may have children. Therefore, VisClass is useful only for leaf objects.

Each visible object has a VI_link instance field. This field specifies the optr of that object's next sibling in the tree. Since this is a field of VisClass , both composites and noncomposites have it. Composite objects also have a VCI_comp field which contains the optr of the composite's first child. Thus, visible trees use the same format as normal object trees.

Creating and Destroying

Adding and Removing

Getting Visible Tree Information

Sending Messages Through the Tree

Visible Object Window Operations

VisClass: 5.1 Working with Visible Object Trees: Creating and Destroying

MSG_VIS_DESTROY

Visible objects are just like any other objects in the ways they are created and destroyed. You can create visible objects in many ways; the easiest is to set them up in a resource and simply load or duplicate the resource block at run-time. You can also use the ObjInstantiate() routine to instantiate new visible objects on the fly from your predefined subclass of VisClass , VisCompClass , or VisContentClass . the GEOS Programming chapter details how to instantiate a new object of a given class.

Destroying visible objects is very simple. You only need to use the message MSG_VIS_DESTROY , which works on a visible object and all its children (if it has any). This message removes the visible branch from the screen if necessary, detaches the visible objects from the visible tree, and then destroys the object (freeing its instance chunk). The only thing the object must do is clean up after itself--in its MSG_META_DETACH or MSG_META_FINAL_OBJ_FREE handler, it should free any memory that it allocated explicitly for its own use, for example.

MSG_VIS_DESTROY also marks the destroyed object's parent invalid both in geometry and image so the tree will be updated properly.

MSG_VIS_DESTROY

void	MSG_VIS_DESTROY(
        VisUpdateMode updateMode);

This message is the high level routine for destroying branches of visible trees. This message will close and destroy the entire branch, unlinking any visible objects in the branch under the recipient object. The parent of the removed branch will be marked invalid for later visual update. This message may be subclassed to replace the geometry update handling, but this is not easily done and is rare.

Source: Unrestricted.

Destination: Any visible object (or head of a visible branch).

Parameters: updateMode A VisUpdateMode that determines when the visible parent of the destroyed object/branch will be updated on the screen.

Return: Nothing.

Interception: Unlikely--may be subclassed if the parent is not to be marked invalid. This is extremely rare.

VisClass: 5.2 Working with Visible Object Trees: Adding and Removing

MSG_VIS_ADD_CHILD, MSG_VIS_REMOVE, MSG_VIS_REMOVE_CHILD, MSG_VIS_MOVE_CHILD, MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD, MSG_VIS_REMOVE_NON_DISCARDABLE_VM_CHILD, MSG_VIS_REMOVE_NON_DISCARDABLE

Once you have objects instantiated, you can connect them together into an object tree. If you know the structure of your tree beforehand, you can create the tree explicitly in your .goc file, just as you would create your generic object tree.

For many purposes, however, a dynamic object tree is much more useful. To use it, you must be able to add and remove objects easily as well as move them within the tree easily.

Adding and Removing Normally

To add an object to a branch of a visible tree, use the message MSG_VIS_ADD_CHILD . This message adds a visible object as the child of a composite; if the new child is a composite with its own children, the entire branch is added to the tree. You can add a child at any position in the composite's child list (e.g., as the first child, as the second child, as the last child, etc.), and you can mark the child dirty after addition if you want.

For example, if you have a composite visible object with two children that is currently unattached to any visible tree, you can attach it to a tree with MSG_VIS_ADD_CHILD . The figure above shows this process and the line of code used to add the composite as the second child of an object in the tree.

Note that the child in the example is added as child one. The child list of a composite is zero-based, so the first child is referred to as number zero, the second is number one, and so on. The last child may always be referred to as CCO_LAST; likewise, the first child may always be referred to as CCO_FIRST.

To remove an object or branch from a visible tree, you can use either MSG_VIS_REMOVE or MSG_VIS_REMOVE_CHILD . MSG_VIS_DESTROY may also be used, but only if the entire branch should be destroyed after being removed from the tree. Both MSG_VIS_REMOVE and MSG_VIS_REMOVE_CHILD detach the object from the visible tree and visually update the parent immediately. MSG_VIS_REMOVE , however, should be sent directly to the object being removed, while MSG_VIS_REMOVE_CHILD is sent to the parent of the object being removed. When removing a child from its parent, you can specify the child by position number (e.g., remove the last child or the first child).

You can move a child within its child list with MSG_VIS_MOVE_CHILD . This message is sent to the parent and simply moves the child within the parent's child list. To move a child from one parent to another, you must first remove it and then add it to the other parent with MSG_VIS_REMOVE_CHILD and MSG_VIS_ADD_CHILD . This message, as the others, will move the child's entire branch with it.

Adding and Removing Objects Not Saved to Documents

In many cases, you may save visible objects directly to VM documents using GenDocument objects and the document controllers. In cases like this, the objects you save to the file must not be discarded by the UI if the visible object is taken off the tree or removed. These objects are known as "non-discardable" visible objects stored in a VM file, and unless they're handled specially, they can cause your documents to crash your application.

Any top-level object you save directly to a file must be treated as non-discardable. That is, any object that gets dynamically added to or removed from a visible tree (such as a vis object that gets added as the child of a GenDocument when the document is opened) must be added, removed, and managed as a non-discardable object. There are three messages that deal specifically with non-discardable visible objects; these are detailed below and are MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD , MSG_VIS_REMOVE_NON_DISCARDABLE_VM_CHILD , and MSG_VIS_REMOVE_NON_DISCARDABLE .

MSG_VIS_ADD_CHILD

void	MSG_VIS_ADD_CHILD(
        optr		child,
        CompChildFlags		flags);

This message attaches the passed object as a child of the composite handling the message. If the parent is already opened and on the screen, you must invalidate the child with MSG_VIS_MARK_INVALID , passing the invalidation VOF_WINDOW_INVALID; the composite and child will be updated appropriately according to the VisUpdateMode passed with the invalidation. If, however, the parent is not opened, the child will automatically be opened when the parent is opened.

Source: Unrestricted.

Destination: Any visible composite object.

Parameters: child The optr of the visible object to be added as a child.

flags

A structure of CompChildFlags , described below.

Return: Nothing.

Interception: You should not subclass this message.

Structures: The CompChildFlags structure contains one one-bit flag and one 15-bit unsigned numerical field. These are described below and can be found in metaC.goh .

 typedef WordFlags  CompChildFlags;
#define CCF_MARK_DIRTY					0x8000
#define CCF_REFERENCE					0x7fff

#define CCO_FIRST					0x0000
#define CCO_LAST					0x7FFF

#define CCF_REFERENCE_OFFSET					     0

CCF_MARK_DIRTY

If this flag is set, the object will be marked dirty when added to the tree.

CCF_REFERENCE

The zero-based position of the new child. Other children will be shuffled forward in the child list as necessary. If greater than the number of children, it will be taken to be CCO_LAST.

Two special numbers may be used in the CCF_REFERENCE field:

CCO_FIRST

Add as the first child.

CCO_LAST

Add as the last child.

Warnings: Do not pass the optr of an object that is already the child of another object. The results are unpredictable and will likely result in an error.

MSG_VIS_REMOVE

void	MSG_VIS_REMOVE(
        VisUpdateMode updateMode);

This is the high-level message that closes (if necessary) and removes a visible branch from the object tree. The parent of the branch is marked invalid for visual update according to the passed VisUpdateMode .

Unlike MSG_VIS_DESTROY , this message does not destroy the visible branch but only unlinks it from the tree. This message may not be subclassed by any object. This message is useful for hiding visible branches which may be added again later with MSG_VIS_ADD_CHILD .

Source: Unrestricted.

Destination: Any visible composite object.

Parameters: updateMode The VisUpdateMode used to update the composite from which the child is removed. VUM_MANUAL is not allowed.

Return: Nothing.

Interception: Do not subclass this message.

Warnings: This message will not allow VUM_MANUAL to be passed as the updateMode .

MSG_VIS_REMOVE_CHILD

void	MSG_VIS_REMOVE_CHILD(
        optr		child,
        CompChildFlags		flags);

This message removes the specified child from the object tree. This message should be rarely used and used with care; it does not close the visible branch but simply removes it. Consider using the higher-level MSG_VIS_REMOVE instead. Note that all grabs (focus, gadget, mouse, etc.) must be released by the child and all its children before the branch can be removed safely.

Source: Unrestricted.

Destination: The parent composite of the passed object.

Parameters: child The optr of the child to be removed. If this optr is not among the recipient's children, an error will likely occur.

flags

The CompChildFlags as described in MSG_VIS_ADD_CHILD on typedef WordFlags CompChildFlags; #define CCF_MARK_DIRTY 0x8000 #define CCF_REFERENCE 0x7fff .

Return: Nothing.

Interception: You should not subclass this message.

Warnings: Most likely you should use MSG_VIS_REMOVE instead of this message. MSG_VIS_REMOVE takes care of extra bookkeeping automatically that can be difficult.

MSG_VIS_MOVE_CHILD

void	MSG_VIS_MOVE_CHILD(
        optr		child,
        CompChildFlags		flags);

This message moves a child of the recipient to another location among its siblings. It essentially removes the child from the branch and then re-adds it in the same manner as MSG_VIS_ADD_CHILD . This message does not move the child from one parent to another; you must use a combination of MSG_VIS_REMOVE and MSG_VIS_ADD_CHILD to achieve that.

Source: Unrestricted.

Destination: The parent composite of the passed object.

Parameters: child The optr of the child to be removed. If this optr is not among the recipient's children, an error will likely occur.

flags

The CompChildFlags as described in MSG_VIS_ADD_CHILD on typedef WordFlags CompChildFlags; #define CCF_MARK_DIRTY 0x8000 #define CCF_REFERENCE 0x7fff .

Return: Nothing.

Interception: You should not subclass this message.

MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD

void	MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD(
        optr		child,
        CompChildFlags		flags);

This message performs exactly the same as MSG_VIS_ADD_CHILD except that it also increments the object's in-use count so it will never be discarded. This is used on top objects in visible sub-trees that are saved to document files: The object is added as a non-discardable file when the document is opened, and it is removed as a non-discardable child (with MSG_VIS_REMOVE_NON_DISCARDABLE_VM_CHILD or MSG_VIS_REMOVE_NON_DISCARDABLE ) when the document is closed.

Source: Unrestricted--typically a document object when opening the file.

Destination: The new parent of the visible object being added to the tree.

Parameters: child The optr of the new child being added to the tree.

flags

A record of CompChildFlags indicating where the child should be added. CCF_MARK_DIRTY is ignored in this record.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_REMOVE_NON_DISCARDABLE_VM_CHILD

void	MSG_VIS_REMOVE_NON_DISCARDABLE_VM_CHILD(
        optr	child);

This message performs exactly the same as MSG_VIS_REMOVE_CHILD except that it is used with MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD rather than with MSG_VIS_ADD_CHILD . This message decrements the in-use count before removing the child, thereby undoing the extra increment performed by MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD .

Source: Unrestricted--typically a document object when closing the file.

Destination: The parent of the visible object being removed from the tree.

Parameters: child The optr of the child being removed.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_REMOVE_NON_DISCARDABLE

void	MSG_VIS_REMOVE_NON_DISCARDABLE(
        VisUpdateMode		updateMode)

This message performs exactly the same as MSG_VIS_REMOVE except that it decrements the object's in-use count before removing it. This message should therefore be used in conjunction with the adding message MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD and should not be used with MSG_VIS_ADD_CHILD. Likewise, MSG_VIS_REMOVE should not be used with this MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD.

Source: Unrestricted--typically a document object when closing the file.

Destination: The visible object being removed from the tree.

Parameters: updateMode A VisUpdateMode value indicating when the object should be visibly removed from the tree. VUM_MANUAL is not allowed.

Return: Nothing.

Interception: Generally not intercepted.

VisClass: 5.3 Working with Visible Object Trees: Getting Visible Tree Information

 MSG_VIS_FIND_CHILD, MSG_VIS_FIND_CHILD_AT_POSITION, MSG_VIS_COUNT_CHILDREN, MSG_VIS_FIND_PARENT

When an application manages a visible object tree, it will most likely need to find children, count children, or get the optr of a particular object in the tree. VisClass offers four messages to provide this bookkeeping information. These four messages are listed below.

MSG_VIS_FIND_CHILD

word	MSG_VIS_FIND_CHILD(
        optr	object);

This message returns the zero-based position of the specified child among the parent's children.

Source: Unrestricted.

Destination: Any visible composite object.

Parameters: object The optr of the child to be found.

Return: The zero-based position of the child in the parent's child list. (E.g., the first child returns zero, the second child returns one, the third child returns two, etc.) If object is not the optr of one of the composite's children, the value -1 will be returned. If sent to a non-composite object, the message will also return -1.

Interception: Unlikely.

MSG_VIS_FIND_CHILD_AT_POSITION

optr	MSG_VIS_FIND_CHILD_AT_POSITION(
        word	position);

This message returns the optr of the child occupying the position specified among the recipient's children.

Source: Unrestricted.

Destination: Any visible composite object.

Parameters: position The zero-based position of the child whose optr is to be returned.

Return: The optr of the child occupying the passed position . If no child occupies that position, or if the message is sent to a non-composite object, the retuned value will be NullOptr.

Interception: Unlikely.

MSG_VIS_COUNT_CHILDREN

word	MSG_VIS_COUNT_CHILDREN();

This message returns the number of children the recipient object has. The count is not zero-based; if a composite has five children, this message will return five.

Source: Unrestricted.

Destination: Any visible composite object.

Parameters: None.

Return: The number of children the object has. If the object has no children (includes non-composite objects), the return will be zero.

Interception: Unlikely.

MSG_VIS_FIND_PARENT

optr	MSG_VIS_FIND_PARENT();

This message returns the optr of the recipient's parent composite.

Source: Unrestricted.

Destination: Any visible composite object.

Parameters: None.

Return: The optr of the object's parent composite. If the message is sent to the top node of a visible tree, the return value will be NullOptr.

Interception: Unlikely.

Tips: If you want to send a message to your parent, use the @visParent macro defined in the next section.

VisClass: 5.4 Working with Visible Object Trees: Sending Messages Through the Tree

Often an object will need to contact its parent or children but will not know their precise optrs. Other times, you may need to send a message to a particular object in the tree but don't know where in the tree the object is. GEOS provides several ways to dispatch messages to parents and children and even to objects of a given class.

Contacting Parents and Children Directly

 @visParent,  @visChildren, MSG_VIS_CALL_PARENT, MSG_VIS_SEND_TO_PARENT, MSG_VIS_SEND_TO_CHILDREN

To send a given message to an object's parent (to check valid bounds, to check the parent's state, etc.), you can use the macro @visParent . To do this, substitute the macro in place of the destination object's name, as follows:

kids = @call @visParent::MSG_VIS_COUNT_CHILDREN();

The above call is more efficient than using two message calls for the same thing, as follows:

myParent = @call self::MSG_VIS_FIND_PARENT();
kids = @call myParent::MSG_VIS_COUNT_CHILDREN();

Note that either @call or @send may be used with the @visParent macro.

A similar macro, @visChildren , is offered for sending messages to a composite's children. Note, however, that you can only use the @send keyword to send messages with this macro; there is no way for a single call to collect return values from many different objects. So, if you need to pass pointers to your children, you will have to get each child's optr in turn and dispatch the message to it individually. (Recall that pointers should not be passed with @send because they may be invalidated by the time the message is handled.) The format for using the @visChildren macro is as follows:

@send @visChildren::MSG_VIS_INVALIDATE();

This usage is much more efficient than counting the composite's children and using a loop to get the child's optr and send the child the message.

In addition to providing the above macros, VisClass lets you pass recorded events to a visible object's parent or children. This can be useful, for example, if you need to send a message to another object's parent; you might otherwise first have to find the optr of the object's parent and then send the message directly. Instead, you can use the VisClass messages MSG_VIS_CALL_PARENT and MSG_VIS_SEND_TO_PARENT to pass recorded (encapsulated) events to the recipient's parent.

To send a recorded event to a visible object's children use the message MSG_VIS_SEND_TO_CHILDREN . The recorded event will not be allowed to return anything for the same reason the @visChildren macro can not.

MSG_VIS_CALL_PARENT

void	MSG_VIS_CALL_PARENT(
        EventHandle event);

This message delivers the passed recorded event to the parent of the recipient object. It acts as a call, executing immediately even across threads.

Source: Unrestricted.

Destination: Any visible object.

Parameters: event The event handle of the prerecorded event to be delivered.

Return: Nothing.

Interception: Unlikely.

Tips: In Goc, an object should not send this message to itself; instead, it should use the @visParent macro described above.

MSG_VIS_SEND_TO_PARENT

void	MSG_VIS_SEND_TO_PARENT(
        EventHandle event);

This message delivers the passed recorded event to the parent of the recipient object. It acts as a send, allowing the caller to continue execution without waiting for the event to be handled.

Source: Unrestricted.

Destination: Any visible object.

Parameters: event The event handle of the recorded event to be delivered.

Return: Nothing.

Interception: Unlikely.

Tips: In Goc, an object should not send this message to itself; instead, it should use the @visParent macro described above.

MSG_VIS_SEND_TO_CHILDREN

void	MSG_VIS_SEND_TO_CHILDREN(
        EventHandle event);

This message delivers the passed recorded event to each of the recipient's children. It acts as a message send and can not return values; there is no way for a single message to call several objects and return values from each with a single call.

Source: Unrestricted.

Destination: Any visible composite object.

Parameters: event The event handle of the recorded event to be delivered.

Return: Nothing.

Structures: In Goc, an object should not send this message to itself; instead, it should use the @visChildren macro described above.

Warnings: Do not pass pointers in the recorded event's parameters because the message may not be handled before the pointers are invalidated.

Sending Classed Events Up the Tree

MSG_VIS_VUP_FIND_OBJECT_OF_CLASS, MSG_VIS_VUP_CALL_OBJECT_OF_CLASS, MSG_VIS_VUP_SEND_TO_OBJECT_OF_CLASS, MSG_VIS_VUP_TEST_FOR_OBJECT_OF_CLASS

VisClass has several messages that automatically travel up the visible object tree until they get to an object that meets the proper criteria; they then deliver themselves to that object. This is accomplished by the default handler in VisClass recognizing whether the given object meets the criteria; if it does not, the handler passes the message up to the object's parent.

To find an object of a given class in the tree, use the message MSG_VIS_VUP_FIND_OBJECT_OF_CLASS . This message travels up the tree starting at the recipient until it reaches the first object of that class. So if you are looking for an object of VisCompClass , at the most the message will be passed up a single level.

If you need to send a message to an object of a given class in the visible tree, you can either find it and send it the message or send the message directly with the visible upward messages MSG_VIS_VUP_CALL_OBJECT_OF_CLASS and MSG_VIS_VUP_SEND_TO_OBJECT_OF_CLASS . These messages search up the tree in the same was as MSG_VIS_VUP_FIND_OBJECT_OF_CLASS , and they then deliver the passed event to the resulting object.

To see simply whether an object of a given class exists in the visible tree, use MSG_VIS_VUP_TEST_FOR_OBJECT_OF_CLASS . This is useful if you are going to use MSG_VIS_VUP_CALL_OBJECT_OF_CLASS (or its counterpart). If no object of the given class exists, you can skip sending the recorded message.

To send classed messages to an object in the tree that is of a specific class, you can use TravelOption with certain MetaClass messages. VisClass defines a travel option TO_VIS_PARENT, which sends the message to the first object up the tree that is of the specified class.

MSG_VIS_VUP_FIND_OBJECT_OF_CLASS

optr	MSG_VIS_VUP_FIND_OBJECT_OF_CLASS(
        ClassStruct *class);

This message searches up the visible object tree until it encounters an object of the specified class. It then returns the optr of that object.

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself to find an object of the given class above it in the visible object tree.

Parameters: class A pointer to the ClassStruct structure of the class to be searched for.

Return: The optr of the object of the passed class. If multiple objects of this class exist in the tree, the first encountered will be returned. If no objects of this class are in the tree, a NullOptr will be returned.

Interception: Unlikely--only objects that masquerade as objects of a different class would subclass this message. This practice is highly discouraged.

MSG_VIS_VUP_TEST_FOR_OBJECT_OF_CLASS

Boolean	MSG_VIS_VUP_TEST_FOR_OBJECT_OF_CLASS(
        ClassStruct *class);

This message searches up the visible tree and determines whether an object of the given class is in the tree.

Source: Unrestricted.

Destination: Any visible object--typically sent before MSG_VIS_VUP_CALL_OBJECT_OF_CLASS or MSG_VIS_VUP_SEND_TO_OBJECT_OF_CLASS to ensure that a recipient for the message exists.

Parameters: class A pointer to the ClassStruct structure of the class to be searched for.

Return: True if the class is found; false if it is not.

Interception: Unlikely.

MSG_VIS_VUP_CALL_OBJECT_OF_CLASS

void	MSG_VIS_VUP_CALL_OBJECT_OF_CLASS(
        EventHandle event);

This message searches up the visible tree until it encounters an object of the proper class for the recorded event. The class is specified within the passed event . When the first such object is found, it will be called with the classed event as if an @call had been used with the event directly.

Source: Unrestricted.

Destination: Any visible object--The passed event will be delivered to the first object of the appropriate class, not necessarily to the recipient of the MSG_VIS_VUP_CALL_OBJECT_OF_CLASS .

Parameters: event The event handle of a recorded event.

Return: The classed event delivered by this message may return values as determined by the event. This message returns nothing.

Interception: Unlikely.

MSG_VIS_VUP_SEND_TO_OBJECT_OF_CLASS

void	MSG_VIS_VUP_SEND_TO_OBJECT_OF_CLASS(
        EventHandle event);

This message searches up the visible tree until it encounters an object of the proper class for the recorded event. The class is specified within the passed event . When the first such object is found, the message will be delivered to that object as if an @send had been used with the event directly.

Source: Unrestricted.

Destination: Any visible object--The passed event will be delivered to the first object of the appropriate class, not necessarily to the object that received the MSG_VIS_VUP_SEND_TO_OBJECT_OF_CLASS .

Parameters: event The event handle of a recorded event.

Return: Nothing. The recorded event may not return anything.

Interception: Unlikely.

Warnings: The recorded event should not pass pointers among its parameters.

Visible Upward Queries

MSG_VIS_VUP_QUERY

You can create your own messages that get passed up the visible tree by creating aliases of MSG_VIS_VUP_QUERY . MSG_VIS_VUP_QUERY , by itself, does nothing useful; it simply gets passed up the visible tree without ever being handled.

You can create your own visible queries to return different types of values from objects higher up in the object tree. Take, for example, a music-teaching application which uses note objects as distant children of a sheet music object. If the note objects needed to know what key they were supposed to be in, they would query up the tree with a special upward query message. If we assume the sheet music object kept this information, it would want to respond to the query message with the appropriate value. Thus, the sheet music class would have a line similar to the following:

@alias(MSG_VIS_VUP_QUERY)
        MusicKeyType MSG_VIS_VUP_QUERY_MUSIC_KEY();

This line creates an alias for the general-purpose upward query. The sheet music object should have a handler for MSG_VIS_VUP_QUERY_MUSIC_KEY in which it figures out and returns the appropriate key. This type of upward query can be invaluable in many different situations.

MSG_VIS_VUP_QUERY

void	MSG_VIS_VUP_QUERY();

This message simply queries up the tree until it is handled. It is extensible so visible objects can implement their own upward queries without adding handlers to every class in between it and the query handler.

It is extremely rare that any object would send or handle MSG_VIS_VUP_QUERY on its own; many classes, however, may alias this message and create their own versions of the upward query.

Source: Unrestricted--see note above.

Destination: Any visible object--see note above. Typically sent by a visible object either to itself or directly to its visible parent.

Parameters: None--an alias of this message may have parameters.

Return: Nothing--an alias of this message may have return values.

Interception: MSG_VIS_VUP_QUERY itself should not be intercepted. Its aliases, however, should be intercepted by the appropriate classes that will handle them.

Sending Messages to Window Groups

MSG_VIS_VUP_CALL_WIN_GROUP, MSG_VIS_VUP_SEND_TO_WIN_GROUP

VisClass offers two specific messages for contacting window group objects in a visible tree. These are similar to MSG_VIS_VUP_CALL_OBJECT_OF_CLASS and MSG_VIS_VUP_SEND_TO_OBJECT_OF_CLASS , except they find the window group of the recipient and deliver the event to the window object. These two messages are detailed below.

MSG_VIS_VUP_CALL_WIN_GROUP

void	MSG_VIS_VUP_CALL_WIN_GROUP(
        EventHandle event);

This message searches up the visible object tree until it encounters a window group object. When the first window group is found, it will be called with the classed event as if an @call had been used.

Source: Unrestricted--typically sent by a visible object to itself to deliver the event to its window.

Destination: Any visible object--the passed event will be delivered to a window object, not necessarily to the object that receives the MSG_VIS_VUP_CALL_WIN_GROUP .

Parameters: event The event handle of a recorded event to be delivered to the window object.

Return: The passed event may return its own values, but MSG_VIS_VUP_CALL_WIN_GROUP returns nothing.

Interception: Unlikely.

See Also: MSG_VIS_VUP_CALL_OBJECT_OF_CLASS.

MSG_VIS_VUP_SEND_TO_WIN_GROUP

void	MSG_VIS_VUP_SEND_TO_WIN_GROUP(
        EventHandle event);

This message searches up the visible object tree until it encounters a window group object. When the first window group is found, the passed event will be delivered to that object as if an @send had been used directly.

Source: Unrestricted--typically sent by a visible object to itself to deliver the event to its window.

Destination: Any visible object--the passed event will be delivered to a window object, not necessarily to the object that receives the MSG_VIS_VUP_CALL_WIN_GROUP .

Parameters: event The event handle of a recorded event to be delivered to the window object.

Return: Nothing. The recorded event may not return values.

Interception: Unlikely.

Warnings: The recorded event may not pass pointers among its parameters.

See Also: MSG_VIS_VUP_SEND_TO_OBJECT_OF_CLASS.

VisClass: 5.5 Working with Visible Object Trees: Visible Object Window Operations

MSG_VIS_OPEN_WIN, MSG_VIS_CLOSE_WIN, MSG_VIS_WIN_ABOUT_TO_BE_CLOSED, MSG_VIS_MOVE_RESIZE_WIN

Typically, windows will be managed entirely by generic UI objects and the Specific UI library currently in use. You can, however, manage your own VisClass -based window objects by using messages normally used only by Specific UI objects. This is a difficult and complex task, however, and it is not recommended. The four messages used for this purpose are detailed below.

MSG_VIS_OPEN_WIN

void	MSG_VIS_OPEN_WIN(
        WindowHandle parentWindow);

This message is sent to a window or portal object to open its window. The graphics window will be opened and drawn on the screen, and a visual update will propagate down the displayed visible tree.

Source: Visual update mechanism.

Destination: A window group (VTF_IS_WINDOW) or portal (VTF_IS_PORTAL) object.

Parameters: parentWindow The window handle of the open window in which the new window will be created.

Return: Nothing.

Interception: The window group or portal must intercept in order to open the new graphics window and set initial parameters ( VCI_window ).

MSG_VIS_CLOSE_WIN

void	MSG_VIS_CLOSE_WIN();

This message is sent to a window or portal object that has its graphics window currently on the screen. The window and its visible branch will be closed (taken off the screen).

Source: Visual update mechanism.

Destination: A window group (VTF_IS_WINDOW) or portal (VTF_IS_PORTAL) object.

Interception: The window group or portal may intercept if more needs to be done than simply closing the graphics window.

MSG_VIS_WIN_ABOUT_TO_BE_CLOSED

void	MSG_VIS_WIN_ABOUT_TO_BE_CLOSED();

This message notifies the recipient that the window it's displayed in is about to be closed. The default handler for this will remove the visible branch of the window off the screen so no redraws will occur before the window closes.

Source: Visual update mechanism.

Destination: The window group (VTF_IS_WINDOW) or portal (VTF_IS_PORTAL) object that is being closed; the message will then propagate down the visible tree.

Interception: May be intercepted by either the window group or the VisContent object if the default behavior is not appropriate for the object.

MSG_VIS_MOVE_RESIZE_WIN

void	MSG_VIS_MOVE_RESIZE_WIN();

This message causes the window object to move and/or resize itself based on the bounds of its content object. This message is used only by window or portal objects and is rarely, if ever, used by objects in your applications.

Source: Part of the visual update mechanism--typically called by the window object on itself in its MSG_VIS_UPDATE_WINDOWS_AND_IMAGE handler.

Destination: The window group (VTF_IS_WINDOW) or portal (VTF_IS_PORTAL) object to be resized or moved.

Interception: The window object may intercept if it does not want to resize to the bounds of its content object.

VisClass: 6 Visible Layers and 32-Bit Graphics

MSG_VIS_LAYER_SET_DOC_BOUNDS, MSG_VIS_LAYER_GET_DOC_BOUNDS, MSG_VIS_LAYER_INSERT_OR_DELETE_SPACE

The GEOS graphic space is built on a basis of 16-bit coordinates. A few applications, however, will require much more space for their documents. GEOS also supports the special use of 32-bit coordinates; applications using these coordinates are said to be using the "large document" model.

The visible object library was originally designed with 16-bit coordinates in the default GEOS graphics space. All instance data, message parameters and return values, and coordinates are assumed to be word-sized integers. A large-document visible object library is not provided primarily because there is no single visible model that works well with large coordinates, and also because no single large model works efficiently for all applications.

It is possible, however, for applications to subclass the standard visible classes in order to get them to support the large document model. In order to do this, however, you must understand the basic issues involved with the large model and with using 32-bit coordinates.

As the application developer, you should read the following sections if you will be using the large document model. Each one deals with a different problem facing applications that want large documents.

In addition, some complex applications may offer several different visible layers in the program. For example, a spreadsheet might want to include a graphic object layer for graphics and charts. The content object of the visible tree can be set up to have several different children, each of which is a "layer" that manages its own objects in the window.

The content in charge of the layers must occasionally set and retrieve the document bounds of its children. For example, if the user wants to set the page size of the spreadsheet that has a graphical layer, the content object must set the new size for all its children. To retrieve the current document bounds of a particular object, send it a MSG_VIS_LAYER_GET_DOC_BOUNDS . To set the document bounds, send a MSG_VIS_LAYER_SET_DOC_BOUNDS . In addition, the application may add or delete space into a layer with MSG_VIS_LAYER_INSERT_OR_DELETE_SPACE ; for example, if a spreadsheet needs to resize a column, it must send this message to the graphic layer to ensure the layers handle the sizing properly.

MSG_VIS_LAYER_SET_DOC_BOUNDS

void	MSG_VIS_LAYER_SET_DOC_BOUNDS(@stack
        sdword	bottom,
        sdword	right,
        sdword	top,
        sdword	left);

This message sets the 32-bit document bounds for a particular layer object. This message is typically sent by a VisContent object to its children, which are assumed to be layer objects.

Source: Unrestricted--typically sent by a VisContent to its large children.

Destination: Any large (32-bit) visible object or composite.

Parameters: all The four parameters describe the new bounds of the large document. Since layer objects typically cover the entire document, the layer object will set its bounds to these values.

Return: Nothing.

Interception: All layer objects and large objects must subclass this message. There is no default handler.

MSG_VIS_LAYER_GET_DOC_BOUNDS

void	MSG_VIS_LAYER_GET_DOC_BOUNDS(
        RectDWord *bounds);

This message returns the 32-bit document bounds of a particular large visible object. Typically, a VisContent will query its large children with this message when it needs to know their bounds.

Source: Unrestricted--typically sent by a VisContent to its large children.

Destination: Any large (32-bit) visible object or composite.

Parameters: bounds A pointer to an empty RectDWord structure that describes a set of large bounds.

Return: The pointer to the filled RectDWord structure. The structure should, upon return, contain the 32-bit bounds of the large visible object.

Interception: All layer objects and large objects must subclass this message. There is no default handler.

Structures: The RectDWord structure is show below for convenience:

typedef struct {
    sdword   RD_left;
    sdword   RD_top;
    sdword   RD_right;
    sdword   RD_bottom;
}  RectDWord;

MSG_VIS_LAYER_INSERT_OR_DELETE_SPACE

void	MSG_VIS_LAYER_INSERT_OR_DELETE_SPACE(
        InsertDeleteSpaceTypes 			type,
        DWFixed 			spaceY,
        DWFixed 			spaceX,
        DWFixed 			positionY,
        DWFixed 			positionX)

This message should be sent by one layer to another when it changes sizes. An example would be a spreadsheet application with a graphic layer; when a column in the spreadsheet resizes, the graphic layer must resize accordingly.

Source: Any visible layer object.

Destination: The visible layer object requiring resizing.

Parameters: type InsertDeleteSpaceType specifying what sort of operation is taking place.

spaceX , spaceY

Change in space for the x and y directions.

positionX , positionY

Change in x and y position.

Return: Nothing.

Interception: This message must be intercepted; it has no default behavior.

Using Visible Document Layers

Using 16-Bit Drawing Commands

The 16-Bit Limit on Visual Bounds

Handling MSG_VIS_DRAW

Managing 32-Bit Geometry

Handling Mouse Events

Setting Up the Objects

VisClass: 6.1 Visible Layers and 32-Bit Graphics: Using Visible Document Layers

The first issue with large documents is the basic structure of the visible tree. The topmost object of a large visible tree must be able to keep track of information about the current translations and coordinates being used. Typically, the topmost object would be a subclass of VisContentClass ; this does not change with large trees, though another consideration has to be taken care of.

A content object should not contain any information about the document itself; the content object should not be stored along with other document information. Thus, the object that acts as the content can not be the object that also manages the 32-bit document space. Instead, it is easiest to use a VisCompClass object to manage the document space and to place this object as a child of the content.

In addition, you can set up several different composite children of the content, each one managing its own large document space. Each one of these composites is called a "layer object" and manages a "layer" of the document. This way, you can have several different layers (such as a spreadsheet layer and a graphic layer) in the same document. The layer object should manage the calculations and translations necessary for supporting the large document space.

VisClass: 6.2 Visible Layers and 32-Bit Graphics: Using 16-Bit Drawing Commands

All the GEOS drawing commands are based on 16-bit coordinates. Drawing may only occur within a 16-bit graphics space. The graphics system does, however, support extended translations of the 16-bit graphics space within 32-bit coordinates.

This means that you can think of the large document space as a number of smaller, 16-bit "local" graphics spaces. When you need to draw anything, you first use an extended translation to get near your drawing point in the large document. Then you can draw using 16-bit offsets from the point to which you translated.

The application using the extended translation can do so in two different ways: It can store a 32-bit translation with each visible object, or it can store a 32-bit translation in a visible composite, thereby making the entire visible branch under the composite in a 32-bit graphics space. Visible trees implementing layer objects must use the second option; the layer must contain the translation for the entire visible branch that it manages. If a simple large visible tree does not need layers, it may wish to use the first solution.

The first of the two solutions is simple but takes up additional memory and time; each object, when it draws, must translate the coordinates, draw, then translate back. Two translations for each object could significantly affect drawing performance unless visual updates are handled carefully.

The other solution, storing a translation in the composite object, requires just two translations for the entire branch headed by the composite. Whenever the composite receives MSG_VIS_DRAW or MSG_VIS_VUP_CREATE_GSTATE , it executes the translation on the GState. As long as the translation is always relative to the GState's current transformation (done using GrApplyTranslationDWord() ), and as long as the translation is undone before the GState is returned to the caller, drawing will be done properly.

VisClass: 6.3 Visible Layers and 32-Bit Graphics: The 16-Bit Limit on Visual Bounds

Individual visual objects have 16-bit bounds. If the rules of drawing in the 32-bit graphics space are followed, this is not a problem. Individual objects are constrained to 16-bit width and 16-bit height, however.

The only objects for which having 16-bit bounds is a problem are the tree's content object and all the layer objects. This is because these two types of objects must have width and height greater than 16 bits. This problem is handled differently for each object:

For the content object, the VI_bounds field is set to all zeros and is not used. Normally, the content uses its bounds to set the document size in the GenView; the responsibility for setting the GenView's document size then falls to the application.

For the layer object, the VI_bounds field is set to all zeros and is not used. If the bounds of the layer object are important to the application, the layer object must be given new instance fields to hold the 32-bit coordinates of the bounds. If not, nothing needs to be done; the bounds can simply be ignored.

VisClass: 6.4 Visible Layers and 32-Bit Graphics: Handling MSG_VIS_DRAW

In normal-sized visible trees, MSG_VIS_DRAW gets sent to all objects in the tree. This draws the entire visible tree, no matter what portions are visible on the screen. For large documents, this can quickly get unwieldy and inefficient.

A better solution is for the layer object of each particular layer to intercept MSG_VIS_DRAW and pass it on only to those objects in the affected portion of the document. For this to work, of course, the layer object must know something of the structure and composition of the visible branch below it. This is the primary reason the visible object library does not offer a standard visible layer class--in essence, it must be defined specifically for each application.

VisClass: 6.5 Visible Layers and 32-Bit Graphics: Managing 32-Bit Geometry

Because visible objects and composites maintain their 16-bit bounds in a large document, they can still use the 16-bit geometry manager. Layer objects, however, can not use the geometry manager. All geometry management on the layer level (child positioning, resizing, etc.) must be done by the layer object itself in conjunction with its child composites.

VisClass: 6.6 Visible Layers and 32-Bit Graphics: Handling Mouse Events

The GenView is built to support large documents, though its default is normal-sized documents. Thus, you can request the view to send large mouse events, which carry with them 32 bits of integer and 16 bits of fraction in each dimension. The visible classes have no default handlers for these messages, so your own classes will have to handle them appropriately.

The large mouse events are the equivalent of their 16-bit counterparts. They just carry different data to represent the coordinates of the pointer. All the mouse events, both large and normal, are described in the Input chapter.

Normal composite objects will not be affected by large mouse events; the composite will continue to send the event on to the proper child as if it were in a 16-bit document. Layer and content objects, however, must process these messages differently.

If no object within the visible tree has the mouse grabbed, the content of the tree must decide which layer object should receive the mouse events. How the content and layer objects negotiate this is up to the particular application; some applications may consider that one layer is "on top of" the others, and other applications may determine which layer is the most appropriate based on the event context. By default, the large mouse events are passed by VisContentClass straight on to the first layer child. If you want a more complex scheme, you will have to subclass VisContentClass and intercept these messages.

VisClass: 6.7 Visible Layers and 32-Bit Graphics: Setting Up the Objects

Finally, you should be aware of what attributes to set in both the GenView and the VisContent objects of your visible tree to support the large document. You could easily find this out by looking through the various attributes of those classes (and you are encouraged to do so), but the following guide is provided for convenience:

In the GenView object, set GVA_WINDOW_COORDINATE_MOUSE_EVENTS in the GVI_attrs instance data field. This will pass mouse events in terms of offsets from the upper-left corner of the view window rather than in absolute document coordinates. VisContentClass handles these events and automatically turns them into document coordinates.

In the VisContent, set VCNA_WINDOW_COORDINATE_MOUSE_EVENTS and VCNA_LARGE_DOCUMENT_MODEL in the VCNI_attrs field. The first of these tells the content that it will receive input events in window coordinates rather than in document coordinates. The second will have the effect of making the content object ignore its bounds field and geometry management. It will also tell the content that all its children are layer objects. Setting the large document model will cause the content to send all the following messages on to all its children rather than handle them directly: MSG_VIS_DRAW , MSG_VIS_CONTENT_VIEW_ORIGIN_CHANGED , MSG_VIS_CONTENT_VIEW_SCALE_FACTOR_CHANGED , and MSG_VIS_CONTENT_VIEW_SIZE_CHANGED .

You do not have to create all the objects you may need; be aware that the Graphic Object Library provides its own layer object that supports a 32-bit graphic object layer. The spreadsheet object also exports its own layer object.

Requirements of Layer Objects

Layer objects will need to handle MSG_VIS_LAYER_SET_DOC_BOUNDS , which will be sent to all layers when the document bounds change.

In essence the layer object's job is to isolate its children and their children from the fact that they are in a 32-bit document rather than a 16-bit document. In order to do this, layer objects must do several things:

• Store the translation
  This is a set of 32-bit translation offsets. These offsets represent the current location, if any, where the layer is being drawn in the 32-bit coordinate space.
• Intercept MSG_VIS_DRAW
In its handler, the layer should apply any 32-bit translations (using GrApplyTranslationDWord() ) on the GState provided by MSG_VIS_DRAW . It should then intelligently select which of its children are affected by the drawing event and pass the message on to them with the translated GState. The handler should then untranslate the GState before returning.
• Intercept MSG_VIS_VUP_CREATE_GSTATE
In the handler, the layer must first call its superclass (to create the GState normally), then apply the necessary translation using GrApplyTranslationDWord() . It can then return the translated GState.
• Intercept and handle large mouse events
  Each large mouse event that may be interesting to the layer must be handled by the layer object. This is to ensure that mouse events that occur when no object has the mouse grab get handled. If the layer has 16-bit visible children, it should translate the mouse event into small mouse events before passing it to its superclass. If the layer has 32-bit visible children, it should first translate both mouse coordinates and then decide which of its large children should receive the event.

Requirements of 32-bit Visible Objects

Large visible objects in the visible tree should be equipped to handle both large and small mouse events. This is because the parent object may have both 32-bit and 16-bit children. If it does, it will have to send out only small mouse events; otherwise, the 16-bit objects would be confused by the large mouse events.

Requirements of 16-bit Visible Objects

Because 16-bit objects are the norm and not the exception, there are few requirements for them. However, 16-bit objects in 32-bit documents must do one thing: they must prevent the system from allowing the user to select the object and then drag-scroll too far. To prevent this from happening, the visible object must call MSG_VIS_VUP_SET_MOUSE_INTERACTION_BOUNDS to set a temporary boundary on drag scrolling.

VisClass: 7 VisClass Error Checking

MSG_VIS_VUP_EC_ENSURE_WINDOW_NOT_REFERENCED, MSG_VIS_VUP_EC_ENSURE_OBJ_BLOCK_NOT_REFERENCED, MSG_VIS_VUP_EC_ENSURE_OD_NOT_REFERENCED

VisClass provides three messages you can use for special error checking. These three messages are provided especially to make sure that all objects being destroyed or removed will be destroyed cleanly. The default handlers for these messages should cause a fatal error if their criteria are not met.

MSG_VIS_VUP_EC_ENSURE_WINDOW_NOT_REFERENCED

void	MSG_VIS_VUP_EC_ENSURE_WINDOW_NOT_REFERENCED(
        WindowHandle window);

This message travels up the visible object tree, ensuring that the window handle passed is not stored anywhere that it might cause trouble. This message may be used when a window is being destroyed and its handle is about to be freed.

Source: Unrestricted.

Destination: Any visible object in the affected visible tree.

Parameters: window The handle of the window being destroyed.

Return: Nothing--if it returns, no error was encountered.

Interception: Do not intercept this message.

MSG_VIS_VUP_EC_ENSURE_OBJ_BLOCK_NOT_REFERENCED

void	MSG_VIS_VUP_EC_ENSURE_OBJ_BLOCK_NOT_REFERENCED(
        MemHandle objBlock);

This message travels up the visible object tree, ensuring that the memory handle (the handle of an object block) passed is not stored anywhere that it might cause trouble. This message may be used just before the object block's handle is freed to ensure that no stale references will remain.

Source: Unrestricted.

Destination: Any visible object in the affected visible tree.

Parameters: objBlock The handle of the block being freed.

Return: Nothing--if it returns, no error was encountered.

Interception: Do not intercept this message.

MSG_VIS_VUP_EC_ENSURE_OD_NOT_REFERENCED

void	MSG_VIS_VUP_EC_ENSURE_OD_NOT_REFERENCED(
        optr	object);

This message travels up the visible object tree, ensuring that the optr passed is not stored by any objects in the tree. This message may be sent when the object is being destroyed; any objects methods encountering a match between a stored optr and the passed optr should force a fatal error.

Source: Unrestricted.

Destination: Any visible object in the affected visible tree.

Parameters: object The handle of the object being destroyed.

Return: Nothing--if it returns, no error was encountered.

Interception: Do not intercept this message.

VisClass: 8 Creating Specific UIs

It is possible, using visible object classes, to create your own specific UIs. It is a complex and difficult task, however, and only very few developers will expect to do this. Documentation on creating a custom specific UI may appear either in a future release of this documentation or under separate cover. Contact Geoworks Developer Products for more information.

VisClass: 9 Basic Summary

Visible objects are involved in several basic operations, each of which has its own primary messages:

• Drawing
  Vis objects must handle MSG_VIS_DRAW ( MSG_VIS_DRAW ) if they are to draw after their window has been exposed. Objects wishing to redraw themselves outside of exposure events can call MSG_VIS_VUP_CREATE_GSTATE ( MSG_VIS_VUP_CREATE_GSTATE ) to create a GState in their view windows for drawing.
• Being added to an object tree
  When an object is added to a visible tree, it must then force a redraw of the tree. It can be added to the tree with MSG_VIS_ADD_CHILD ( MSG_VIS_ADD_CHILD ), and the tree can be updated with MSG_VIS_VUP_UPDATE_WIN_GROUP ( MSG_VIS_VUP_UPDATE_WIN_GROUP ).
• Being removed from an object tree
  A visible object may be removed from a visible tree with MSG_VIS_REMOVE ( MSG_VIS_REMOVE ). This message will close the object (take it off the screen) and then segregate it from its parent.
• Undergoing visual update
  The visual update mechanism is automatic for the most part. An object that requires visual update, however, can use MSG_VIS_MARK_INVALID ( MSG_VIS_MARK_INVALID ) in conjunction with MSG_VIS_VUP_UPDATE_WIN_GROUP ( MSG_VIS_VUP_UPDATE_WIN_GROUP ) to cause the update.
• Geometry management
  Geometry management of visible objects can be as simple as setting a few flags in the instance data or as complex as manually setting position and size of the objects. For a full description of geometry management of visible objects, see Positioning Visible Objects .
• Being Destroyed
  Visible objects may be destroyed even when they are part of a visible tree that is on the screen. MSG_VIS_DESTROY ( MSG_VIS_DESTROY ) first removes the object from the tree (with MSG_VIS_REMOVE ) and then destroys it (through the MetaClass detach and destroy mechanisms).