VisClass: 4.2 Using VisClass: Drawing to the Screen

One of the main features of visible objects is their ability to draw themselves on the screen. The visible tree does not have to detect when drawing or redrawing should be done; the UI will do this automatically through the window system and the GenView object.

Visual Updates

MSG_VIS_OPEN, MSG_VIS_CLOSE

The visible tree will have to draw or redraw itself when a portion of its GenView window becomes newly exposed. The GenView keeps track of its window and will notify its content when any portion of the window becomes exposed. Exposure can occur from several events: The view window could be newly created; another window could have been moved, exposing the view's window; or the view window could have been scrolled.

Each of these exposure events looks exactly the same to the visible tree. When one of them occurs, the GenView will send a MSG_META_EXPOSED to its content object. The content (a VisContent or GenDocument if you're using a visible tree) will create a GState for the window and translate the MSG_META_EXPOSED into a MSG_VIS_DRAW . It will then send this MSG_VIS_DRAW to itself.

The default handler for MSG_VIS_DRAW in a composite is to simply pass the message on to all of the composite's children. There is no default behavior for MSG_VIS_DRAW in VisClass .

Any object (content, composite, or leaf) that wants to represent itself on the screen must handle MSG_VIS_DRAW . Any composite that subclasses this message must be sure to pass it on to all of its children with the following line:

@send @visChildren:: MSG_VIS_DRAW(drawFlags, gstate);

Redrawing is not initiated only by the view window becoming exposed. It can also be initiated by some portion of the visible tree changing so that it needs to be redrawn (e.g., a child is moved from one composite to another, which may have an effect on the visual representation of the composite). Typically, any change that necessitates a redrawing will automatically generate a MSG_VIS_DRAW to the appropriate objects. These operations, however, will require a VisUpdateMode to be passed along with the other parameters.

All of the above assumes that the visible object is "open" or "realized." If an object is not open, it will not appear on the screen or as part of a composite's geometry calculations. When a window is first created, the window's content is automatically opened with MSG_VIS_OPEN . In the case of a visible tree attached to a GenView, this means that the VisContent object will be opened along with the window. All of the VisContent's children will also be opened automatically (assuming their VOF_WINDOW_INVALID bits are set, which is true the first time a visible object comes up).

If a visible object is added to an already-opened composite, the child will automatically be opened and marked invalid. This will cause the composite's geometry and image to be updated during the next visual update. If a child is added to a composite that is not currently open, the child will not be opened.

Although it is rarely done directly, you can manually open a visible object with the message MSG_VIS_OPEN , and you can "close" an object (remove it from the screen and from the tree's geometry calculations) with MSG_VIS_CLOSE . To open or close an entire branch of the visible tree, you can send the appropriate message to the top composite object in the branch. The message will propagate down through all the visible children.

MSG_VIS_OPEN

void	MSG_VIS_OPEN(
        WindowHandle window);

This message is part of the visual update mechanism and will be sent by the system when an object must be visually updated to appear on the screen. It will be sent to any VOF_WINDOW_INVALID objects in a branch whose VTF_IS_WIN_GROUP object has become VA_VISIBLE. Any object added into a visible tree having VOF_WINDOW_INVALID set will receive a MSG_VIS_OPEN at the next visual update. This message propagates down the visible tree and does not cross over boundaries of window groups. This message is often subclassed by objects that want to initialize some information before being drawn on the screen. If an object subclasses this message, it should be sure to call its superclass somewhere in the handler.

Source: Visual update mechanism.

Destination: Any visible object.

Parameters: window Handle of window in which the object is to appear, or zero if it should appear in the top window object.

Return: Nothing.

Interception: Will be intercepted by objects that want to initialize certain data or take certain actions before being drawn on the screen. Any intercepting objects must call the superclass somewhere in their handler.

MSG_VIS_CLOSE

void	MSG_VIS_CLOSE();

This message is part of the visual update mechanism and is sent to objects that are being taken off the screen. The system will send this message to any objects in a visual branch whose VTF_IS_WIN_GROUP object is set not visible (~VA_VISIBLE). This message closes appropriate windows and propagates to all children to the bottom leaf objects of the visible branch. This message will not cross window group boundaries; if a lower VTF_IS_WIN_GROUP object is encountered during the message propagation, an error will likely occur. Therefore, lower window groups must be closed before higher window groups may be closed.

Source: Visual update mechanism.

Destination: Any visible object.

Interception: Will be intercepted by objects that want to do something as it is being taken off the screen. Any objects that intercept the message must call their superclasses in the handlers.

VisUpdateMode

VisUpdateMode is an enumerated type that determines when and how the visible tree will be visually updated when its image or geometry becomes invalid. This type has four enumerations, described below:

VUM_MANUAL: This mode indicates that the UI should not update at all after this change. Instead, the visual update will be initiated manually later on.
VUM_NOW: This mode indicates that the visual update should occur immediately after the change is effected.
VUM_DELAYED_VIA_UI_QUEUE: This mode indicates that the visual update should occur only when the UI queue is completely empty (indicating no further changes are coming).
VUM_DELAYED_VIA_APP_QUEUE: This mode indicates that the visual update should occur only when the application's queue is empty (indicating that no more changes are coming). This mode is very useful for making several changes that each require an update; it will put the updating off until the very end and will cause only a single update.

A VisUpdateMode is passed as a parameter to certain Vis and Gen messages. These messages typically have some effect on the visual representation of the objects--either on the geometry or on the image itself.

The Initial GState

 MSG_VIS_VUP_CREATE_GSTATE

For any drawing to occur, a graphic state must exist. The graphic state typically is associated with the GenView's window and is created automatically, either when the window is first realized on the screen or when an exposure event occurs.

To create a GState, the system generates a MSG_VIS_VUP_CREATE_GSTATE and sends it to the object that first requires a visual update. This message travels up the visible tree until it gets to a window group (an object with its VTF_IS_WINDOW flag set), and then it creates a GState associated with that window object. Sometimes a content object will subclass this message to set up its own display information before the GenView window can create the new GState. The other time in which this message may be subclassed is by a content that manages a 32-bit graphics space; the content will have to translate the gstate to the proper position in the large document before letting other objects use it.

MSG_VIS_VUP_CREATE_GSTATE

GStateHandle MSG_VIS_VUP_CREATE_GSTATE();

This message travels up the visible object tree until it reaches either the root object or a window group object. It then creates a graphic state associated with that object; this graphic state is then used for the subsequent visual update. You may wish to subclass this message in order to alter the GState created or to set it up to take 32-bit coordinates. If you subclass it, however, be sure to call the superclass somewhere in the handler.

Source: Unrestricted--typically sent by a visible object to itself.

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

Parameters: None.

Return: The GStateHandle of the newly-created GState.

Interception: Unlikely--VisContent objects may intercept this message to translate the returned GState in a 32-bit graphics space. In this case, the VisContent must first call its superclass, then translate the GState appropriately before returning.

Retrieving the Current Window Handle

MSG_VIS_QUERY_WINDOW

Often a visible object will require the window handle of the window it's currently residing in. Some objects, for example, will want to force visual updates in real-time, and they can do this by using the current window handle, creating a special GState for it, and drawing to that GState. The visible object can either cache the window handle when the window is first opened, or it can retrieve it with MSG_VIS_QUERY_WINDOW .

MSG_VIS_QUERY_WINDOW

WindowHandle MSG_VIS_QUERY_WINDOW();

This message returns the window handle of the window the object currently resides in. In many cases, this will be the window handle of a GenView window.

Source: Unrestricted.

Destination: Any visible object--typically sent by a visible object to itself to retrieve its current window handle.

Parameters: None.

Return: The window handle of the object's current window.

Interception: Unlikely.

Causing Redrawing

MSG_VIS_BOUNDS_CHANGED, MSG_VIS_REDRAW_ENTIRE_OBJECT, MSG_VIS_INVALIDATE, MSG_VIS_MARK_INVALID, MSG_VIS_INVAL_TREE, MSG_VIS_ADD_RECT_TO_UPDATE_REGION

If your visible tree contains a composite that manages its own children, chances are you'll need to force a visual update after certain changes occur. For example, if you have an object that can be moved with the mouse, it will probably want to erase its image and redraw itself somewhere else after the move; since the geometry manager is not involved here, the object must force a redrawing of the affected portion of the visible tree.

There are several ways an object can force a redraw. These all take the form of messages, each of which is described below.

MSG_VIS_DRAW: This message causes the entire visible branch to draw itself. This message may be sent by any object to any other object, including itself. It does not, however, update the screen image; you must call MSG_VIS_VUP_UPDATE_WIN_GROUP .
MSG_VIS_BOUNDS_CHANGED: This message causes the visible object to mark the affected portions invalid, causing the visual update mechanism to redraw that portion during the next visual update. This message is part of the visible update mechanism.
MSG_VIS_REDRAW_ENTIRE_OBJECT: This message causes the visible object to redraw itself entirely (as opposed to just the invalid portion) if it is currently drawable. Essentially, the object will send itself a MSG_VIS_DRAW when it receives this message. This is especially useful if an object needs to completely change its image.
MSG_VIS_INVALIDATE: This message invalidates the entire region inside the visible object's bounds. It will cause the window system to generate a MSG_META_EXPOSED for the affected area, causing a MSG_VIS_DRAW to propagate down the tree to all affected objects. Note that this message must be subclassed to work with scaled windows or large documents.
MSG_VIS_INVAL_TREE: This message invalidates the entire region inside the visible object's bounds, including any child window areas. The window system will generate a MSG_META_EXPOSED for all affected windows.
MSG_VIS_MARK_INVALID: This message allows the caller to set an object's invalid flags so the object will be properly updated later. The object is marked as being invalid, and the default handler ensures a visual update path is created. This method may not be subclassed by applications.
MSG_VIS_ADD_RECT_TO_UPDATE_REGION: This message adds the passed rectangular region to a window's update list. Essentially, the window group associated with the recipient object will ensure that the given rectangle gets marked invalid and included in the next visual update.

MSG_VIS_DRAW

void	MSG_VIS_DRAW(
        DrawFlags		drawFlags,
        GStateHandle		gstate);

This message causes the visible object to draw itself. The default behavior of this message for composite objects is to pass the message on to all children. There is no default behavior for VisClass for this message.

Source: Unrestricted.

Destination: Any visible object.

Parameters: drawFlags A record of type DrawFlags (defined below). The flags in this record describe what type of action initiated the MSG_VIS_DRAW .

gstate: The GStateHandle of the gstate created for this visual update. All drawing done in the handler should be for this GState.

Return: Nothing.

Interception: All visible objects that wish to draw anything to the screen must intercept this message. Composites that intercept it must be sure to send it to their children (with @send @visChildren ).

Structures: The flags in the DrawFlags record are listed below:

DF_EXPOSED: This flag indicates the MSG_VIS_DRAW is a result of a MSG_META_EXPOSED from the window system. This is the standard and most usual form of MSG_VIS_DRAW .
DF_OBJECT_SPECIFIC: This flag is used by various Specific UI objects for object-specific things. Your visible objects should not be concerned with this flag.
DF_PRINT: This flag indicates that the MSG_VIS_DRAW is a result of a MSG_META_EXPOSED_FOR_PRINT , the printing message. The GState passed will be a spooler GState rather than a window GState. If this flag is set, DF_EXPOSED will also be set.
DF_DONT_DRAW_CHILDREN: This flag indicates that composite objects should draw themselves but should not propagate the drawing message on to their children (this is nonstandard behavior).
DF_DISPLAY_TYPE: This is actually an enumerated type indicating the display type being used by the system right now. The display type enumeration is named DisplayClass . For review, the types are listed below:
: DC_TEXT, DC_GRAY_1, DC_GRAY_2, DC_GRAY_4, DC_GRAY_8, DC_COLOR_2, DC_COLOR_4, DC_CF_RGB.

MSG_VIS_BOUNDS_CHANGED

void	MSG_VIS_BOUNDS_CHANGED(@stack
        word	bottom,
        word	right,
        word	top,
        word	left);

The geometry manager sends this message when a geometry update changes an object's bounds.

Source: Unrestricted--sent by the geometry manager when a visible object's bounds have changed as the result of a geometry change.

Destination: Any visible object.

Parameters: bottom , right , top , left The four parameters correspond to the rectangle defining the object's old bounds. The parameters are passed on the stack.

Return: Nothing.

Interception: Unlikely. If the object subclasses this message, it should invalidate any part of its old bounds that it might have drawn in (the default handler invalidates the entire passed range).

MSG_VIS_REDRAW_ENTIRE_OBJECT

void	MSG_VIS_REDRAW_ENTIRE_OBJECT();

This message causes the object send itself a MSG_VIS_DRAW , creating and destroying a GState for itself.

Source: Unrestricted--typically sent by an object to itself because of a state change, not as part of the visual update mechanism.

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

Interception: Unlikely.

MSG_VIS_INVALIDATE

void	MSG_VIS_INVALIDATE();

This message invalidates the entire region within the object's bounds. The message will cause the window system to generate a MSG_META_EXPOSED for the area covered by the bounds, causing a visual update to occur.

Source: Unrestricted.

Destination: Any visible object.

Interception: Must be intercepted if the object is working in a 32-bit document space. Must also be intercepted to work with scaled views.

MSG_VIS_INVAL_TREE

void	MSG_VIS_INVAL_TREE();

This message has the effect of MSG_VIS_INVALIDATE on an entire branch of the visible tree. The window system will generate MSG_META_EXPOSED for each affected window.

Source: Unrestricted.

Destination: Any visible object.

Interception: Unlikely.

MSG_VIS_MARK_INVALID

void	MSG_VIS_MARK_INVALID(
        VisOptFlags		flagsToSet,
        VisUpdateMode		updateMode);

This message allows the caller to set the recipient's VI_optFlags record so the object will get updated properly during the next visual update. The flags that can be set with this message are VOF_GEOMETRY_INVALID, VOF_WINDOW_INVALID, and VOF_IMAGE_INVALID. For more information on these flags, see VI_optFlags .

Source: Unrestricted.

Destination: Any visible object.

Parameters: flagsToSet A record of VisOptFlags indicating which type of invalidation is being caused. The flags allowed with this message are VOF_GEOMETRY_INVALID, VOF_WINDOW_INVALID, and VOF_IMAGE_INVALID.

updateMode: A VisUpdateMode indicating when the visual update caused by this message should occur.

Return: Nothing.

Interception: May not be subclassed. Certain optimizations are made in the default handler, and subclassing may have unpredictable results.

MSG_VIS_ADD_RECT_TO_UPDATE_REGION

void	MSG_VIS_ADD_RECT_TO_UPDATE_REGION(@stack
        byte		unused,		/* for word alignment of parameters */
        VisAddRectFlags		addRectFlags,
        word		bottom,
        word		right,
        word		top,
        word		left);

This message adds the passed rectangular region to the window group's list of regions that require visual update. The handler for this message will ensure that the window group object for this branch of the tree marks the region as invalid so it will be included in the next visual update. The addRectFlags parameter contains either of the flags listed below.

Source: Unrestricted--usually sent by an object to itself.

Destination: Any visible object--usually sent by an object to itself.

Parameters: unused An unused byte for alignment of parameters.

addRectFlags: A record of VisAddRectFlags , defined below.
rectangle coords: The coordinates of the rectangle to be added to the invalidation region.

Return: Nothing.

Interception: Unlikely--a composite object may wish to optimize invalidation by altering the passed bounds and then passing the message on to its superclass.

Structures: The VisAddRectFlags are listed below:

VARF_NOT_IF_ALREADY_INVALID: This flag indicates that the passed rectangle should not be invalidated if any visible object in the hierarchy going up to the window group object is marked invalid.
VARF_ONLY_REDRAW_MARGINS: This flag indicates that the object is invalidating old bounds and may indicate that the system can use a special optimization for invalidation.

Updating Window Groups

MSG_VIS_VUP_UPDATE_WIN_GROUP, MSG_VIS_UPDATE_WIN_GROUP, MSG_VIS_UPDATE_WINDOWS_AND_IMAGE

A window group is an object that has a window in which visible objects are displayed. Typically, you will not create your own window group objects, but you may need to notify a window group when it needs to be updated visually. To be a window group, an object has to have its VTF_IS_WINDOW or VTF_IS_PORTAL flag set in its VI_typeFlags field.

The window group is responsible for keeping track of the regions of its coordinate space that require visual updating. When a region or object gets invalidated, the window group remembers that it is invalid and makes sure it gets updated during the next visual update.

Any object can request that a visual update occur for the entire branch managed by a window group. It can use the three messages described in this section to request or force a visual update for the window group.

MSG_VIS_VUP_UPDATE_WIN_GROUP

Boolean	MSG_VIS_VUP_UPDATE_WIN_GROUP(
        VisUpdateMode updateMode);

This message travels up the visible tree from the recipient object to the first window group encountered; it will then cause that window group to go through a visible update by sending the window group object a MSG_VIS_UPDATE_WIN_GROUP , below.

Source: Unrestricted.

Destination: Any visible object residing in the window group that is to be updated.

Parameters: updateMode A VisUpdateMode indicating when the visual update should occur. VUM_MANUAL has the effect of a "no operation" because VUM_MANUAL does not cause visual updates.

Return: True if the update mechanism was invoked; false if it was not.

Interception: Not allowed.

Warnings: You may not subclass this message.

MSG_VIS_UPDATE_WIN_GROUP

void	MSG_VIS_UPDATE_WIN_GROUP(
        VisUpdateMode updateMode);

This message may only be sent by a window group object to itself. It causes the window group to actually go through a visual update.

Source: Visible update mechanism.

Destination: The window group object that is to be updated.

Parameters: updateMode A VisUpdateMode indicating when the visual update should occur. This is the same as passed to MSG_VIS_VUP_UPDATE_WIN_GROUP.

Return: Nothing.

Interception: Not allowed.

Warnings: You may not subclass this message.

MSG_VIS_UPDATE_WINDOWS_AND_IMAGE

void	MSG_VIS_UPDATE_WINDOWS_AND_IMAGE(
        VisUpdateImageFlags updateImageFlags);

This message is called by a window group during a visual update. It should not be sent or handled by anything other than a window group. It causes both the geometry and image of the affected branch of the visible tree to be updated, and it is used on branches which are already visually realized on the screen.

Source: Visual update mechanism.

Destination: A window group object.

Parameters: updateImageFlags This is a record of VisUpdateImageFlags that govern the visual update of the window group.

Return: Nothing.

Interception: Not allowed.

Structures: The flags of VisUpdateImageFlags are listed below:

VUIF_ALREADY_INVALIDATED: An optimization flag to keep an already-invalid composite from invalidating all its children.
VUIF_SEND_TO_ALL_CHILDREN: A flag to ensure that all children get invalidated; it is used when the composite only updates its margins for optimization.

Warnings: You may not subclass this message.

Using Visual Monikers

MSG_VIS_DRAW_MONIKER, MSG_VIS_GET_MONIKER_POS, MSG_VIS_GET_MONIKER_SIZE, MSG_VIS_FIND_MONIKER, MSG_VIS_CREATE_VIS_MONIKER

Although visual monikers are typically used with generic objects (and are, in fact, documented in the GenClass chapter), you can display monikers with visible objects as well. The four messages discussed in this section can be used to draw a visible moniker, get information about a moniker, or locate a particular moniker in the visible object tree.

MSG_VIS_DRAW_MONIKER

void	MSG_VIS_DRAW_MONIKER(@stack
        DrawMonikerFlags		monikerFlags,
        ChunkHandle		visMoniker,
        word		textHeight,
        GStateHandle		gstate,
        word		yMaximum,
        word		xMaximum,
        word		yInset,
        word		xInset);

This message draws a visual moniker for the object. This message may be called by an object on itself in its MSG_VIS_DRAW handler.

Source: Unrestricted.

Destination: Any visible object.

Parameters: monikerFlags A record of DrawMonikerFlags indicating how the moniker should be drawn. These flags are described below.

visMoniker: The chunk handle of the chunk containing the actual moniker to be drawn. This chunk must be in the same block as the object handling the message.
textHeight: A parameter used for optimization--if the caller knows the system text height, it should pass it here. If not, it should pass zero.
gstate: The handle of the GState to use when drawing the moniker. Typically, this is received by MSG_VIS_DRAW , which invokes this message.
yMaximum: The maximum bottom bound of the moniker if DMF_CLIP_TO_MAX_WIDTH is set in monikerFlags . Pass MAX_COORD to avoid clipping.
xMaximum: The maximum right bound of the moniker if DMF_CLIP_TO_MAX_WIDTH is set in monikerFlags . Pass MAX_COORD to avoid clipping.
yInset: The vertical inset at which to begin drawing the moniker, if left or right justified.
xInset: The horizontal inset at which to begin drawing the moniker, if top or bottom justified.

Return: Nothing.

Interception: Unlikely.

Structures: The DrawMonikerFlags structure is defined as follows:

typedef ByteFlags DrawMonikerFlags;
#define DMF_UNDERLINE_ACCELERATOR						0x40
		/* Underlines accelerator key, if any */
#define DMF_CLIP_TO_MAX_WIDTH						0x20
		/* Clips the moniker to the xMaximum
		 * parameter */
#define DMF_NONE						0x10
		/* Set to draw the moniker at the
		 * current pen position (ignore the
		 * xInset and yInset parameters) */
#define DMF_Y_JUST_MASK						0x0c
#define DMF_X_JUST_MASK						0x03
		/* These are two bitfields that
		 * determine the justification.
		 * Their offsets are below; they
		 * are of type Justification. */
#define DMF_Y_JUST_OFFSET					2
#define DMF_X_JUST_OFFSET					0

MSG_VIS_GET_MONIKER_POS

XYValueAsDWord MSG_VIS_GET_MONIKER_POS(@stack
        DrawMonikerFlags		monikerFlags,
        ChunkHandle		visMoniker,
        word		textHeight,
        GStateHandle		gstate,
        word		yMaximum,
        word		xMaximum,
        word		yInset,
        word		xInset);

This message returns the position at which the moniker would appear if it were drawn with MSG_VIS_DRAW_MONIKER . The moniker is not actually drawn by this message.

Source: Unrestricted.

Destination: Any visible object.

Parameters: See MSG_VIS_DRAW_MONIKER above.

Return: A dword value representing the horizontal and vertical positions where the moniker would be drawn if it were drawn with the passed parameters. The horizontal position is returned in the high word; the vertical position is returned in the low word. Use the DWORD_X and DWORD_Y macros to extract the x and y values. These macros can be found in the file graphics.h .

Interception: Unlikely.

MSG_VIS_GET_MONIKER_SIZE

SizeAsDWord MSG_VIS_GET_MONIKER_SIZE(@stack
        DrawMonikerFlags		monikerFlags,
        ChunkHandle		visMoniker,
        word		textHeight,
        GStateHandle		gstate,
        word		yMaximum,
        word		xMaximum,
        word		yInset,
        word		xInset);

This message returns the size of the moniker specified by the parameters. The moniker is not drawn.

Source: Unrestricted.

Destination: Any visible object.

Parameters: See MSG_VIS_DRAW_MONIKER above.

Return: A dword value representing the size of the moniker. The width of the moniker is returned in the high word; the height is returned in the low word. Use the macros DWORD_WIDTH and DWORD_HEIGHT, which can be found in the file visC.goh and also on DWORD_HEIGHT .

Interception: Unlikely.

MSG_VIS_FIND_MONIKER

optr	MSG_VIS_FIND_MONIKER(@stack
        VisMonikerSearchFlags			searchFlags,
        MemHandle			destBlock,
        ChunkHandle			monikerList,
        DisplayType			displayType);

This message locates the given visual moniker list and returns the optr of the moniker most appropriate for the passed display scheme.

Source: Unrestricted.

Destination: Any visible object.

Parameters: searchFlags A record of VisMonikerSearchFlags (described below) indicating the attributes of the moniker that should be returned.

destBlock: Handle of the block into which the moniker chunk should be copied.
monikerList: Chunk handle of the chunk containing the moniker list to search. The moniker list must be in the same object block as the object handling the message.
displayType: The DisplayType of the moniker to be found (see below).

Interception: Unlikely.

Structures: The VisMonikerSearchFlags are listed below.

 typedef WordFlags VisMonikerSearchFlags;
#define VMSF_STYLE					0xf000
	/* Four bits defining the preferred style of
	 * the moniker. These bits are of type
	 * VMStyle, which is defined below. */

#define VMSF_COPY_CHUNK					0x0400
	/* Set if the moniker should be copied into
	 * the block specified if not already in
	 * that block. */
#define VMSF_REPLACE_LIST					0x0200
	/* Set if the moniker list chunk containing
	 * the VisMoniker should be replaced. The
	 * chunk handle of the list will then point
	 * to the moniker rather than the list. */
#define VMSF_GSTRING					0x0100
	/* Set if a GString moniker is expected,
	 * clear if a text moniker is expected. */

	/* The remaining bits of this record are
	 * reserved for internal use. */

#define VMSF_STYLE_OFFSET 12

typedef ByteEnum  VMStyle;
#define VMS_TEXT					0
			/* Normal text moniker */
#define VMS_ABBREV_TEXT					1
			/* short text abbreviation */
#define VMS_GRAPHIC_TEXT					2
			/* textual GString */
#define VMS_ICON					3
			/* normal GString moniker */
#define VMS_TOOL					4
			/* tool moniker, normally smaller
			 * than a standard moniker */

The DisplayType flags are listed below and can be found in win.h:

typedef ByteFlags  DisplayType;
#define DT_DISP_SIZE						0xc0
		/*   Two bits indicating the size of the
		 * display; a DisplaySize value, one of
		 * DS_TINY (CGA, or 256 x 320),
		 * DS_STANDARD (EGA, VGA, HGC, MCGA),
		 * DS_LARGE (800 x 600 SVGA), or
		 * DS_HUGE (huge screens). */
#define DT_DISP_ASPECT_RATIO						0x30
		/* Two bits indicating the aspect
		 * ratio of the screen; a value of
		 * DisplayAspectRatio, one of
		 * DAR_NORMAL (VGA or MCGA),
		 * DAR_SQUISHED (EGA or HGC), or
		 * DAR_VERY_SQUISHED (CGA) */
#define DT_DISP_CLASS						0x0f
		/* Four bits indicating the class of
		 * the display driver (or closest
		 * match); A DisplayClass value, one of
		 * DC_TEXT (char only, not implemented),
		 * DC_GRAY_1 (1 bit/pixel gray scale),
		 * DC_GRAY_2 (2 bit/pixel gray scale),
		 * DC_GRAY_4 (4 bit/pixel gray scale),
		 * DC_GRAY_8 (8 bit/pixel gray scale),
		 * DC_COLOR_2 (2 bit/pixel color index),
		 * DC_COLOR_4 (4 bit/pixel color index),
		 * DC_COLOR_8 (8 bit/pixel color index),
		 * DC_CF_RGB (color with RGB values) */

MSG_VIS_CREATE_VIS_MONIKER

ChunkHandle MSG_VIS_CREATE_VIS_MONIKER(@stack
        CreateVisMonikerFlags			flags,
        word			height,
        word			width
        word			length,
        VisMonikerDataType			dataType,
        VisMonikerSourceType			sourceType,
        dword			source);

This message creates a new chunk for a visual moniker within the recipient's object block. The new moniker can be created from an already existing visual moniker, a visual moniker list, a text string, a GString, or a token from the token database. The source may be defined by a far pointer, a global memory handle, or an optr. If the source is a text string or GString, a visual moniker structure will be created for the string. The newly-created chunk is marked dirty if the CVMF_DIRTY flag is passed.

If a moniker list is passed, the entire list will be copied into the destination object block. You must make sure that all the monikers in the list will still exist when the list is used.

Source: Unrestricted.

Destination: Any visible object.

Parameters: flags A record of CreateVisMonikerFlags . Currently only one may be passed: CVMF_DIRTY, which indicates that the chunk should be marked dirty.

height: The height of the moniker.
width: The width of the moniker.
length: The length of the moniker, if a text string.
dataType: The type of moniker, an enumeration of the type VisMonikerDataType . This parameter determines the type of moniker to be created.
sourceType: The type of source used to create the new moniker, an enumeration of VisMonikerSourceType .
source: This parameter can be a pointer to the source, the global handle of the block containing the source, or an optr pointing to the chunk containing the source, depending on the value in sourceType .

Return: The chunk handle of the new visual moniker. The visual moniker chunk resides in the object block of the object receiving the message. If the flag CVMF_DIRTY is passed, the chunk will be marked dirty.

Interception: Unlikely--custom UI gadgets may intercept in some cases.

Structures: VisMonikerSourceType and VisMonikerDataType are defined below. Both can be found in visC.goh .

typedef ByteEnum  VisMonikerSourceType;
#define VMST_FPTR					0
		/* Source is referenced by a pointer.
		 * CVMF_source is a far pointer. */
#define VMST_OPTR					1
		/* Source is referenced by an optr.
		 * CVMF_source is an optr. */
#define VMST_HPTR					2
		/* Source is referenced by a combination
		 * memory handle and offset into the
		 * memory block (as opposed to an optr
		 * in which the low word is actually a
		 * chunk handle, not an offset). */

typedef ByteEnum  VisMonikerDataType;
#define VMDT_NULL					0
		/* There is no source. Not valid for
		 * MSG_VIS_CREATE_VIS_MONIKER. */
#define VMDT_VIS_MONIKER					1
		/* Source is a complete VisMoniker
		 * structure. CVMF_length indicates the
		 * size of a complete VisMoniker
		 * structure; CVMF_width and
		 * CVMF_height are unused. */
#define VMDT_TEXT					2
		/* Source is a text string. If the
		 * string is null-terminated,
		 * CVMF_length should be zero.
		 * Otherwise, CVMF_length is the length
		 * of the string; A VisMoniker
		 * structure will be created for the
		 * string. CVMF_width and CVMF_height
		 * are unused. */
#define VMDT_GSTRING					3
		/* Source is a GString. If CVMF_length
		 * is zero, the GString length is
		 * determined by scanning for
		 * GR_END_STRING. Otherwise, CVMF_length
		 * indicates the length of the GString.
		 * CVMF_width and CVMF_height indicate
		 * the width and height of the GString.
		 * If either is zero, the dimension will
		 * be calculated by examining the
		 * string. A VisMoniker structure will
		 * be created for the GString. */
#define VMDT_TOKEN					4
		/* Source is a GeodeToken. CVMF_length,
		 * CVMF_width, and CVMF_height are
		 * unused. The destination must be able
		 * to use this data type because the
		 * specific UI must decide which moniker
		 * to choose from the token in the token
		 * database. */

DWORD_HEIGHT

word	 DWORD_HEIGHT(val);
        dword	val;

This macro extracts the height from a SizeAsDWord structure (dword).

DWORD_WIDTH

word	 DWORD_WIDTH(val);
        dword	val;

This macro extracts the width from a SizeAsDWord structure (dword).

MAKE_SIZE_DWORD

SizeAsDWord  MAKE_SIZE_DWORD(width, height);
        word	width, height;

This macro takes a width and height and creates a SizeAsDWord value.

Cached GStates

MSG_VIS_CREATE_CACHED_GSTATES, MSG_VIS_RECREATE_CACHED_GSTATES, MSG_VIS_DESTROY_CACHED_GSTATES

Many complex visible objects (such as VisText and VisSpline) have both a cached GState and a reference count. When the reference count goes from zero to one, the Vis object creates and caches a GState; when the reference count goes from one to zero, the cached GState is destroyed. VisClass has three messages to create, update, and destroy the cached GStates. None of these messages has any default behavior; they are provided for complex objects to handle should they need them.

MSG_VIS_CREATE_CACHED_GSTATES

void	MSG_VIS_CREATE_CACHED_GSTATES();

This message may be used to create and cache a GState, typically to avoid having a complex Vis object update several times for several simple operations (such as pointer events).

Source: Unrestricted.

Destination: Any visible object.

Interception: Must be intercepted to have any effect; there is no default behavior.

MSG_VIS_RECREATE_CACHED_GSTATES

void	MSG_VIS_RECREATE_CACHED_GSTATES();

This message may be used to have the Vis object destroy and recreate any cached GStates it has. For example, cached GStates of a complex visible object that gets moved or resized will no longer map to the proper place in the object's document. After the move or resize, this message may be used to update those GStates.

Source: Unrestricted.

Destination: Any visible object.

Interception: Must be intercepted to have any effect; there is no default behavior.

MSG_VIS_DESTROY_CACHED_GSTATES

void	MSG_VIS_DESTROY_CACHED_GSTATES();

This message may be used to destroy any cached GStates the visible object may have.

Source: Unrestricted.

Destination: Any visible object.

Interception: Must be intercepted to have any effect; there is no default behavior.

GEOS SDK TechDocs |

4.1 Basic VisClass Rules | Next:

4.3 Positioning Visible Objects