Description:

The ThumbWheel Widget is similar to the scaler widget, but uses a thumbwheel instead of a slider. It has an optional label and an optional textfield to display the actual value. The textfield may be used to change the value, if enabled. Two arrowbuttons can be used to increment or decrement the value, these buttons have a timeout function for incrementing. A home button will reset the value to some fixed number. The primary use will be to rotate the wheel with the mouse. Left button pressed inside the widget and movig the cursor will rotate the wheel and change the value.

Two examples showing the possible orientations:

Resources:

The widget includes the »core« , "Composite", "Constraint" and "XmManager" class with all resources. To describe the features of the ThumbWheel widget, it has several resources for it's own. The following table contains the resource-name, the resource-class and the accesstype. Defining the resource in a general resourcefile file like .Xdefaults, means, leave out the prefix XwN or XwC. The access type defines, if the resource may be set at creation »C«, using XtSetValues »S«, only at creation using XtSetArg »CS« and being read using XtGetValues »G«.

Name	Class	Type	Default	Access
XmNdestroyCallback		XtCallbackList	NULL	S C
XmNeditable	XmCeditable	Bool	FALSE	C S G
XmNfontList	XmCfontList	FontList	inherit	C S
XmNminimum	XmCminimum	int	0	C S G
XmNmaximum	XmCmaximum	int	100	C S G
XwNlowInfinite	XwCLowInfinite	Bool	FALSE	C S
XwNhighInfinite	XwCHighInfinite	Bool	FALSE	C S
XmNvalue	XmCvalue	int	0	C S G
XmNshadowThickness	XmCShadowThickness	Dimension	2	C S
XwNhomeValue	XwCHomeValue	int	0	C S G
XmNshowValue	XmCShowValue	Boolean	TRUE	C S
XwNshowHomeButton	XwCshowHomeButton	Boolean	TRUE	C S
XmNorientation	XmCOrientation	char	XmVERTICAL	CS G
XwNrightValue	XwNCRightValue	Bool	FALSE	CS
XmNmaxLength	XmCMaxLength	int	0	C S
XmNtitleString	XmCTitleString	XmString	NULL	C S
XmNshowArrows	XmCShowArrows	Boolean	TRUE	C S
XmNdecimalPoints	XmCdecimalPoints	int	0	C S G
XmNincrement	XmCincrement	int	1	C S G
XmNvalueChangedCallback	XmCCallback	XtCallbackList	NULL	S C
XmNactivateCallback	XmCCallback	XtCallbackList	NULL	S C

Detailed Description of special Resources

Callbacks:

Possible callbacks are:

XwNdestroyCallback , XmNvalueChangedCallback, XmNactivateCallback.
Of course the most important is the value changed callback. It is called at any value change, so the user may react directly on the change. (p.e. Move a displayed item). Activate is used to get the last value back, but will be hooked only on the value-displaying textfield, if this is editable. The delivered callback data structure is the same for valuechanged and activate callbacks:

typedef struct{

int reason;

XEvent *event;

int value;

} XwThumbWheelCallbackStruct;

XmNshowArrows, XwNshowHomeButton

These resources influence the display and behaviour. If set to TRUE, they add buttons to the wheel, showArrows will add two arrow-buttons at each end of the widget. Pressing an arrow will increment (or decrement) the value, rotating the wheel. After a short time, while button is pressed, autoincrement will start. The home-button resets the value to a defined number.

XmNtitleString

The given XmString is displayed as Label centered above the wheel.

XmNshowValue

creates a textfield centered below the wheel. The initial size of the textfield fits to the minimum/maximum values. In case of editable set to TRUE, it may act as input,

XmNshadowThickness

This resource is inherited, but may be set to change the display. The shadow is plotted for the wheel only, not for label and value-text-field.

XmNfontList

This resource is used for the embedded textwidget, (see XmText) and the label

XmNeditable

If True, allows the user to type the new value directly into the textfield.

XmNminimum, XmNmaximum

These given limits are checked. The value won't be set beyond the limits. No value changed will occur if out of limits. If minimum is equal to maximum, this indicates infinite incrementing.

XmNdecimalPoints

Like the Scale-widget, tis effects only the textfield (display or editing). If decimal points are set, the value is displayed in float notation. The user must take care about the precision when using the value in a callback or retriving it from the widget.

XmNincrement

Incrementing or decrementing can be set to any value, even to a negative number, which will revert the reactions.

XmNvalue

Setting a new (or the initial value). For getting and setting the actual value, convenience functions are available.

XwNrightValue

If XmNorientation is set to XmHORIZONTAL, and XmNshowValue is TRUE, the value displaying text field ist created right of the wheel, instead of being below the wheel.

XmNmaxLength

This resources is normally set to zero, which means, the size is calculated from the minimum an maximum value. Sometimes, together with XwNrightValue, several Thumbwheels should have exactly the same size. Therefore, XmNmaxLength can be set to the maximum number of expected digits, resulting in a fixed size now.

XwNlowInfinite XwNhighInfinite

Normally, infinite is defined via minimum = maximum. But in special cases it might be useful to define only one directions as infinite, so these resources may set either the lower or upper bound to infinite.

Convenience Functions:

Name: XwCreateThumbWheel
Header file: »ThumbWheel.h«

Widget XwCreateThumbWheel Widget, char *, ArgList, Cardinal);

XwCreateThumbWheel creates a widgetinstance of class xwThumbWheelWidgetClass and returns the widget-id. The argumentlist follows the general standard.

Name: XwThumbWheelSetValue

Header file: »ThumbWheel.h«

Boolean XgThumbWheelSetValue(Widget w, int value);

Name: XwThumbWheelGetValue

Header file: »ThumbWheel.h«

int XwThumbWheelGetValue(Widget w);