[ Previous |
Next |
Contents |
Glossary |
Home |
Search ]
Motif 2.1 Widget Writer's Guide
XmQTnavigator
A widget holding this trait can act as a navigator
Format
#include <Xm/NavigatorT.h>
typedef struct {
int version;
XmNavigatorMoveCBProc changeMoveCB;
XmNavigatorSetValueProc setValue;
XmNavigatorGetValueProc getValue;
} XmNavigatorTraitRec, *XmNavigatorTrait;
void
(*XmNavigatorMoveCBProc)WidgetXtCallbackProcXtPointerBoolean
void
(*XmNavigatorSetValueProc)WidgetXmNavigatorDataBoolean
void
(*XmNavigatorGetValueProc)WidgetXmNavigatorData
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 XmSpinBox widgets
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;
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:
valueMaskHolds 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:
NavDimMaskValidates the dimMask field.
NavValueValidates the value field.
NavMinimumValidates the minimum field.
NavMaximumValidates the maximum field.
NavSliderSizeValidates the slider_size field.
NavIncrementValidates the increment field.
NavPageIncrementValidates the page_increment field.
NavAllValidValidates all fields.
dimMaskHolds a bit vector mask. Each bit in the bit 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:
NavigDimensionXValidates the x dimension.
NavigDimensionYValidates 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
dimMask affects 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.
valueHolds 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.
minimumHolds 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.
maximumHolds 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_sizeHolds 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 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.
incrementHolds 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 value increases or decreases when the user
takes an action that moves the slider by one increment.
page_incrementHolds 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.
void changeMoveCBWidget
navigatorWidgetXtCallbackProc
moveCBXtPointer closureBoolean
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);
else
XtRemoveCallback (navigatorWidget, ExmNmoveCallback, moveCB,
closure);
}
|
navigatorWidgetSpecifies the child widget that is to have its list of callbacks modified.
moveCBSpecifies the callback procedure that is to be added or removed from the
list of callbacks.
closureSpecifies additional data to be passed to the callback.
setUnsetSpecifies a Boolean value. If this value is True, the
setValue trait method adds moveCB to the list of
callbacks. If this value is False, the moveCB is removed
from the list of callbacks.
void setValueWidget
navigatorWidgetXmNavigatorData
navigatorDataBoolean notify
The setValue trait method allows the caller to pass new
navigator data to the navigatorWidget.
navigatorWidgetSpecifies the navigator widget that provides this method.
navigatorDataSpecifies an XmNavigatorData structure whose fields describe the
characteristics of the navigator widget.
notifySpecifies 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.
void getValueWidget
navigatorWidgetXmNavigatorData
navigatorData
The getValue trait method returns the current
navigatorData held by the navigatorWidget. Not all of the
fields in the returned navigatorData will hold valid data. The caller
of getValue must analyze the returned valueMask and
dimMask fields to determine which of the other fields hold valid
data.
navigatorWidgetSpecifies the navigator widget that provides this method.
navigatorDataSpecifies an XmNavigatorData structure whose fields describe the
characteristics of the navigator widget.
RELATED
XmQTscrollFrame(3), XmScrollBar(3),
XmSpinBox(3), and ExmPanner(3).
[ Previous |
Next |
Contents |
Glossary |
Home |
Search ]