GenClass: 4.2 Modifying GenClass Instance Data: Managing Visual Monikers

MSG_GEN_GET_VIS_MONIKER, MSG_GEN_USE_VIS_MONIKER, MSG_GEN_CREATE_VIS_MONIKER, MSG_GEN_REPLACE_VIS_MONIKER, MSG_GEN_REPLACE_VIS_MONIKER_OPTR, MSG_GEN_REPLACE_VIS_MONIKER_TEXT, MSG_GEN_FIND_MONIKER, MSG_GEN_DRAW_MONIKER, MSG_GEN_GET_MONIKER_POS, MSG_GEN_GET_MONIKER_SIZE, MSG_GEN_RELOC_MONIKER_LIST, MSG_GEN_FIND_OBJECT_WITH_TEXT_MONIKER

SendingMSG_GEN_GET_VIS_MONIKER to an object returns the chunk handle of the visual moniker (GI_visMoniker ) for that object. You can then inspect that visual moniker or use it within other objects (though this is not recommended). You must be careful when sharing monikers with other objects, as freeing one object (and therefore its associated moniker) will interfere with any other objects referencing that moniker.

SendingMSG_GEN_USE_VIS_MONIKER to an object sets a visual moniker for that object to use. The message must pass the chunk handle of the moniker desired for the object along with a VisUpdateMode . Valid VisUpdateMode s are described in the VisClass chapter. The moniker to use must reside in the same block as the object being set. If you need to set an object to use a new moniker from a location outside of its object block, use MSG_GEN_REPLACE_VIS_MONIKER to copy the moniker to the new location.

MSG_GEN_REPLACE_VIS_MONIKER copies a visual moniker from a source location into a destination. This message must pass parameters specifying the type of copy operation. The source for the moniker can be referenced using an optr or a simple text string. Use this message when you wish to copy a moniker from outside of the object's current object block.

MSG_GEN_REPLACE_VIS_MONIKER_OPTR and MSG_GEN_REPLACE_VIS_MONIKER_TEXT are simplified versions of the above message, allowing you to set a visual moniker from an optr or from a pointer to a null-terminated text string without having to pass many other arguments.

MSG_GEN_CREATE_VIS_MONIKER creates a visual moniker (within the resource block of the object this message is sent to), copying it from a source; it does not, however, attach this moniker to any object.

MSG_GEN_FIND_MONIKER searches for a specific type of moniker within a moniker list. You may then use the moniker directly. You can also replace the original moniker list with the specified moniker.

MSG_GEN_DRAW_MONIKER, MSG_GEN_GET_MONIKER_POS , and MSG_GEN_GET_MONIKER_SIZE all manipulate a currently existing moniker. These messages are most useful for custom gadgets. MSG_GEN_DRAW_MONIKER draws the moniker according to the criteria passed with the message. MSG_GEN_GET_MONIKER_POS and MSG_GEN_GET_MONIKER_SIZE return GEOS coordinates specifying the location and size of the moniker, respectively. You may then inspect and alter these coordinates before sending the moniker a MSG_GEN_DRAW_MONIKER to redraw the moniker according to the changed criteria.

The utility message MSG_GEN_RELOC_MONIKER_LIST relocates an object's moniker list.

To find an object with a particular visual moniker, send MSG_GEN_FIND_OBJECT_WITH_MONIKER_FLAGS to the object at which to start the top-down search, passing the text to perform the match.

MSG_GEN_GET_VIS_MONIKER

ChunkHandle	 MSG_GEN_GET_VIS_MONIKER();

This message retrieves the instance data in the object's current GI_visMoniker instance field. This message returns the ChunkHandle of the moniker data structure. You can then use that chunk handle to manipulate the visual moniker directly or to copy the moniker for use by other objects.

Source: Unrestricted.

Destination: Any generic object.

Return: The chunk handle of the visual moniker in use by this object.

Interception: Generally not intercepted.

MSG_GEN_USE_VIS_MONIKER

void	MSG_GEN_USE_VIS_MONIKER(
        ChunkHandle moniker,
        VisUpdateMode updateMode);

This message allows an object to reference a visual moniker; this message does not destroy the chunk of the object's current visual moniker. The moniker must reside in the same block as the object. Use MSG_GEN_REPLACE_VIS_MONIKER if you wish to set a moniker from a source outside the object block or if you wish to use a new moniker, overwriting the old one.

You cannot pass a moniker list's chunk handle using this message. See MSG_GEN_FIND_MONIKER for information on selecting monikers from within a list.

Source: Unrestricted.

Destination: Any generic object.

Parameters: moniker The chunk handle of the visual moniker to use

updateMode: VisUpdateMode to determine when the moniker will be redrawn.

Return: Nothing.

Interception: Generally not intercepted.

Code Display 2-18 Getting and Using Visual Monikers

/* This method effectively copies a visual moniker from ObjectOne into ObjectTwo.
 * Both objects must reside in the same object block. Note that in effect, both
 * ObjectOne and ObjectTwo will "share" the same moniker. This can be dangerous if
 * one object is freed, thereby causing the other object to become dereferenced.
 * For more complex copy operations, use MSG_GEN_REPLACE_VIS_MONIKER instead. */

@method MyProcessClass, MSG_MY_MONIKER_MESSAGE {
	/* Set up variable to store the chunk handle of the visual moniker. */
    ChunkHandle MyVisMonikerCH;

	/* Retrieve the visMoniker of ObjectOne and store it in the variable. */

    MyVisMonikerCH = @call @ObjectOne::MSG_GEN_GET_VIS_MONIKER();

	/* Set the visMoniker of Object Two to MyVisMonikerCH and update
	 * immediately. Use @send if you don't expect a return value. */

    @send @ObjectTwo::MSG_GEN_USE_VIS_MONIKER(MyVisMonikerCH, VUM_NOW);
}

/* You can also declare visual monikers in your .goc file and set them later */

    @visMoniker OnMoniker = "On";
    @visMoniker OffMoniker = "Off";

	/* Within a method, the following routine will set the moniker to "On". The
	 * OptrToChunk operator casts the object from an optr to a ChunkHandle. */

    @call @MyObject::MSG_GEN_SET_MONIKER(OptrToChunk(@OnMoniker), VUM_NOW);

	/* Within a method, the following routine will set the moniker to "Off" */

    @call @MyObject::MSG_GEN_SET_MONIKER(OptrToChunk(@OffMoniker), VUM_NOW);

MSG_GEN_REPLACE_VIS_MONIKER

ChunkHandle	 MSG_GEN_REPLACE_VIS_MONIKER(@stack
        VisUpdateMode			updateMode,
        word			height,
        word			width,
        word			length,
        VisMonikerDataType			dataType,
        VisMonikerSourceType			sourceType,
        dword			source);

This message copies a visual moniker from a source to the object sent the message. The message returns the chunk handle of the newly copied moniker. The object's current visual moniker is overwritten by this message; therefore, if more than one object shares the overwritten block, the other object should be updated with MSG_GEN_USE_VIS_MONIKER . This message can copy a visual moniker from a variety of sources.

This message is a general, all-purpose, moniker replacement device. If your visual moniker source is a visMoniker structure or a null-terminated text string, you may be able to use the simpler messages MSG_GEN_REPLACE_VIS_MONIKER_OPTR and MSG_GEN_REPLACE_VIS_MONIKER_TEXT .

Source: Unrestricted.

Destination: Any generic object.

Parameters: updateMode Specifies the VisUpdateMode to use when visually updating the changes to the screen. See the VisClass Chapter for more information on VisUpdateMode types.

height: If moniker is a GString, this specifies the height of the moniker in points. Otherwise, set this to zero.
width: If the moniker is a GString, this specifies the width of the moniker in points. Otherwise, set this to zero.
length: If the moniker is a GString, this specifies the size of the moniker in bytes. If the moniker is text and this argument is zero, the string is assumed to be null-terminated.
dataType: Specifies the type of data referenced by the source . Valid VisMonikerDataType types include VMDT_VIS_MONIKER, VMDT_TEXT, VMDT_GSTRING, or VMDT_TOKEN.
sourceType: Specifies the type of pointer referencing the source . Valid VisMonikerSourceType types are VMST_FPTR, VMST_OPTR, and VMST_HPTR.
source: Specifies the source of the moniker to be used during the copy process. This source may be a pointer to a text string, an optr pointing to a visual moniker outside the current block, or a variety of other sources. The source type should be specified in sourceType .

Return: The chunk handle of the new visual moniker for the object.

Interception: Generally not intercepted.

MSG_GEN_REPLACE_VIS_MONIKER_OPTR

ChunkHandle	 MSG_GEN_REPLACE_VIS_MONIKER_OPTR(
        optr		source,
        VisUpdateMode		updateMode);

This message is a simplified version of MSG_GEN_REPLACE_VIS_MONIKER. If your visual moniker source is an existing visMoniker structure, you can use this message to replace an object's moniker.

Source: Unrestricted.

Destination: Any generic object.

Parameters: source The optr of the visMoniker structure to use in the replacement operation.

updateMode: Specifies the VisUpdateMode to use when visually updating the changes to the screen.

Return: The chunk handle of the new visual moniker for the object.

Interception: Generally not intercepted.

MSG_GEN_REPLACE_VIS_MONIKER_TEXT

ChunkHandle	 MSG_GEN_REPLACE_VIS_MONIKER_TEXT(
        const char		*source,
        VisUpdateMode		updateMode);

This message is a simplified version of MSG_GEN_REPLACE_VIS_MONIKER. If your visual moniker source is a pointer to a null-terminated text string, you can use this message to replace an object's moniker without having to pass the arguments of MSG_GEN_REPLACE_VIS_MONIKER .

Source: Unrestricted.

Destination: Any generic object.

Parameters: source A pointer to a null-terminated character string to use in the replacement operation.

updateMode: Specifies the VisUpdateMode to use when visually updating the changes to the screen.

Return: The chunk handle of the new visual moniker for the object.

Interception: Generally not intercepted.

MSG_GEN_CREATE_VIS_MONIKER

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

This message creates a visual moniker chunk within the resource block of the object sent this message. The moniker is copied from the source specified but is not attached to any object in the new object block.

Source: Unrestricted

Destination: Any GenClass object

Parameters: flags Flags to use in the creation of the new visual moniker. CVMF_DIRTY marks the new moniker chunk OCF_DIRTY .

height: If moniker is a GString, this specifies the height of the moniker in points. Otherwise, set this to zero.
width: If the moniker is a GString, this specifies the width of the moniker in points. Otherwise, set this to zero.
length: If the moniker is a GString, this specifies the length of the moniker in points. Otherwise, set this to zero.
dataType: Specifies the type of data referenced by the source . Valid VisMonikerDataType types include VMDT_VIS_MONIKER, VMDT_TEXT, VMDT_GSTRING, or VMDT_TOKEN.
sourceType: Specifies the type of pointer referencing the source . Valid VisMonikerSourceType types are VMST_FPTR, VMST_OPTR, and VMST_HPTR.
source: Specifies the source of the moniker to be used during the copy process. This source may be a pointer to a text string, an optr pointing to a visual moniker outside the current block, or a variety of other sources. The source type should be specified in sourceType .

Return: The chunk handle of the new visual moniker for the object.

Interception: Generally not intercepted.

MSG_GEN_FIND_MONIKER

optr	MSG_GEN_FIND_MONIKER(
        Boolean		useAppMonikerList,
        word		searchFlags,					/* VisMonikerSearchFlags */
        MemHandle		destBlock);

This message scans a list of monikers and selects a specific moniker (or the most appropriate moniker). The moniker selected is determined according to the passed VisMonikerSearchFlags . This message is usually used by the specific UI to select an application moniker from a list.

If the first argument (useAppMonikerList ) is not zero, the message will use the GenApplication's moniker list instead of the recipient's. This is useful for finding the icon used for an iconified application.

Note that this message returns an optr, not a chunk handle, as this message is most often used to find a moniker outside of the current object block. This message returns zero if no moniker is found.

Source: Unrestricted.

Destination: Any generic object.

Parameters: useAppMonikerList
Non-zero to use the moniker list of the application associated with this object.

searchFlags: VisMonikerSearchFlags to use for the search criteria. If VMSF_COPY_CHUNK is specified in the searchFlags , a block handle must be supplied in destBlock . The selected moniker will be copied into that block.
destBlock: Block to copy a moniker into, if VMSF_COPY_CHUNK is specified in the searchFlags .

Return: The optr of the moniker found according to the search criteria. (This may be outside the current object block.)

Interception: Generally not intercepted.

MSG_GEN_DRAW_MONIKER

void	MSG_GEN_DRAW_MONIKER(@stack
        DrawMonikerFlags		monikerFlags,
        word		textHeight,
        GStateHandle		gState,
        word		yMaximum,
        word		xMaximum,
        word		yInset,
        word		xInset);

This message draws a moniker for an object according to the parameters passed. The moniker must currently exist. You can use this message to change the way you wish a visual moniker to appear within a generic object without actually changing the visual moniker itself.

Source: Unrestricted.

Destination: Any GS_USABLE generic object.

Parameters: monikerFlags Specifies the DrawMonikerFlags to use when drawing the moniker. The DrawMonikerFlags record specifies the conditions to draw the moniker under.

textHeight: Specifies the height of the system text. Passing this value speeds the processing of this message. If you do not know the height of the system text, pass zero.
gState: Specifies the GState, if any, to use when drawing the moniker.
yMaximum, xMaximum: These specify the maximum height and width of the moniker. Typically, these are used with DMF_CLIP_TO_MAX_WIDTH (in DrawMonikerFlags ) to perform a clipping operation on the moniker. Pass zero if no maximum width is desired.
yInset: Specifies the point to begin drawing the moniker if the moniker is right or left justified.
xInset: Specifies the point to begin drawing the moniker if the moniker is top or bottom justified.

Return: Nothing

Interception: Generally not intercepted. Custom gadgets may handle this if they are supplementing or replacing default functionality.

Structures: The DrawMonikerFlags record defines the parameters to use when drawing a currently existing visual moniker. This record is used by MSG_GEN_DRAW_MONIKER , MSG_GEN_GET_MONIKER_POS and MSG_GEN_GET_MONIKER_SIZE . Its flags are shown below:

DMF_UNDERLINE_ACCELERATOR
DMF_CLIP_TO_MAX_WIDTH
DMF_NONE
DMF_Y_JUST_MASK    /* of type Justifications */
DMF_X_JUST_MASK    /* of type Justifications */

Use DMF_UNDERLINE_ACCELERATOR to underline the keyboard accelerator of a text moniker. Use DMF_CLIP_TO_MAX_WIDTH to clip the visual bounds of the moniker to the width specified in maxWidth . Use DMF_NONE to draw the moniker at the current pen position.

The two justification masks are of type Justification , and they specify the vertical and horizontal justifications to use when drawing the moniker. The values you can use in the justification fields are

J_LEFT
J_RIGHT
J_CENTER
J_FULL

MSG_GEN_GET_MONIKER_POS

XYValueASDWord MSG_GEN_GET_MONIKER_POS(@stack
        DrawMonikerFlags		monikerFlags,
        word		textHeight,
        GStateHandle		gState,
        word		yMaximum,
        word		xMaximum,
        word		yInset,
        word		xInset);

This message returns the x and y coordinates of the moniker for the object as if the moniker were drawn according to the passed parameters (the same as for MSG_GEN_DRAW_MONIKER ). Use the macros DWORD_X and DWORD_Y to extract the appropriate coordinates from the returned value.

This message, along with MSG_GEN_DRAW_MONIKER and MSG_GEN_GET_MONIKER_SIZE is most useful in the construction and modification of custom gadgets.

Source: Unrestricted.

Destination: Any generic object.

Parameters: See MSG_GEN_DRAW_MONIKER .

Return: XYValueAsDWord which can be split up into x and y coordinates of the moniker position with the macros DWORD_X and DWORD_Y.

Interception: Generally not intercepted.

MSG_GEN_GET_MONIKER_SIZE

SizeAsDWord MSG_GEN_GET_MONIKER_SIZE(
        word		textHeight,
        GStateHandle		gState);

This message returns the width and height (in points) of the moniker for the object. Use the macros DWORD_WIDTH and DWORD_HEIGHT to extract the appropriate coordinates from the returned value. This message, along with MSG_GEN_DRAW_MONIKER and MSG_GEN_GET_MONIKER_POS , is most useful in the construction and modification of custom gadgets.

Source: Unrestricted.

Destination: Any generic object.

Parameters: textHeight The system text height, if known; otherwise, pass zero.

gstate: The GState handle of the GState to draw to.

Return: SizeAsDWord which can be split up into with and height with the macros DWORD_WIDTH and DWORD_HEIGHT.

Interception: Generally not intercepted.

MSG_GEN_RELOC_MONIKER_LIST

void 	MSG_GEN_RELOC_MONIKER_LIST(
        optr		monikerList,
        word 		relocFlag); /* 0: relocate; 1: unrelocate */

This method (un)relocates a passed moniker list.

Source: Anyone.

Destination: Any GenClass object.

Parameters: monikerList optr of moniker list.

reloc: Flag specifying whether relocation or unrelocation is desired.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_FIND_OBJECT_WITH_TEXT_MONIKER

optr	MSG_GEN_FIND_OBJECT_WITH_TEXT_MONIKER(
        char	*text,
        word	flags);

This message recursively searches through the generic tree (starting at the object sent the message) for an object whose visual moniker matches the passed text. This match does not need to be complete (unless the flag GFTMF_EXACT_MATCH is passed); the message will return the first object whose initial characters match the given text. The message must pass GenFindObjectWithMonikerFlags .

typedef WordFlags GenFindObjectWithMonikerFlags;
#define GFTMF_EXACT_MATCH 0x8000
#define GFTMF_SKIP_THIS_NODE 0x4000

If GFTMF_EXACT_MATCH is passed, the text and the visual moniker text must match exactly (null-terminated). If GFTMF_SKIP_THIS_NODE is passed, the object which sent the message will not be checked; only its children will be checked.

Source: Unrestricted.

Destination: Any generic object.

Parameters: text Null-terminated text.

flags: GenFindObjectWithMonikerFlags .

Return: optr of the object with the matching moniker, or null if no moniker was found.

Interception: Generally not intercepted.

GEOS SDK TechDocs |

4.1 Visual Monikers | Next:

4.3 Managing Keyboard Accelerators