DtSpinBox(3) UNIX System V (1 August 1995) DtSpinBox(3)
NAME
DtSpinBox - the SpinBox widget class
SYNOPSIS
#include <Dt/SpinBox.h>
DESCRIPTION
The DtSpinBox widget is a user interface control to
increment and decrement an arbitrary TextField. For
example, it can be used to cycle through the months of the
year or days of the month.
Widget subclassing is not supported for the DtSpinBox widget
class.
Classes
The DtSpinBox widget inherits behavior and resources from
the Core, Composite and XmManager classes.
The class pointer is dtSpinBoxWidgetClass.
The class name is DtSpinBoxWidget.
New Resources
The following table defines a set of widget resources used
by the application to specify data. The application can
also set the resource values for the inherited classes to
set attributes for this widget. To reference a resource by
name or by class in a .Xdefaults file, the application must
remove the DtN or DtC prefix and use the remaining letters.
To specify one of the defined values for a resource in a
.Xdefaults file, the application must remove the Dt prefix
and use the remaining letters (in either lower case or upper
case, but including any underscores between words). The
codes in the access column indicate if the given resource
can be set at creation time (C), set by using XtSetValues()
(S), retrieved by using XtGetValues() (G), or is not
applicable (N/A).
DtSpinBox Resource Set
___________________________________________________________________________
Name Class Type Default Access
___________________________________________________________________________
DtNarrowLayout DtCArrowLayout unsigned char DtARROWS_END CSG
DtNarrowSensitivity DtCArrowSensitivityunsigned char DtARROWS- CSG
_SENSITIVE
DtNdecimalPoints DtCDecimalPoints short 0 CSG
DtNincrementValue DtCIncrementValue int 1 CSG
DtNinitialDelay DtCInitialDelay unsigned int 250 CSG
DtNmaximumValue DtCMaximumValue int 10 CSG
Page 1 (printed 9/3/04)
DtSpinBox(3) UNIX System V (1 August 1995) DtSpinBox(3)
DtNminimumValue DtCMinimumValue int 0 CSG
DtNmodifyVerifyCallbackDtCCallback XtCallbackListNULL C
DtNnumValues DtCNumValues int 0 CSG
DtNposition DtCPosition int 0 CSG
DtNrepeatDelay DtCRepeatDelay unsigned int 200 CSG
DtNspinBoxChildType DtCSpinBoxChildTypeunsigned char XmSTRING CG
DtNvalueChangedCallbackDtCCallback XtCallbackListNULL C
DtNvalues DtCValues XmStringTable NULL CSG
DtNarrowLayout
Specifies the style and position of the SpinBox
arrows. The following values are supported:
DtARROWS_FLAT_BEGINNING
The arrows are placed side by side to the
right of the TextField.
DtARROWS_FLAT_END
The arrows are placed side by side to the
left of the TextField.
DtARROWS_SPLIT
The down arrow is on the left and the up
arrow is on the right of the TextField.
DtARROWS_BEGINNING
The arrows are stacked and placed on the
left of the TextField.
DtARROWS_END
The arrows are stacked and placed on the
right of the TextField.
DtNarrowSensitivity
Specifies the sensitivity of the arrows in the
DtSpinBox. The following values are supported:
DtARROWS_SENSITIVE
Both arrows are active to user selection.
DtARROWS_DECREMENT_SENSITIVE
The down arrow is active and the up arrow
is inactive to user selection.
DtARROWS_INCREMENT_SENSITIVE
The up arrow is active and the down arrow
is inactive to user selection.
DtARROWS_INSENSITIVE
Both arrows are inactive to user
selection.
Page 2 (printed 9/3/04)
DtSpinBox(3) UNIX System V (1 August 1995) DtSpinBox(3)
DtNdecimalPoints
Specifies the position of the radix character
within the numeric value when DtNspinBoxChildType
is DtNUMERIC. This resource is used to allow for
floating point values in the DtSpinBox widget.
DtNincrementValue
Specifies the amount to increment or decrement the
DtNposition when the DtNspinBoxChildType is
DtNUMERIC. When the Up action is activated, the
DtNincrementValue is added to the DtNposition
value; when the Down action is activated, the
DtNincrementValue is subtracted from the
DtNposition value. When DtNspinBoxChildType is
DtSTRING, this resource is ignored.
DtNinitialDelay
Specifies the amount of time in milliseconds before
the Arrow buttons will begin to spin continuously.
DtNnumValues
Specifies the number of items in the DtNvalues list
when the DtNspinBoxChildType resource is DtSTRING.
The value of this resource must be a positive
integer. The DtNnumValues is maintained by the
DtSpinBox widget when items are added or deleted
from the DtNvalues list. When DtNspinBoxChildType
is not DtSTRING, this resource is ignored.
DtNvalues
Supplies the list of strings to cycle through when
the DtNspinButtonChildType resource is DtSTRING.
When DtNspinBoxChildType is not DtSTRING, this
resource is ignored.
DtNmaximumValue
Specifies the upper bound on the DtSpinBox's range
when DtNspinBoxChildType is DtNUMERIC.
DtNminimumValue
Specifies the lower bound on the DtSpinBox's range
when DtNspinBoxChildType is DtNUMERIC.
DtNmodifyVerifyCallback
Specifies the callback to be invoked just before
the DtSpinBox position changes. The application
can use this callback to implement new
application-related logic (including setting new
position spinning to, or canceling the impending
action). For example, this callback can be used to
stop the spinning just before wrapping at the upper
and lower position boundaries. If the application
Page 3 (printed 9/3/04)
DtSpinBox(3) UNIX System V (1 August 1995) DtSpinBox(3)
sets the doit member of the DtSpinBoxCallbackStruct
to False, nothing happens. Otherwise, the position
changes. Reasons sent by the callback are
DtCR_SPIN_NEXT, or DtCR_SPIN_PRIOR.
DtNposition
The DtNposition resource has a different value
based on the DtNspinBoxChildType resource. When
DtNspinBoxChildType is DtSTRING, the DtNposition is
the index into the DtNvalues list for the current
item. When the DtNspinBoxChildType resource is
DtNUMERIC, the DtNposition is the integer value of
the DtSpinBox that falls within the range of
DtNmaximumValue and DtNminimumValue.
DtNrepeatDelay
Specifies the number of milliseconds between
repeated calls to the DtNvalueChangedCallback while
the user is spinning the DtSpinBox.
DtNspinBoxChildType
Specifies the style of the DtSpinBox. The
following values are supported:
DtSTRING
The child is a string value that is
specified through the DtNvalues resource
and incremented and decremented by
changing the DtNposition resource.
DtNUMERIC
The child is a numeric value that is
specified through the DtNposition resource
and incremented according to the
DtNincrementValue resource.
DtNvalueChangedCallback
Specifies the callback to be invoked whenever the
value of the DtNposition resource is changed
through the use of the spinner arrows. The
DtNvalueChangedCallback passes the
DtSpinBoxCallbackStruct call_data structure.
Inherited Resources
The DtSpinBox widget inherits behavior and resources from
the following named superclasses. For a complete
description of each resource, see the man page for that
superclass.
Page 4 (printed 9/3/04)
DtSpinBox(3) UNIX System V (1 August 1995) DtSpinBox(3)
XmManager Resource Set
_________________________________________________________________________
Name Class Type Default Access
_________________________________________________________________________
XmNbottom- XmCBottom- Pixel dynamic CSG
ShadowColor ShadowColor
XmNbottom- XmCBottom- Pixmap XmUNSPECIFIED-CSG
ShadowPixmap ShadowPixmap _PIXMAP
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCHighlightColor Pixel dynamic CSG
XmNhighlightPixmapXmCHighlightPixmapPixmap dynamic CSG
XmNinitialFocus XmCInitialFocus Widget NULL CSG
XmNnavigationType XmCNavigationType XmNavigationType dynamic CSG
XmNshadowThicknessXmCShadowThicknessDimension dynamic CSG
XmNstringDirectionXmCStringDirectionXmStringDirectiondynamic CG
XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG
XmNtopShadowPixmapXmCTopShadowPixmapPixmap dynamic CSG
XmNtraversalOn XmCTraversalOn Boolean dynamic CSG
XmNunitType XmCUnitType unsigned char dynamic CSG
XmNuserData XmCUserData XtPointer NULL CSG
Composite Resource Set
____________________________________________________________________
Name Class Type Default Access
____________________________________________________________________
XmNchildren XmCReadOnly WidgetList NULL G
XmNinsertPositionXmCInsertPositionXtOrderProcdefault procedureCSG
XmNnumChildren XmCReadOnly Cardinal 0 G
Core Resource Set
_______________________________________________________________________________
Name Class Type Default Access
_______________________________________________________________________________
XmNaccelerators XmCAccelerators XtAcceleratorsdynamic CSG
XmNancestorSensitiveXmCSensitive Boolean dynamic G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED- CSG
_PIXMAP
XmNborderColor XmCBorderColor Pixel XtDefaultForegroundCSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED- CSG
_PIXMAP
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNcolormap XmCColormap Colormap dynamic CG
XmNdepth XmCDepth int dynamic CG
XmNdestroyCallback XmCCallback XtCallbackListNULL C
XmNheight XmCHeight Dimension dynamic CSG
XmNinitialResources-XmCInitialResources-Boolean True C
Persistent Persistent
XmNmappedWhen- XmCMappedWhen- Boolean True CSG
Page 5 (printed 9/3/04)
DtSpinBox(3) UNIX System V (1 August 1995) DtSpinBox(3)
Managed Managed
XmNscreen XmCScreen Screen * dynamic CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslationsdynamic CSG
XmNwidth XmCWidth Dimension dynamic CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Callback Information
A pointer to the following structure is passed to each
DtSpinBox callback:
typedef struct {
int reason;
XEvent *event;
Widget widget;
Boolean doit;
int position;
XmString value;
Boolean crossed_boundary;
} DtSpinBoxCallbackStruct;
The reason argument indicates why the callback was invoked.
There are three possible reasons for this callback to be
issued. The reason is DtCR_OK when this is the first call
to the callback at the beginning of a spin or if it is a
single activation of the spin arrows. If the DtSpinBox is
in the process of being continuously spun, then the reason
will be DtCR_SPIN_NEXT or DtCR_SPIN_PRIOR, depending on the
arrow that is spinning.
The event argument points to the XEvent that triggered the
callback. It can be NULL when the DtSpinBox is continuously
spinning.
The widget argument is the widget identifier for the text
widget that has been affected by the spin.
The doit argument is set only when the call_data comes from
the DtNmodifyVerifyCallback. It indicates that the action
that caused the callback to be called should be performed.
The action is not performed if doit is set to False.
The position argument is the new value of the DtNposition
resource as a result of the spin.
The value argument is the new XmString value displayed in
the Text widget as a result of the spin. The application
must copy this string if it is used beyond the scope of the
call_data structure.
The crossed_boundary argument is True when the spinbox
Page 6 (printed 9/3/04)
DtSpinBox(3) UNIX System V (1 August 1995) DtSpinBox(3)
cycles. This is the case when a DtNspinBoxChildType of
DtSTRING wraps from the first item to the last or the last
item to the first. In the case of the DtNspinBoxChildType
of DtNUMERIC, the boundary is crossed when the DtSpinBox
cycles from the maximum value to the minimum or vice versa.
SEE ALSO
DtCreateSpinButton(3X), DtSpinButtonAddItem(3X),
DtSpinButtonDeletePos(3X), DtSpinButtonSetItem(3X),
Composite(3X), Core(3X), XmManager(3X), XmText(3X),
XmTextField(3X), XtGetValues(3X), XtSetValues(3X)
Page 7 (printed 9/3/04)
