XmQTnavigator(3X) UNIX System V XmQTnavigator(3X)
NAME
XmQTnavigator - A widget holding this trait can act as a
navigator
SYNOPSIS
#include <Xm/NavigatorT.h>
typedef struct {
int version;
XmNavigatorMoveCBProc changeMoveCB;
XmNavigatorSetValueProc setValue;
XmNavigatorGetValueProc getValue;
} XmNavigatorTraitRec, *XmNavigatorTrait;
void (*XmNavigatorMoveCBProc)(
Widget,
XtCallbackProc,
XtPointer,
Boolean,
void (*XmNavigatorSetValueProc)(
Widget,
XmNavigatorData,
Boolean,
void (*XmNavigatorGetValueProc)(
Widget,
XmNavigatorData);
VERSION
This page documents Motif 2.1.
DESCRIPTION
A child widget holding the XmQTnavigator trait can act as a
navigator widget. A user can manipulate a navigator widget
in order to make different parts of a scrollable widget
visible.
In the standard Motif widget set, the XmScrollBar and
XmSpinBoxwidgets hold the XmQTnavigator trait. In the Exm
demonstration widget set, the ExmPanner widget holds this
trait.
Widgets holding the XmQTnavigator trait can cooperate with
widgets holding the XmQTscrollFrame trait.
Two of the trait methods, setValue and getValue, require an
XmNavigatorData structure, which has the following
definition:
typedef struct {
Mask valueMask;
Mask dimMask;
XmTwoDIntRec *value;
XmTwoDIntRec *minimum;
Page 1 (printed 1/22/99)
XmQTnavigator(3X) UNIX System V XmQTnavigator(3X)
XmTwoDIntRec *maximum;
XmTwoDIntRec *slider_size;
XmTwoDIntRec *increment;
XmTwoDIntRec *page_increment;
} XmNavigatorDataRec, *XmNavigatorData;
where XmTwoDIntRec is a 2-field structure defined as
follows:
typedef struct {
int x;
int y;
} XmTwoDIntRec, *XmTwoDInt;
Following is a detailed description of the fields of the
XmNavigatorData structure:
valueMask Holds a bit vector mask. Each bit in the bit
vector mask represents a different field in the
XmNavigatorData structure. If a bit is set, then
the data for that field is valid. If that bit is
not set, then the data within that field is
ignored. Motif provides the following constants,
each representing one bit of the bit mask. The
caller can add any combination of the following
constants in order to form the appropriate
valueMask value:
NavDimMask
Validates the dimMask field.
NavValue Validates the value field.
NavMinimum
Validates the minimum field.
NavMaximum
Validates the maximum field.
NavSliderSize
Validates the slider_size field.
NavIncrement
Validates the increment field.
NavPageIncrement
Validates the page_increment field.
NavAllValid
Validates all fields.
dimMask Holds a bit vector mask. Each bit in the bit
Page 2 (printed 1/22/99)
XmQTnavigator(3X) UNIX System V XmQTnavigator(3X)
vector mask represents a different dimension.
Currently, the only two supported dimensions are x
and y. Therefore, 1 bit of this mask represents
the x dimension and another bit represents the y
dimension. Motif provides the following
constants, each representing 1 bit of the bit
mask. The caller may add any combination of the
following constants in order to form the
appropriate dimMask value:
NavigDimensionX
Validates the x dimension.
NavigDimensionY
Validates the y dimension.
The value of the dimMask field affects the
interpretation of the value, minimum, maximum,
slider_size, increment, and page_increment fields.
The value of dimMaskaffects these other fields
even if NavDimMask is not set. In fact, the only
time that NavDimMask has influence is when the
caller is trying to change or read the value of
dimMask.
value Holds a TwoDIntRec structure containing two
values: one is the value of the navigator widget
in the x dimension, and the other is the value in
the y dimension. For example, suppose the value
in the x dimension is 50, the minimum is 10, and
the maximum is 90. In this case, the navigator
widget will have a horizontal position halfway
between the left and right sides of the widget.
minimum Holds a TwoDIntRec structure containing two
values: one is the minimum value of the navigator
widget in the x dimension and the other is the
minimum value in the y dimension.
maximum Holds a TwoDIntRec structure containing two
values: one is the maximum value of the navigator
widget in the x dimension and the other is the
maximum value in the y dimension.
slider_size
Holds a TwoDIntRec structure containing two
values: one is the slider size of the navigator
widget in the x dimension and the other is the
slider size in the y dimension. The slider_size
value is not an absolute value; for example, it is
not a size in pixels. The actual size of the
slider is based on the ratio of the slider_size to
Page 3 (printed 1/22/99)
XmQTnavigator(3X) UNIX System V XmQTnavigator(3X)
the difference between the minimum and maximum.
For example, suppose the slider_size in the x
dimension is 20, the minimum is 10, and the
maximum is 90. In this case, the difference
between the minimum and the maximum is 80.
Therefore, the slider will occupy 20/80 (or 25%)
of the allocated widget space in the x dimension.
increment Holds a TwoDIntRec structure containing two
values: one is the increment size of the
navigator widget in the x dimension and the other
is the increment size in the y dimension. The
increment size is the amount by which the
valueincreases or decreases when the user takes an
action that moves the slider by one increment.
page_increment
Holds a TwoDIntRec structure containing two
values: one is the page increment size of the
navigator widget in the x dimension and the other
is the page increment size in the y dimension.
The page increment size is the amount by which the
value increases or decreases when the user takes
an action that moves the slider by one page
increment.
The changeMoveCB Trait Method
void changeMoveCB(
Widget navigatorWidget,
XtCallbackProc moveCB,
XtPointer closure,
Boolean setUnset);
The changeMoveCB trait method is responsible for adding or
removing the moveCB callback from the list of callbacks. A
child widget holding the XmQTnavigator trait should provide
a resource that holds the name of the move callback
procedure. This callback will be activated whenever a user
moves an indicator in the navigatorWidget.
Following is a sample implementation of this trait method.
In this implementation, the ExmNmoveCallback resource holds
the name of the move callback procedure.
NavigChangeMoveCB(
Widget navigatorWidget,
XtCallbackProc moveCB,
XtPointer closure,
Boolean setunset)
{
if (setunset)
XtAddCallback (navigatorWidget, ExmNmoveCallback, moveCB, closure);
Page 4 (printed 1/22/99)
XmQTnavigator(3X) UNIX System V XmQTnavigator(3X)
else
XtRemoveCallback (navigatorWidget, ExmNmoveCallback, moveCB, closure);
}
navigatorWidget
Specifies the child widget that is to have its
list of callbacks modified.
moveCB Specifies the callback procedure that is to be
added or removed from the list of callbacks.
closure Specifies additional data to be passed to the
callback.
setUnset Specifies a Boolean value. If this value is True,
the setValuetrait method adds moveCB to the list
of callbacks. If this value is False, the moveCB
is removed from the list of callbacks.
The setValue Trait Method
void setValue(
Widget navigatorWidget,
XmNavigatorData navigatorData,
Boolean notify);
The setValue trait method allows the caller to pass new
navigator data to the navigatorWidget.
navigatorWidget
Specifies the navigator widget that provides this
method.
navigatorData
Specifies an XmNavigatorData structure whose
fields describe the characteristics of the
navigator widget.
notify Specifies a Boolean value. If True, the caller
wants setValue to activate the move callback
procedure whenever there is a change in the value
field of the navigatorData structure.
The getValue Trait Method
void getValue(
Widget navigatorWidget,
XmNavigatorData navigatorData);
The getValue trait method returns the current
navigatorDataheld by the navigatorWidget. Not all of the
fields in the returned navigatorData will hold valid data.
The caller of getValuemust analyze the returned valueMask
and dimMask fields to determine which of the other fields
Page 5 (printed 1/22/99)
XmQTnavigator(3X) UNIX System V XmQTnavigator(3X)
hold valid data.
navigatorWidget
Specifies the navigator widget that provides this
method.
navigatorData
Specifies an XmNavigatorData structure whose
fields describe the characteristics of the
navigator widget.
RELATED
XmQTscrollFrame(3), XmScrollBar(3), XmSpinBox(3), and
ExmPanner(3).
Page 6 (printed 1/22/99)