ANNNAMEOPTIONS

typedef struct tagANNNAMEOPTIONS
{
   L_UINT uStructSize;
   L_UINT uFlags;
   L_BOOL bShowName;
   L_TCHAR *pszName;
   L_SIZE_T uNameLen;
   ANNPOINT ptNameOffset;
   L_BOOL bNameRestrict;
   COLORREF crNameFore;
   COLORREF crNameBack;
   ANNFONT NameFont;
   L_BOOL bNameBackTransparent;
   L_INT32 nReserved;
} ANNNAMEOPTIONS, *pANNNAMEOPTIONS;

The ANNNAMEOPTIONS structure is used with the functions LAnnotation::SetNameOptions and LAnnotation::GetNameOptions to get or set the name options on any annotation object.

Member	Description
uStructSize	Size of this structure. Use sizeof(ANNNAMEOPTIONS)
uFlags	Identifies which fields are valid. Possible values are one or more of the following constants "or"ed together. Possible values are:
	Value	Meaning
	ANNNAME_SHOW_NAME	[0x0001] bShowName field is valid.
	ANNNAME_NAME	[0x0002] pszName field is valid.
	ANNNAME_NAME_LENGTH	[0x0004] uNameLen is valid.
	ANNNAME_OFFSET	[0x0008] ptNameOffset is valid.
	ANNNAME_RESTRICT	[0x0010] bNameRestrict is valid.
	ANNNAME_FORECOLOR	[0x0020] crNameFore is valid.
	ANNNAME_BACKCOLOR	[0x0040] crNameBack is valid.
	ANNNAME_BACK_TRANSPARENT	[0x0080] bNameBackTransparent is valid.
	ANNNAME_FONT_BOLD	[0x0100] NameFont.bFontBold is valid.
	ANNNAME_FONT_ITALIC	[0x0200] NameFont.bFontItalic is valid.
	ANNNAME_FONT_STRIKEOUT	[0x0400] NameFont.bFontStrikeOut is valid.
	ANNNAME_FONT_UNDERLINE	[0x0800] NameFont.bFontUnderline is valid.
	ANNNAME_FONT_NAME	[0x1000] NameFont.szFontName is valid.
	ANNNAME_FONT_SIZE	[0x2000] NameFont.dFontSize is valid.
	ANNNAME_FONT_INFO	(ANNNAME_FONT_BOLD \| .// The entire NameFont field is valid
		ANNNAME_FONT_ITALIC \|
		ANNNAME_FONT_STRIKEOUT \|
		ANNNAME_FONT_UNDERLINE \|
		ANNNAME_FONT_SIZE \|
		ANNNAME_FONT_NAME)
	ANNNAME_ALL	(ANNNAME_SHOW_NAME \| All fields are valid
		ANNNAME_NAME \|
		ANNNAME_NAME_LENGTH \|
		ANNNAME_OFFSET \|
		ANNNAME_RESTRICT \|
		ANNNAME_FORECOLOR \|
		ANNNAME_BACKCOLOR \|
		ANNNAME_BACK_TRANSPARENT \|
		ANNNAME_FONT_INFO)
bShowName	Flag that indicates whether to show or hide the annotation object name. Possible values are:
	Value	Meaning
	TRUE	Show the annotation object name
	FALSE	Hide the annotation object name
pszName	Null terminated character string containing the name
uNameLen	Length of string, including the NULL terminator
ptNameOffset	Offset of name. The name offset is the x and y offset (in pixels viewed at 100%) relative to the upper left corner of the bounding box of the annotation object.
bNameRestrict	Flag that indicates whether the annotation object name is restricted to appear fully within the bitmap. Possible values are:
	Value	Meaning
	TRUE	Restrict the annotation name to within the bitmap. (Annotation container).
	FALSE	Allow the annotation name to be moved outside the container.
crNameFore	Foreground color of the name text
crNameBack	Background color of the name text
NameFont	Font used to display the name text. For more information, refer to the documentation for ANNFONT.
bNameBackTransparent	Flag that indicates whether the background text color is transparent. Possible values are:
	Value	Meaning
	TRUE	Background text color is transparent.
	FALSE	Use crNameBack for the background color of the text.
nReserved	Reserved for future use. Use zero.

Comments

When calling LAnnotation::GetNameOptions, the uFlags field identifies which fields to retrieve. When calling LAnnotation::SetNameOptions, the uFlags field identifies which fields to set.

When you create an object in the automation mode, the values for bShowName, ptNameOffset, and bNameRestrict are taken from the automation object. The name of the object is also taken from the automation object, specifically from the ANNAUTOTEXT_ITEM_DEFAULTNAME item. This is just like the annotation text, which is by default "AaBbYyZz" and is taken from ANNAUTOTEXT_ITEM_DEFAULTTEXT item.

The default name is "", which means that the objects will not show a name when you create them. To set a default name, call LAnnAutomation::SetAutoText with uItem set to ANNAUTOTEXT_ITEM_DEFAULTNAME, and pText set to your desired default string. For example:

LAnnAutomation::SetAutoText(hAutomation, ANNAUTOTEXT_ITEM_DEFAULTNAME, "Default_name");

The name offset of an annotation object (value pointed to by pNameOffset) is an offset that is relative to the upper left corner of the bounding box of the annotation. The name offset values (pNameOffset.x, pNameOffset.y) are in pixels, where the image is viewed at 100%. The name offset can be changed in any of the following ways:

1.	Programmatically using LAnnotation::SetNameOptions.
2.	Right-clicking the object in design-mode, selecting Name Properties, setting the NameOffset using the text box, and clicking Apply.
3.	Clicking on the object name in design-mode and dragging it to a new location.

The name of an annotation object may be restricted so that it fully appears on the bitmap. For example, if the variable pointed to by pbNameRestrict is TRUE for an object, the name offset cannot be set so that the object name is outside the bitmap (annotation container). Suppose you have a 200x200 bitmap with a 100x100 button in the lower right corner. The name of the button is "BUTTON". Attempting to set the name offset to anything larger than (43,100) by any of the above methods will result in the name offset being set to (43,100). Also, dragging the annotation object itself in such a way that would cause the object name to be moved outside the bitmap will cause the name offset to change.

When retrieving the name text, you must first call LAnnotation::GetNameOptions to determine the length of the character string. Then, you must allocate a character string of this length, and call LAnnotation::GetNameOptions again.

The sample illustrates this.

Example

For an example, refer to LAnnotation::SetNameOptions.