ANNSNAPTOGRIDOPTIONS

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.

Members

uStructSize

Size of this structure in bytes, for versioning. Use the sizeof() operator 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:

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:

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:

bShowGrid

Flag that indicates whether or not do display the grid in design mode. Possible values are:

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:

nReserved

Reserved for future use.  Must be set to zero.

Comments

The ANNSNAPTOGRIDOPTIONS structure is used with the functions LAnnotation::SetSnapToGrid and LAnnotation::GetSnapToGrid to get or set the annotation snap to grid behavior in annotation automation design mode.  When calling the LAnnotation::GetSnapToGrid function, the uFlags field identifies which fields to retrieve.  When calling the LAnnotation::SetSnapToGrid 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 LAnnotation::SetSnapToGrid), 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 LAnnotation::SetSnapToGrid 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

1. right-clicking on a part of the image that does not contain an annotation

2. selecting Default Properties

3. clicking on the "Snap to Grid..." menu option

The structure is used by:

• LAnnotation::SetSnapToGrid
• LAnnotation::GetSnapToGrid

Example

This sample gets the current state of the snap-to-grid and changes the snap-to-grid to grid size of 10 lines, every ten row of dots. Solid red lines enable 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_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; 
}