Ruler Object Library: 3 VisRuler Instance Data

The VisRuler's instance data fields are listed below. Depending on your setup, the management of most of these fields will probably be taken care of by the ruler itself or some of its associated controllers. However, many programs set values for the VRI_rulerAttrs , VRI_constrainStrategy , and VRI_slave fields when defining their rulers.

Code Display 19-1

@classVisRulerClass,VisClass;
@instance VisRulerAttributes VRI_rulerAttrs;

typedef ByteFlags VisRulerAttributes; 
#define VRA_IGNORE_ORIGIN 				0x80
#define VRA_SHOW_GUIDES 				0x40
#define VRA_SHOW_GRID 				0x20
#define VRA_SHOW_MOUSE 				0x10
#define VRA_HORIZONTAL 				0x08
#define VRA_MASTER 				0x04

@instance VisRulerType VRI_type;

typedef ByteEnum VisRulerType; 
  #define VRT_INCHES 			0x0
#define VRT_CENTIMETERS 			0x1
#define VRT_POINTS 			0x2
#define VRT_PICAS 			0x3
#define VRT_CUSTOM 			CUSTOM_RULER_DEFINITION
#define VRT_NONE 			NO_RULERS
#define VRT_DEFAULT 			SYSTEM_DEFAULT

@instance VisRulerConstrainStrategy VRI_constrainStrategy;

typedef WordFlags VisRulerConstrainStrategy; 
#define VRCS_OVERRIDE 							0x8000
#define VRCS_SET_REFERENCE 							0x2000
#define VRCS_SNAP_TO_GRID_X_ABSOLUTE 							0x1000
#define VRCS_SNAP_TO_GRID_Y_ABSOLUTE 							0x0800
#define VRCS_SNAP_TO_GRID_X_RELATIVE 							0x0400
#define VRCS_SNAP_TO_GRID_Y_RELATIVE 							0x0200
#define VRCS_SNAP_TO_GUIDES_X 							0x0100
#define VRCS_SNAP_TO_GUIDES_Y 							0x0080
#define VRCS_CONSTRAIN_TO_HORIZONTAL_AXIS 							0x0040
#define VRCS_CONSTRAIN_TO_VERTICAL_AXIS 							0x0020
#define VRCS_CONSTRAIN_TO_UNITY_SLOPE_AXIS 							0x0010
#define VRCS_CONSTRAIN_TO_NEGATIVE_UNITY_SLOPE_AXIS 							0x0008
#define VRCS_CONSTRAIN_TO_VECTOR 							0x0004
#define VRCS_CONSTRAIN_TO_VECTOR_REFLECTION 							0x0002
#define VRCS_INTERNAL 							0x0001

@instance MinIncrementType 			VRI_minIncrement; /* minimum increment displayed */

  typedef union {
	MinUSMeasure 			MIT_US;
	MinMetricMeasure 			MIT_METRIC;
	MinPointMeasure 			MIT_POINT;
	MinPicaMeasure 			MIT_PICA;
} MinIncrementType;

typedef ByteEnum   MinUSMeasure; 
#define MUSM_EIGHTH_INCH 				0x0
#define MUSM_QUARTER_INCH 				0x1
#define MUSM_HALF_INCH 				0x2
#define MUSM_ONE_INCH 				0x3

typedef ByteEnum   MinMetricMeasure;
#define MMM_MILLIMETER 				0x0
#define MMM_HALF_CENTIMETER 				0x1
#define MMM_CENTIMETER 				0x2

typedef ByteEnum   MinPointMeasure; 
#define MPM_25_POINT 				0x0
#define MPM_50_POINT 				0x1
#define MPM_100_POINT 				0x2

typedef ByteEnum   MinPicaMeasure;
#define MPM_PICA 				0x0
#define MPM_INCH 				0x1

@instance WWFixed VRI_scale; /* scale factor */

@instance DWFixed VRI_origin; /* 0,0 of the ruler in document coordinates */

@instance PointDWFixed VRI_reference;

@instance sdword VRI_mouseMark;

@instance word VRI_window; /* actually a noreloc WindowHandle */

@instance optr VRI_slave;

@instance Grid VRI_grid;

@instance WWFixed VRI_vectorSlope; /* slope of vector */

@instance optr VRI_guideArray;

@instance word VRI_guideInfluence; /* influence of guides in pixels */

@instance word VRI_desiredSize;

@instance word VRI_reserved;

@instance dword VRI_invalOD; /* actually a noreloc optr */

@instance word VRI_transformGState; /* actually a noreloc GStateHandle */

The VRI_rulerAttrs field contains flags which determine whether the ruler will support given features. This field tends to vary between applications; put some thought into which flags to turn on.

VRA_IGNORE_ORIGIN: Using the VRI_origin field, it is possible to set an origin for the user to use based upon the coordinates of the graphic space within the main view. This can come in handy when the zero point for the ruler shouldn't correspond to the very left or top of the view; GeoWrite uses this when the user wants the ruler's origin to be based upon the right edge of a text object rather than the edge of the view. The VRA_IGNORE_ORIGIN flag effectively turns off this feature.
VRA_SHOW_GUIDES: This flag indicates that the user wants guidelines drawn over their main view.
VRA_SHOW_GRID: This flag indicates that the user wants gridlines drawn over the main view.
VRA_SHOW_MOUSE: This flag indicates that the ruler should draw a tick mark to show the mouse pointer's location.
VRA_HORIZONTAL: This flag indicates that the ruler is horizontal. Horizontal rulers should have this flag turned on; vertical rulers should not.
VRA_MASTER: If a given view has only one ruler associated with it, that ruler should have this flag set. If a given view has more than one ruler (perhaps having one horizontal and one vertical), one of these rulers should be set up as the master ruler. It should have the VRA_MASTER flag set and should have the second ruler's optr in its VRI_slave field. If there is a third ruler, the second ruler should have its optr in its (the second ruler's) VRI_slave field, and so on.

The VRI_constrainStrategy field contains the default mouse constraint strategy the ruler should use when constraining mouse movement.

VRCS_OVERRIDE: This flag isn't really meant to be part of the default mouse constraint; it will be ignored if in the VRI_constrainStrategy field. During some events other constrain strategies may be combined with the default mouse constrain strategy; if the other strategy's VRCS_OVERRIDE flag is set, then the default mouse constraint strategy field will be ignored.
VRCS_SET_REFERENCE: This flag signals that the next selection should signal that the user wishes the point clicked on to be the reference point, which is used with certain kinds of mouse constraint.
VRCS_SNAP_TO_GRID_X_ABSOLUTE: This flag signals that the mouse position should be snapped to the grid horizontally.
VRCS_SNAP_TO_GRID_Y_ABSOLUTE: This flag signals that the mouse position should be snapped to the grid vertically.
VRCS_SNAP_TO_GRID_X_RELATIVE: This flag signals that the mouse position should be horizontally snapped to a grid such as would be formed if the present grid spacing was used with the reference point as the grid's origin.
VRCS_SNAP_TO_GRID_Y_RELATIVE: This flag signals that the mouse position should be vertically snapped to a grid such as would be formed if the present grid spacing was used with the reference point as the grid's origin.
VRCS_SNAP_TO_GUIDES_X: This flag signals that the mouse positions should be horizontally snapped to guidelines. Note that guidelines are only effective within range of their "influence" in pixels.
VRCS_SNAP_TO_GUIDES_Y: This flag signals that the mouse positions should be vertically snapped to guidelines. Note that guidelines are only effective within range of their "influence" in pixels.
VRCS_CONSTRAIN_TO_HORIZONTAL_AXIS: This flag signals that the mouse position should be restrained to the horizontal line passing through the reference point.
VRCS_CONSTRAIN_TO_VERTICAL_AXIS: This flag signals that the mouse position should be restrained to the vertical line passing through the reference point.
VRCS_CONSTRAIN_TO_UNITY_SLOPE_AXIS: This flag signals that the mouse position should be restrained to the diagonal line with slope ( y = x ) passing through the reference point.
VRCS_CONSTRAIN_TO_NEGATIVE_UNITY_SLOPE_AXIS: This flag signals that the mouse position should be restrained to the diagonal line with slope ( y = -x ) passing through the reference point.
VRCS_CONSTRAIN_TO_VECTOR: This flag signals that the mouse position should be constrained to the line passing through the reference and vector points.
VRCS_CONSTRAIN_TO_VECTOR_REFLECTION: This flag signals that the mouse position should be constrained to the reflection of the line passing through the reference and vector points.

The VRI_type and VRI_minIncrement fields determine the measurement type and ruler increment of the ruler.Normally, the user will work with the ruler's type via a RulerTypeControl. RulerTypeControlClass 's features structures are shown below.

Code Display 19-2 RulerTypeControl Features

typedef WordFlags  RTCFeatures;
#define  RTCF_DEFAULT				(0x20)
#define RTCF_SPREADSHEET 				(0x10)
#define RTCF_INCHES 				(0x08)
#define RTCF_CENTIMETERS 				(0x04)
#define RTCF_POINTS 				(0x02)
#define RTCF_PICAS 				(0x01)
#define  RTC_DEFAULT_FEATURES \
	(RTCF_INCHES | RTCF_CENTIMETERS | RTCF_POINTS | RTCF_PICAS | RTCF_DEFAULT)

typedef WordFlags  RTCToolboxFeatures;
#define  RTCTF_DEFAULT 				(0x20)
#define RTCTF_SPREADSHEET 				(0x10)
#define RTCTF_INCHES 				(0x08)
#define RTCTF_CENTIMETERS 				(0x04)
#define RTCTF_POINTS 				(0x02)
#define RTCTF_PICAS 				(0x01)
#define  RTC_DEFAULT_TOOLBOX_FEATURES (RTCF_INCHES | RTCF_CENTIMETERS)

The RulerTypeControl uses a notification block with the following structure:

typedef struct RulerTypeNotificationBlock {
	VisRulerType  RTNB_type;
}  RulerTypeNotificationBlock;

The ruler must keep track of the main view's scale; if the main view has doubled in scale, the ruler should put its tick marks twice as far apart. This scale is stored in the VRI_scale field. The ruler automatically receives a MSG_VIS_RULER_VIEW_SCALE_FACTOR_CHANGED when the main view's scale changes. To set the scale independently of the main view scale, send a MSG_VIS_RULER_SET_SCALE .

The VRI_origin field allows you to set an origin for the ruler other than (0,0). The coordinates are given in terms of the main view's coordinate system.

The reference point, used for various types of mouse constraint, is stored in the VRI_reference field.

VRI_mouseMark contains the coordinate at which the mouse tick is currently being drawn.

The VRI_window field, initiated automatically, holds the window handle of the main view.

The VRI_slave field holds the ruler's slave ruler; see the documentation for VRA_MASTER, above, to learn about master and slave rulers.

TheVRI_grid field contains the information used to maintain the grid associated with a ruler.

The VRI_vectorSlope defines the slope of a vector that may be used with vector mouse constraints.

The VRI_guideArray field keeps track of the location where guideline data is stored; this field is initiated automatically.

The VRI_guideInfluence contains the influence to use when constraining the mouse position to guidelines. Guidelines will only attract the mouse if it is within a certain distance of them--this distance is the "influence" of the guidelines. It is measured in pixels, not points; thus, the guide influence is independent of scale.

The VRI_desiredSize field contains the ruler's idea of its ideal thickness. By default, this is set so that the ruler will have room to draw its numbers and tick marks normally; if you will be subclassing the VisRuler to add more gadgetry, you may wish to use a different value here.

The VRI_invalOD field contains the object descriptor of the object which should be redrawn when the ruler needs to draw something differently to the main view; by the ruler's default behavior, this will be updated automatically via a MSG_VIS_RULER_GAINED_SELECTION .

The VRI_transformGState field contains the handle of a GState. This GState contains the transformation which is used to transform the coordinate system used with mouse constraints.

MSG_VIS_RULER_SET_TYPE

void	MSG_VIS_RULER_SET_TYPE(
        VisRulerType type);

This message sets the VRI_type field.

MSG_VIS_RULER_GET_TYPE

VisRulerType MSG_VIS_RULER_GET_TYPE();

This message returns the value in the VRI_type field.

MSG_VIS_RULER_SET_CONSTRAIN_STRATEGY

void MSG_VIS_RULER_SET_CONSTRAIN_STRATEGY(
        VisRulerConstrainStrategy 				setflags,
        VisRulerConstrainStrategy 				clearflags);

This message sets the default mouse constrain strategy for the ruler.

Parameters: setflags Flags to set.

clearflags: Flags to clear.

Return: Nothing.

MSG_VIS_RULER_GET_CONSTRAIN_STRATEGY

VisRulerConstrainStrategy
MSG_VIS_RULER_GET_CONSTRAIN_STRATEGY();

This message gets the current default constrain strategy for the ruler.

MSG_VIS_RULER_SET_IGNORE_ORIGIN

void MSG_VIS_RULER_SET_IGNORE_ORIGIN(
        Boolean 		ignore);

This message sets the "ignore origin" state.

Parameters: ignore Set true (i.e. non-zero) to ignore the origin. Set false (i.e. zero) not to ignore the origin.

Return: Nothing.

MSG_VIS_RULER_SET_ORIGIN

void MSG_VIS_RULER_SET_ORIGIN(
        sdword 		pointInt, 
        word 		pointFrac);

Use this message to set the ruler's origin point.

MSG_VIS_RULER_GET_ORIGIN

void MSG_VIS_RULER_GET_ORIGIN(
        DWFixedReturn *retval);

Use this message to retrieve the ruler's origin point.

Structures:

typedef struct {
	word 		unused;
	word 		 DWFR_frac;
	sdword 		DWFR_int;
}  DWFixedReturn;

MSG_VIS_RULER_SET_REFERENCE

void MSG_VIS_RULER_SET_REFERENCE( @stack
        sdword 		yInt, 
        word 		yFrac, 
        sdword 		xInt, 
        word 		xFrac);

Set the ruler's reference point.

MSG_VIS_RULER_SET_VECTOR

void MSG_VIS_RULER_SET_VECTOR( @stack
        sdword 		yInt, 
        word 		yFrac, 
        sdword 		xInt, 
        word 		xFrac);

Set the point to use to define the "vector"--together with the reference point, this will form a slope which may be used for mouse constraints.

MSG_VIS_RULER_SET_MIN_INCREMENT

void	MSG_VIS_RULER_SET_MIN_INCREMENT(
        MinIncrementType min);

This message sets the VRI_minIncrement field to the passed value. It must be passed the proper MinIncrementType value.

MSG_VIS_RULER_SET_SCALE

void	MSG_VIS_RULER_SET_SCALE(
        WWFixedAsDWord scale);

This message sets the VRI_scale field.

GEOS SDK TechDocs |

2 Ruler Setup | Next:

4 Managing Rulers