Axis Widget Class

Overview

An Axis widget can be used to provide horizontal or vertical annotation for one or more widgets. The Axis widget can display an axis line, major and minor tick marks, major and minor tick mark labels, auxiliary annotation and a title label. The annotation and tick marks can be scrolled when the associated widget is scrolled.

The displayable range of tick mark labels is defined by the starting and ending values of the Axis widget. The displayable size of the Axis widget is defined by its virtual length in pixels. The range of numbers displayed at a given time is defined by the virtual position in pixels and the width (horizontal Axis) or height (vertical Axis) in pixels of the widget window.

Inherited Behavior and Resources

The Axis widget inherits behavior and resources from the Core and Motif Primitive classes.

The class pointer is xintAxisWidgetClass.
The class name is XintAxis.
The header file is included as <Xint/Axis.h>.

The following resources are defined by the Axis widget class:
Name	Type	Default	Access
XmNannotationAngle	int	0	CSG
XmNannotationOffset	int	2	CSG
XmNannotationFont	char *	"courierbold-r100"	CSG
XmNannotationFormat	String	"%3.1f"	CSG
XmNauxAnnotation	Boolean	True	CSG
XmNauxAnnotationCount	int	0	CSG
XmNauxAnnotationList	char **	NULL	CSG
XmNauxLineStyle	int	XintGRID_LINE_SOLID	CSG
XmNauxPositionList	float	NULL	CSG
XmNauxThickness	int	2	CSG
XmNauxTickLength	int	8	CSG
XmNaxisLineOffset	int	0	CSG
XmNaxisLineThickness	int	2	CSG
XmNaxisType	int	XintAXIS_LINEAR	CSG
XmNcolor	Pixel	black	CSG
XmNcoordinateChangeCallback	XtCallbackList	NULL	C
XmNend	float *	100.0	CSG
XmNendAnnotation	Boolean	True	CSG
XmNendTickLength	int	8	CSG
XmNlabel	char *	"Axis"	CSG
XmNlabelColor	Pixel	black	CSG
XmNlabelFont	char *	"courierbold-r120"	CSG
XmNlabelOffset	int	10	CSG
XmNlabelOrientation	int	XintPARALLEL_TO_AXIS	CSG
XmNmajorAnnotation	Boolean	True	CSG
XmNmajorIncrement	float *	10.0	CSG
XmNmajorLineStyle	int	XintGRID_LINE_SOLID	CSG
XmNmajorThickness	int	2	CSG
XmNmajorTickLength	int	8	CSG
XmNminorAnnotation	Boolean	False	CSG
XmNminorIncrement	float *	5.0	CSG
XmNminorLineStyle	int	XintGRID_LINE_SOLID	CSG
XmNminorThickness	int	2	CSG
XmNminorTickLength	int	4	CSG
XmNopposite	Boolean	False	CSG
XmNorientation	unsigned char	XintHORIZONTAL	CG
XmNroundAnnotation	Boolean	NULL	CSG
XmNscrollBar	Widget	NULL	CSG
XmNselectionCallback	XtCallbackList	NULL	C
XmNstart	float *	0.0	CSG
XmNtextThreeD	Boolean	False	CSG
XmNthumbMovedCallback	XtCallbackList	NULL	C
XmNtickChangeCallback	XtCallbackList	NULL	C
XmNvirtualLength	int	0	CSG
XmNvirtualPosition	int	0	CSG

Resource Value Description
XintGRID_LINE_DOUBLE_DASHED Solid ticks and double dashed grid lines.
XintGRID_LINE_DASHED Solid ticks and dashed grid lines.
XintGRID_LINE_SHADOW_IN 3D appearance for ticks and grid lines.
XintGRID_LINE_SHADOW_OUT 3D appearance for ticks and grid lines.
XintGRID_LINE_SOLID Solid ticks and grid lines.

Resource Value	Description
XintGRID_LINE_DOUBLE_DASHED	Solid ticks and double dashed grid lines.
XintGRID_LINE_DASHED	Solid ticks and dashed grid lines.
XintGRID_LINE_SHADOW_IN	3D appearance for ticks and grid lines.
XintGRID_LINE_SHADOW_OUT	3D appearance for ticks and grid lines.
XintGRID_LINE_SOLID	Solid ticks and grid lines.

XmNauxPositionList

Specifies an array of user coordinates that defines where the annotation strings provided in resource XmNauxAnnotationList are located. The size of the list is specified in resource XmNauxAnnotationCount.

XmNauxThickness

Specifies the width of the auxiliary tick marks in pixel units.

XmNauxTickLength

Specifies the length of the auxiliary tick marks in pixel units. Specify 0 if you do not want auxiliary tick marks.

XmNaxisLineOffset

Specifies the number of pixels between the axis line and the window.

XmNaxisLineThickness

Specifies the thickness of the axis line. Specify 0 if you don't want an axis line. The line style used to draw the axis line is set using resource XmNmajorLineStyle.

XmNaxisType

Specifies the type of axis to be drawn. Choices are XintAXIS_LINEAR for a linear axis and XintAXIS_LOG for a logarithmic axis.

XmNcolor

Specifies the pixel color used to draw the axes lines, annotation and tick marks. This resource is also used to draw the grid lines if the Axis widget is connected to a Grid or VirtualGrid widget. This resource is not used when resource XmNlineThreeD is set to True.

XmNcoordinateChangeCallback

Specifies the list of callbacks that is called when the axis start or end values (values of XmNstart and XmNend) are changed. This callback is also invoked when resource XmNvirtualLength changes.

XmNend

Specifies the end value of the Axis in user coordinates.

XmNendAnnotation

Specifies whether or not the end values of the axis are drawn or not.

XmNendTickLength

Specifies the length of the end tick marks in pixel units. Specify 0 if you do not want end tick marks.

XmNlabel

Specifies the string that is used to draw the title label of the axis. Specifies NULL if you do not want an axis title.

XmNlabelColor

Specifies the pixel color used to draw the axis label.

XmNlabelFont

Specifies the X-Window font name to use when drawing the label title. This font will only be used if resource XmNlabelAngle is set to 0.

XmNlabelOffset

Specifies the number of pixels between the top of an end tick annotation and the axis label.

XmNlabelOrientation

Specifies the orientation of the label. Possible values are:

Resource Value Description
XintPARALLEL_TO_AXIS (default) Label is drawn parallel to axis.
XintSTACKED Letters of label are stacked vertically.
XintPERPENDICULAR_TO_AXIS Label is drawn perpendicular to axis.

Resource Value	Description
XintPARALLEL_TO_AXIS (default)	Label is drawn parallel to axis.
XintSTACKED	Letters of label are stacked vertically.
XintPERPENDICULAR_TO_AXIS	Label is drawn perpendicular to axis.

XmNmajorAnnotation

Specifies whether major annotations are drawn or not. When the axis is logarithmic, major annotations correspond to the cycle starting at the value defined by resource XmNstart.

XmNmajorIncrement

Specifies the increment, in user coordinates, for major annotation.

XmNmajorLineStyle

Specifies the line style used to draw major ticks, grid lines (if the Axis widget is connected to a VirtualGrid widget), and the base axis line. Possible values are:

Resource Value Description
XintGRID_LINE_DOUBLE_DASHED Solid ticks and double dashed grid lines.
XintGRID_LINE_DASHED Solid ticks and dashed grid lines
XintGRID_LINE_SHADOW_IN 3D appearance for ticks and grid lines.
XintGRID_LINE_SHADOW_OUT 3D appearance for ticks and grid lines.
XintGRID_LINE_SOLID Solid line for ticks and grid lines.

Resource Value	Description
XintGRID_LINE_DOUBLE_DASHED	Solid ticks and double dashed grid lines.
XintGRID_LINE_DASHED	Solid ticks and dashed grid lines
XintGRID_LINE_SHADOW_IN	3D appearance for ticks and grid lines.
XintGRID_LINE_SHADOW_OUT	3D appearance for ticks and grid lines.
XintGRID_LINE_SOLID	Solid line for ticks and grid lines.

XmNmajorThickness

Specifies the width of major tick marks in pixel units.

XmNmajorTickLength

Specifies the length of major tick marks in pixel units. Specify 0 if you do not want major tick marks.

XmNminorAnnotation

Specifies whether or not to draw minor annotation.

XmNminorIncrement

Specifies the increment, in user coordinates, for minor annotation. This resource is not used if the axis type is logarithmic.

XmNminorLineStyle

Specifies the line style used to draw minor tick and grid lines (if the Axis is connected to a VirtualGrid widget). Possible values are:

Resource Value	Description
XintGRID_LINE_DOUBLE_DASHED	Solid ticks and double dashed grid lines.
XintGRID_LINE_DASHED	Solid ticks and dashed grid lines.
XintGRID_LINE_SHADOW_IN	3D appearance for ticks and grid lines.
XintGRID_LINE_SHADOW_OUT	3D appearance for ticks and grid lines.
XintGRID_LINE_SOLID	Solid line for ticks and grid lines.

XmNminorThickness

Specifies the width of minor tick marks in pixel units.

XmNminorTickLength

Specifies the length of minor tick marks in pixel units. Specify 0 if you do not want minor tick marks.

XmNopposite

Specifies the position of the axis line. If the axis is horizontal, the axis line is drawn below the Axis annotation when this resource is False and above the Axis annotation when it is True. If the axis is vertical, the axis line is drawn at the left of the Axis annotation when this resource is False, and at the right when the resource is True. This resource must thus be set to True when the Axis widget is placed right or below a grid, and False when the Axis widget is placed left or above a grid.

XmNorientation

Specifies whether the axis is displayed vertically (XintVERTICAL) or horizontally (XintHORIZONTAL).

XmNroundAnnotation

Specifies whether annotation is placed at a multiple of the increment (True) or at the starting value plus multiples of the increment (False).

XmNscrollBar

Specifies the ID of a ScrollBar widget to be connected with the Axis widget. If specified, the axis widget sets the virtual fields of the ScrollBar and any manipulation of the ScrollBar is reflected by the Axis widget. In addition, any modification of the Axis widget resources will be reflected in the ScrollBar widget. ScrollBar resource XmNminimum is set to 0, resource XmNmaximum is set to the Axis widget virtual length as specified in resource XmNvirtualLength, and resource XmNsliderSize is set to the width (horizontal Axis) or height (vertical Axis) of the Axis widget window.

XmNselectionCallback

Specifies a list of callbacks that is called when a user selects the Axis widget. The callback structure is XintAxisCallbackStruct. The reason sent by the callback is XintCR_SELECTION.

XmNstart

Specifies the starting value of the Axis widget in user coordinates.

XmNtextThreeD

Specifies whether or not the tick annotation and title label are drawn with a three dimensional look. The top and bottom shadow colors of the parent widget will be used to draw the tick annotation and title label when this resource is True. If this resource is set to False, the color specified in resource XmNcolor will be used.

XmNthumbMovedCallback

Specifies the list of callbacks that is called when resource XmNvirtualPosition is changed. This is usually caused when the associated ScrollBar widget is moved or when resource XmNvirtualPosition is changed.

XmNtickChangeCallback

Specifies the list of callbacks that is called when any of the tick visual attributes are changed.

XmNvirtualLength

Specifies the displayable length in pixels of the Axis widget. If this resource is set to 0, the scrolling feature of the Axis widget is disabled and the displayable length is equal to the widget window size. Otherwise, this resource must be equal or greater than the width (horizontal axis) or the height (vertical axis) of the Axis widget's window. Resource XmNstart corresponds to 0 and resource XmNend corresponds to the value of resource XmNvirtualLength. When the Axis widget is created inside a Grid widget this resource is automatically set to 0.

XmNvirtualPosition

Specifies the starting position in pixel units of the visible portion within the virtual length of the axis (resource XmNvirtualLength). This resource is only used when the Axis widget is used in virtual mode, usually in conjunction with a VirtualGrid widget. The axis window width (for a horizontal widget) or height (for a vertical widget) acts as the thumb in the virtual length that is currently displayed. Valid values for resource XmNvirtualPosition are between 0 and the value of resource XmNvirtualLength. If the Axis widget is created inside a Grid widget, this resource will always be set to 0.

Defined Actions

The following action procedures are defined by the Axis widget class and can be tied to user actions via a translation table

Name Description
Top() Moves the virtual position of the Axis widget back at the top (or left if horizontal axis).
Bottom() Moves the virtual position of the Axis widget at the bottom (or right if horizontal axis).
Page(up) Moves the virtual position of the Axis widget up one thumb length.
Page(down) Moves the virtual position of the Axis widget down one thumb length.
Increment(up) Moves the virtual position of the Axis widget up by a half thumb length.
Increment(down) Moves the virtual position of the Axis widget down by a half thumb length.
SelectionCallback() Whenever a selection is made inside the widget window, this action calls the list of procedures specified by resource XmNselectionCallback.
TraverseCurrent() Moves the focus to the Axis widget.

Name	Description
Top()	Moves the virtual position of the Axis widget back at the top (or left if horizontal axis).
Bottom()	Moves the virtual position of the Axis widget at the bottom (or right if horizontal axis).
Page(up)	Moves the virtual position of the Axis widget up one thumb length.
Page(down)	Moves the virtual position of the Axis widget down one thumb length.
Increment(up)	Moves the virtual position of the Axis widget up by a half thumb length.
Increment(down)	Moves the virtual position of the Axis widget down by a half thumb length.
SelectionCallback()	Whenever a selection is made inside the widget window, this action calls the list of procedures specified by resource XmNselectionCallback.
TraverseCurrent()	Moves the focus to the Axis widget.

Default Translations

The following translation table is used by default for the action procedures defined by an Axis widget. These default translations can be overridden by the end-user or the application programmer.

Event Sequence Action Name
<Key>osfBeginLine Top()
<Key>osfEndLine Bottom()
<key>osfPageUp Page(up)
<key>osfPageDown Page(down)
~Shift Ctrl <Key> osfUp Page(up)
~Shift Ctrl <Key> osfLeft Page(up)
~Shift Ctrl <Key> osfDown Page(down)
~Shift Ctrl <Key> osfRight Page(down)
~Shift Ctrl <Key>osfPageUp Page(up)
<Btn1Down> TraverseCurrent()
SelectionCallback()
~Shift ~Ctrl <Key>osfUp Increment(up)
~Shift ~Ctrl <Key>osfDown Increment(down)
~Shift ~Ctrl <Key>osfLeft Increment(up)
~Shift ~Ctrl <Key>osfRight Increment(down)

Event Sequence	Action Name
<Key>osfBeginLine	Top()
<Key>osfEndLine	Bottom()
<key>osfPageUp	Page(up)
<key>osfPageDown	Page(down)
~Shift Ctrl <Key> osfUp	Page(up)
~Shift Ctrl <Key> osfLeft	Page(up)
~Shift Ctrl <Key> osfDown	Page(down)
~Shift Ctrl <Key> osfRight	Page(down)
~Shift Ctrl <Key>osfPageUp	Page(up)
<Btn1Down>	TraverseCurrent() SelectionCallback()
~Shift ~Ctrl <Key>osfUp	Increment(up)
~Shift ~Ctrl <Key>osfDown	Increment(down)
~Shift ~Ctrl <Key>osfLeft	Increment(up)
~Shift ~Ctrl <Key>osfRight	Increment(down)

Defined Callbacks

The following callbacks are defined by the Axis widget class.

Name Structure Reason
XmNcoordinateChangeCallback XintAxisCallbackStruct XintCR_VALUE_CHANGED
XmNselectionCallback XintAxisCallbackStruct XintCR_SELECTION
XmNthumbMovedCallback XintAxisCallbackStruct XintCR_DRAG
XmNtickChangeCallback XintAxisCallbackStruct XintCR_TICK_CHANGED

Name	Structure	Reason
XmNcoordinateChangeCallback	XintAxisCallbackStruct	XintCR_VALUE_CHANGED
XmNselectionCallback	XintAxisCallbackStruct	XintCR_SELECTION
XmNthumbMovedCallback	XintAxisCallbackStruct	XintCR_DRAG
XmNtickChangeCallback	XintAxisCallbackStruct	XintCR_TICK_CHANGED

XintAxisCallbackStruct

The following ordered table lists the members of the callback structure, XintAxisCallbackStruct, used by the Axis widget class for all of its callbacks.

Data Type Member Description
int reason Indicates why the callback was invoked.
XEvent * event Points to the XEvent that triggered the callback.
int old_position Virtual position before the axis moved.
int new_position New virtual position of the axis.
Boolean horizontal True if axis is horizontal.

Data Type	Member	Description
int	reason	Indicates why the callback was invoked.
XEvent *	event	Points to the XEvent that triggered the callback.
int	old_position	Virtual position before the axis moved.
int	new_position	New virtual position of the axis.
Boolean	horizontal	True if axis is horizontal.

Defined Functions

The following functions are defined for creating and manipulating the Axis widget.

Function Name Description
XintCreateAxis Creates an Axis widget.
XintAxisGetVisibleLimits Returns the visible range of an Axis widget.
XintAxisPixelToUser Transforms a pixel location into a user coordinate.
XintAxisUserToPixel Transforms a user coordinate into a pixel location.

Function Name	Description
XintCreateAxis	Creates an Axis widget.
XintAxisGetVisibleLimits	Returns the visible range of an Axis widget.
XintAxisPixelToUser	Transforms a pixel location into a user coordinate.
XintAxisUserToPixel	Transforms a user coordinate into a pixel location.

XintCreateAxis

XintCreateAxis creates an unmanaged Axis widget.

     Widget XintCreateAxis (...)

Widget parent Parent of the new Axis widget.
char * name Name of the new Axis widget.
ArgList arglist List of resource/value items.
Cardinal argcount Number of items in arglist.

XintAxisGetVisibleLimits

This function returns the visible range currently displayed by an Axis widget, in user coordinates.

     void XintAxisGetVisibleLimits (...)

Widget widget ID of the Axis widget.
float * start Returns the first visible value.
float * end Returns the last visible value.

XintAxisPixelToUser

This function converts a pixel location in the virtual length of an Axis widget into a user coordinate.

     Boolean XintAxisPixelToUser (...)

Widget widget ID of the Axis widget.
int pixel Pixel location.
float * user_coordinate Returns the user coordinate corresponding to pixel.

The function returns False if argument pixel is out of range.

XintAxisUserToPixel

This function transforms a user value into the corresponding pixel value in the virtual length of an Axis widget.

     Boolean XintAxisUserToPixel (...)

Widget widget ID of the Axis widget.
float user_coordinate Specifies a user coordinate.
int * pixel Returns the pixel value corresponding to user_coordinate.

This function returns False if argument user_coordinate is outside the widget start and end values.

Widget	parent	Parent of the new Axis widget.
char *	name	Name of the new Axis widget.
ArgList	arglist	List of resource/value items.
Cardinal	argcount	Number of items in arglist.

Widget	widget	ID of the Axis widget.
float *	start	Returns the first visible value.
float *	end	Returns the last visible value.