ANNSNAPTOGRIDOPTIONS

Summary

The ANNSNAPTOGRIDOPTIONS structure provides the annotation snap-to-grid behavior in annotation automation design mode.

Syntax

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; 

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:

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

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:

  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

Usage

Example

This sample:

Help Version 22.0.2023.7.11
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Raster Imaging C API Help

Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.