ANNSNAPTOGRIDOPTIONS

Show in webframe

typedef struct tagANNSNAPTOGRIDOPTIONS
{
   L_UINT uStructSize;
   L_UINT uFlags;
   COLORREF crGridColor;
   L_UINT uGridLength;
   L_UINT uLineSpacing;
   L_UINT uLineStyle;
   L_BOOL bEnableSnap;
   L_BOOL bShowGrid;
   L_BOOL bAutoChangeGridLength;
   L_INT32 nReserved;
} ANNSNAPTOGRIDOPTIONS, *pANNSNAPTOGRIDOPTIONS;

The ANNSNAPTOGRIDOPTIONS structure is used to get and set the snap-to-grid options for the L_AnnSetSnapToGrid and L_AnnGetSnapToGrid functions.

Member	Description
uStructSize	Size of this structure in bytes, for versioning. Use the sizeof() macro to calculate this value.
uFlags	Identifies which fields are valid. Possible values are one or more of the following constants "or"ed together. Possible values are:
	Value	Meaning
	ANNSNAPTOGRID_GRID_COLOR	[0x0001] crGridColor field is valid.
	ANNSNAPTOGRID_GRID_LENGTH	[0x0002] uGridLength field is valid.
	ANNSNAPTOGRID_LINE_SPACING	[0x0004] uLineSpacing field is valid.
	ANNSNAPTOGRID_LINE_STYLE	[0x0008] uLineStyle field is valid.
	ANNSNAPTOGRID_ENABLE_SNAP	[0x0010] bEnableSnap field is valid.
	ANNSNAPTOGRID_SHOW_GRID	[0x0020] bShowGrid field is valid.
	ANNSNAPTOGRID_AUTO_CHANGE_GRID_LENGTH	[0x0040] bAutoChangeGridLength field is valid.
	ANNSNAPTOGRID_ALL	Use all flags, the value of this flag equals to (
		ANNSNAPTOGRID_GRID_COLOR \|
		ANNSNAPTOGRID_GRID_LENGTH \|
		ANNSNAPTOGRID_LINE_SPACING \|
		ANNSNAPTOGRID_LINE_STYLE \|
		ANNSNAPTOGRID_ENABLE_SNAP \|
		ANNSNAPTOGRID_SHOW_GRID \|
		ANNSNAPTOGRID_AUTO_CHANGE_GRID_LENGTH)
crGridColor	A COLORREF value that represents the color to be used for the overlayed grid.

uGridLength	The length of the grid (in pixels viewed at 100%). Must be between 5 and 999 inclusive.
uLineSpacing	Frequency that lines are drawn over the grid dot-pattern. Must be between 1 and 100 inclusive.
uLineStyle	The constant that specifies the line style. Possible values are:
	Value	Meaning
	ANNLINE_SOLID	[0] Solid line.
	ANNLINE_DASH	[1] Dashed line.
	ANNLINE_DOT	[2] Dotted line.
	ANNLINE_DASHDOT	[3] Dash dot line.
	ANNLINE_DASHDOTDOT	[4] Dash dot line.
	ANNLINE_NULL	[5] No line.
	Note: Windows displays all lines greater than 1 pixel as solid.
	To see the possible line styles, refer to Illustration of Line Styles for Annotations.
bEnableSnap	Flag that indicates the 'snap' behavior when drawing or moving annotation objects in design mode. Possible values are:
	Value	Meaning
	TRUE	Moving or drawing annotation objects snap to the nearest grid point.
	FALSE	Moving or drawing annotation objects do not snap to nearest grid point.
bShowGrid	Flag that indicates whether or not do display the grid in design mode. Possible values are:
	Value	Meaning
	TRUE	Display the grid design mode.
	FALSE	Do not display the grid.
bAutoChangeGridLength	Flag that indicates whether or not to atomically increase the resolution of the grid when zooming in by 100%, 200%, 400% and so on:
	Value	Meaning
	TRUE	If possible, automatically increase the resolution of the grid when zooming.
	FALSE	Do not automatically increase the resolution of the grid when zooming.
nReserved	Reserved for future use. Must be set to zero.

Comments

The ANNSNAPTOGRIDOPTIONS structure is used with the functions L_AnnSetSnapToGrid and L_AnnGetSnapToGrid to get or set the annotation snap to grid behavior in annotation automation design mode. When calling the L_AnnGetSnapToGrid function, the uFlags field identifies which fields to retrieve. When calling the L_AnnSetSnapToGrid function, the uFlags field identifies which fields to set.

The snap-to-grid feature is used in annotation automation design mode to allow the user to precisely draw, locate, and align annotation objects. When snap-to-grid is enabled (see L_AnnSetSnapToGrid), a grid pattern consisting of dots and lines is overlayed on the image. When creating annotations in design mode, each point snaps to the nearest grid point. This beavior holds for creating any annotation object EXCEPT the freehand annotation. When creating a freehand annotation, the individual points do NOT snap to the nearest grid point because this would adversely affect the behavior of the freehand. The snap-to-grid feature affects the moving of all annotations object types in design mode, in that the bounding box of the annotation object snaps to the nearest grid point.

The grid that is overlayed can be customized by color (see crGridColor), grid spacing (see uGridLength), and line frequency (see uLineSpacing). For example, to display a red grid that has a dot pattern every 20 pixels, and solid lines every 100 pixels, you would set:

crGridColor = RGB(255,0,0)
uLineSpacing = 20
uLineStyle = ANNLINE_SOLID
uLineSpacing = 5

The lines of the grid can be removed completely by setting uLineStyle to be ANNLINE_NULL. The lines of the grid can be drawn in any style (see uLineStyle). The grid itself can be hidden (see bShowGrid) so that the snap-to-grid feature is still on without the grid being overlaid on the image. Conversely, the grid can be displayed (see bShowGrid) while disabling the snap-to-grid-behavior (see the L_AnnSetSnapToGrid function).

Setting bAutoChangeGridLength to TRUE affects the grid density when zooming. The effect is that when zooming to 200%, the density of the dot pattern doubles. When zooming to 400%, the density doubles again. The density doubles at 200%, 400%, 800%, 1600% and so on as long as it is meaningful to double the density. In other words, if doubling the dot density would create a dot where no pixel exists when viewing at 100%, then the dot density will not change. The following examples illustrate this.

Example 1: uGridLength is 10
The dot density doubles at 200% because 10 is evenly divisible by 2.
The dot density does not double again at 400% because 10 do not evenly divide 4.

Example 2: uGridLength is 20
The dot density doubles at 200%, and doubles again at 400%.
The dot density does not double again at 800% because 20 does not divide 8 evenly.

Example 3: uGridLength is 21
The dot density never changes because 21 is a prime number.

The snap-to-grid behavior can be turned on our off in annotation automation mode by right-clicking on a part of the image that does not contain an annotation, and selecting the Snap To Grid option from the pop up menu. The snap-to-grid behavior can be customized in annotation automation mode by

right-clicking on a part of the image that does not contain an annotation
selecting Default Properties
clicking on the "Snap to Grid..." menu option

Example

This sample
* gets the current state of the snap-to-grid
* changes the snap to grid to grid size of 10, lines every ten row of dots, solid red lines
* enables the snap to grid

L_TCHAR* getLineStyleString(L_UINT uLineStyle)
{
   TCHAR *pszLineStyle = TEXT("");
   switch(uLineStyle)
   {
   case ANNLINE_SOLID:
      pszLineStyle = TEXT("ANNLINE_SOLID");
      break;
   case ANNLINE_DASH:
      pszLineStyle = TEXT("ANNLINE_DASH");
      break;

   case ANNLINE_DOT:
      pszLineStyle = TEXT("ANNLINE_DOT");
      break;

   case ANNLINE_DASHDOT:
      pszLineStyle = TEXT("ANNLINE_DASHDOT");
      break;

   case ANNLINE_DASHDOTDOT:
      pszLineStyle = TEXT("ANNLINE_DASHDOTDOT");
      break;

   case ANNLINE_NULL:
      pszLineStyle = TEXT("ANNLINE_NULL");
      break;
   }

   return pszLineStyle;

}

L_VOID DisplaySnapToGrid(HANNOBJECT hAutomation, L_TCHAR *pszTitle)
{
#if defined (LEADTOOLS_V16_OR_LATER)
   L_TCHAR szMsg[200] = {0};
   ANNSNAPTOGRIDOPTIONS options = {0};
   L_UINT uSnapToGridMode = ANN_SNAPTOGRID_OFF;
   options.uStructSize = sizeof(ANNSNAPTOGRIDOPTIONS);
   options.uFlags = ANNSNAPTOGRID_ALL;
   L_INT nRet = L_AnnGetSnapToGrid(hAutomation, &uSnapToGridMode,  &options);
   if(nRet == SUCCESS)
   {
      wsprintf(szMsg, TEXT("uSnapToGridMode[%s]\ncrGridColor[0x%x]\nuGridLength[%d]\nuLineSpacing[%d]\nuLineStyle[%s]\nbEnableSnap[%s]\nbShowGrid[%s]\nbAutoChangeGridLength[%s]"),
         uSnapToGridMode == ANN_SNAPTOGRID_OFF ? TEXT("ANN_SNAPTOGRID_OFF") : TEXT("ANN_SNAPTOGRID_ON"),
         options.crGridColor,
         options.uGridLength,
         options.uLineSpacing,
         getLineStyleString(options.uLineStyle),
         options.bEnableSnap ? TEXT("TRUE") : TEXT("FALSE"),
         options.bShowGrid ? TEXT("TRUE") : TEXT("FALSE"),
         options.bAutoChangeGridLength ? TEXT("TRUE") : TEXT("FALSE")
         );

      MessageBox(NULL, szMsg, pszTitle, MB_OK);
   }

#endif
}

L_LTANNTEX_API L_INT SampleAnnSetSnapToGridExample(HANNOBJECT hAutomation)
{
   L_INT nRet = SUCCESS;
#if defined (LEADTOOLS_V16_OR_LATER)
   // Make sure that the snap-to-grid features is enabled
   L_AnnSetOptions(hAutomation, OPTIONS_NEW_ALL | OPTIONS_NEW_SNAPTOGRID);

   // Display current snap-to-grid settings
   DisplaySnapToGrid(hAutomation, TEXT("Original Settings"));

   // Change snap-to-grid to grid size of 10, lines every ten row of dots, solid red lines, and enable it
   ANNSNAPTOGRIDOPTIONS options = {0};
   options.uStructSize = sizeof(ANNSNAPTOGRIDOPTIONS);
   options.uFlags = ANNSNAPTOGRID_ALL;
   options.bAutoChangeGridLength = TRUE;
   options.bEnableSnap = TRUE;
   options.bShowGrid = TRUE;
   options.crGridColor = RGB(255,0,0);
   options.uGridLength = 10;
   options.uLineSpacing = 10;
   options.uLineStyle = ANNLINE_SOLID;
   options.nReserved = 0;

   nRet = L_AnnSetSnapToGrid(hAutomation, ANN_SNAPTOGRID_ON, &options);
   if(nRet == SUCCESS)
   {
      DisplaySnapToGrid(hAutomation, TEXT("New Settings"));
   }

#endif
   return nRet;
}