Using Rulers in Annotation Objects

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

ANNOBJECT_CROSSPRODUCT

ANNOBJECT_POLYRULER

ANNOBJECT_PROTRACTOR

ANNOBJECT_RULER

In addition, the Automation object (ANNOBJECT_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 LAnnAutomation::GetUnit function or the LAnnRuler::GetUnit function. 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 LAnnAutomation::SetUnit or the LAnnRuler::SetUnit function 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.

You can calibrate a ruler by calling the LAnnotation::CalibrateRuler function. For more information, refer to Calibrating Annotation Ruler Objects. This function must be enabled by passing OPTIONS_NEW_ CALIBRATE_RULER to the LAnnotation::SetOptions function before calling LAnnotation::CalibrateRuler. For more information, refer to  Annotation Features.

Each annotation object class that uses rulers has two members that can be used to get the length of a ruler: a GetDistance function and a GetDistance2 function (except the LAnnAutomation class only has LAnnAutomation::GetDistance). The GetDistance member can be used with up to 2 rulers, whereas the AnnGetDistance2 function can be used on any of the ruler objects. Use the GetDistance2 member to get the length of all the rulers in a ANNOBJECT_POLYRULER object. If the annotation object is type ANNOBJECT_CROSSPRODUCT, ANNOBJECT_PROTRACTOR or ANNOBJECT_POLYRULER, the GetDistance2 member 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 function is meant to replace the AnnGetDistance function, which is being phased out.

At each end of the ruler is a perpendicular line called a gauge. Depending on which object is being used, call the LAnnAutomation::SetGaugeLength or the LAnnRuler::SetGaugeLength function 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 LAnnAutomation::GetGaugeLength or the LAnnRuler::GetGaugeLength function 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. Depending on which object is being used, the length of these tick marks can be set using the LAnnAutomation::SetTicMarkLength, the LAnnPolyRuler::SetTicMarkLength, or the LAnnRuler::SetTicMarkLength function The length of the tic mark is expressed in pixels, not in points. Use the LAnnAutomation::GetShowFlags or the LAnnRuler::GetShowFlags function to determine how the rulers are being displayed. Use the LAnnAutomation::SetShowFlags or the LAnnRuler::SetShowFlags function 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 LAnnAutomation::SetBitmapDpiYL function and set the vertical Bitmap DPI value to the bitmap's Y resolution. Likewise, call the LAnnAutomation::SetBitmapDpiXL function 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.