Using Rulers in Annotation Objects

The following annotation objects utilize one or more rulers as part of the annotation:

ANN_OBJECT_CROSSPRODUCT

ANN_OBJECT_POLYRULER

ANN_OBJECT_PROTRACTOR

ANN_OBJECT_RULER

In addition, the Automation object (ANN_OBJECT_AUTOMATION) stores default ruler settings along with the other object default settings.

To determine the unit of measure for each ruler as well as its precision, call the AnnGetUnit method, which fills the AnnUnit property with the unit of measure. Read the AnnUnit property and the AnnPrecision property after calling the AnnGetUnit method to get the current Unit and Precision. The default unit of measure for Ruler, Polyruler, and Crossproduct objects is Smart English. With the smart units, the unit changes with the length. For example, if the length is 11 inches (assuming the default precision of 2 is being used), "11.00 in" displays whereas if the length is 15 inches, "1 ft 3.00 in" displays. Call the AnnSetUnit method to set the unit of measurement and its precision for the ruler. The precision indicates how many digits to display to the right of the decimal point in the length.

There are two methods that can be used to get the length of a ruler: the AnnGetDistance method and the AnnGetDistance2 method. The AnnGetDistance method can be used with up to 2 rulers, whereas the AnnGetDistance2 method can be used on any of the ruler objects. Call the AnnGetDistance2 method to get the length of all the rulers in a ANN_OBJECT_POLYRULER object. If the annotation object is type ANN_OBJECT_CROSSPRODUCT, ANN_OBJECT_PROTRACTOR or ANN_OBJECT_POLYRULER, the AnnGetDistance2 method provides more information on the length of each ruler, the number of rulers, the unit of measure of each ruler and the total length of all rulers. The AnnGetDistance2 method is meant to replace the AnnGetDistance method, which is being phased out.

At each end of the ruler is a perpendicular line called a gauge. Use the AnnSetGaugeLength method to set the length of the gauge. The length is expressed in pixels, not in points. The length extends from one end point of the gauge, through the end point of the ruler, to the other end point of the gauge. Use the AnnGetGaugeLength method to get the length of the gauge.

Along the length of the ruler are tic marks. The tic marks are the perpendicular lines that measure the units. The length of these tick marks can be set using the AnnTicMarkLength property. The length of the tic mark is expressed in pixels, not in points. Call the AnnGetShowFlags method to determine how the rulers are being displayed. Call the AnnSetShowFlags method to set whether ruler length, gauge and tic marks will be displayed.

Please note that when loading or pasting Automation objects or any objects that use rulers from the clipboard, it is necessary to call the AnnSetBitmapDpiY method and set the vertical Bitmap DPI value to the bitmap's Y resolution. Likewise, call the AnnSetBitmapDpiX method and set the horizontal Bitmap DPI value to the bitmap's X resolution. Doing so ensures that the distances shown by the ruler objects will be accurate.

Call the AnnCalibrateRuler method to calibrate an ANN_OBJECT_RULER object by assigning a specified length to it. Note that although this method only works on ANN_OBJECT_RULER objects, it can be used to indirectly calibrate other objects. For more information, refer to Calibrating Annotation Ruler Objects. In Version 14.5, you need to first enable this function by calling the AnnSetOptions method with the ANN_OPTIONS_NEW_CALIBRATE_RULER flag set. For more information, refer to New Annotation Features of Version 14.5.