(3) Version Unknown To Mankind (3)
Free Widget Foundation Free Widget Foundation
NAME
XfwfThumbWheel
DESCRIPTION
This is a very basic implementation of a valuator (scrolling) widget
that uses a thumbwheel as a metaphor. The thumbwheel is placed
vertically by default. The edge is turned towards the viewer and
sticking out. It can be turned up or down (or left-right) with the
mouse or with the up/down arrow keys.
With the mouse, there are two modes of operation: continuous and
discrete. Continuous movement is the result of pressing a mouse button
and dragging the mouse up or down. This is best for large, sweeping
movements. The default arrangement causes the left mouse button to
make the largest movements, the middle button makes the wheel turn
about half as fast and the third mouse button turns the wheel at a
quarter speed.
Discrete movements are good for finer control. By clicking the mouse
just below or above the wheel, the wheel turns a fixed distance (the
step size) in that direction. Here again the middle and right buttons
make the wheel turn half or a quarter of the step.
When the mouse is kept pressed for longer than a certain interval, the
wheel is repeatedly stepped, until the mouse is released.
With the keyboard, only discrete steps are possible. The default
translations assign the normal step size to the up and down keys, and
the smaller steps to the same keys combined with with Shift and
Control.
The picture of a thumb wheel is not integral to the widget, although a
default picture is provided. The picture (or rather series of
pictures) is an Image resource. To archieve a realistic `turning'
effect, at least three slightly different pictures must be provided.
Public variables
center box; cBsss lB|lB|lB|lB l|l|l|l. XfwfThumbWheel
Name Class Type Default
XtNnumberOfPictures XtCNumberOfPictures int 0
XtNpictures XtCPictures ImageList NULL
XtNvertical XtCVertical Boolean True
XtNclickArea XtCClickArea Dimension 7
XtNminValue XtCMinValue int 0 XtNmaxValue XtCMaxValue int
100 XtNvalue XtCValue int 0 XtNstep XtCStep int 1
- 1 - Formatted: December 15, 2025
(3) Version Unknown To Mankind (3)
Free Widget Foundation Free Widget Foundation
XtNinitialDelay XtCInitialDelay int 500
XtNrepeatDelay XtCRepeatDelay int 50
XtNsensitivity XtCSensitivity int 2
XtNscrollCallback XtCScrollCallback Callback NULL
XtNscrollResponse XtCScrollResponse XtCallbackProc
scroll_response
XtNnumberOfPictures
The widget is formed by the images that represents the wheel. The
wheel includes areas where the mouse can be clicked for small,
discrete movements. The size of the image thus determines the
size of the widget. There can be any number of images, but for
realisticly looking movement at least three slightly different
pictures are needed. numberOfPictures gives the number of
imagess, pictures must be an array of at least that many images.
A default set of pictures is provided when the pictures array is
left undefined.
Note for application programmers: the array is not copied to
private memory, so the array must stay valid for as long as the
widget exists and changes to elements of the array have
unpredictable results.
In the current implementation, these resources cannot be set with
XtSetValues.
XtNpictures
XtNvertical
The wheel can be either horizontal or vertical. The default is
vertical. Note that the setting of vertical should correspond to
the set of pictures.
- 2 - Formatted: December 15, 2025
(3) Version Unknown To Mankind (3)
Free Widget Foundation Free Widget Foundation
XtNclickArea
A small area along the top and bottom (or left and right) of the
widget is reserved for clicking the mouse, in order to get
discrete movements. clickArea is the number of pixels to reserve
for this area.
XtNminValue
The wheel can be turned through a range of values (integers),
indicated by minValue and maxValue. By default they are 0 and
100. value is the current value, which must lie between the two
(inclusive). Note that minValue may be greater than maxValue,
but in that case step (see below) should be negative.
Note for programmers: the information that is passed to callback
function always contains a value between 0 and 1, regardless of
minValue and maxValue.
XtNmaxValue
XtNvalue
XtNstep
When the user clicks on the areas below or above the wheel
itself, or when the user drags the wheel with the mouse, the
wheel is turned in fixed increments (or fractions thereof, see
the translations). The default step size is 1.
- 3 - Formatted: December 15, 2025
(3) Version Unknown To Mankind (3)
Free Widget Foundation Free Widget Foundation
XtNinitialDelay
When the user presses and holds the mouse for longer than
initialDelay milliseconds in the areas above or below the wheel,
the wheel is turned repeatedly every repeatDelay milliseconds.
XtNrepeatDelay
XtNsensitivity
The sensitivity is the number of pixels the mouse has to move
before the wheel turns. A small value such as 3, 2 (the default)
or 1 is usually best.
XtNscrollCallback
When the wheel is turned, the ThumbWheel widget calls the
callback functions on the scrollCallback list. It does so with
every change, but the information in the call_data argument is
different depending on the event that caused the change. The
call_data argument is a pointer to an XfwfScrollInfo structure.
For a full explanation of this structure, refer to `SWIP', the
Scrolling Widgets Interface Policy. The field that are of
interest here are reason, flags and vpos.
The field reason can be either XfwfSDrag, XfwfSMove, XfwfSUp,
XfwfSDown, XfwfSLeft, or XfwfSRight. Callbacks with reason =
XfwfSDrag are repeatedly called when the user drags the wheel up
or down. An application may ignore them (to save time), because
at the end of the drag there will always be a callback with
reason = XfwfSMove. The reasons XfwfSUp and XfwfSDown (XfwfSLeft,
XfwfSRight) are used when the user clicks on the areas above or
below the wheel (repeatedly, if he holds the button down.)
In all cases, the flags field has the value XFWF_VPOS for a
vertical thumbwheel or XFWF_HPOS for a horizontal thumbwheel.
- 4 - Formatted: December 15, 2025
(3) Version Unknown To Mankind (3)
Free Widget Foundation Free Widget Foundation
The vpos (or hpos) field is a real number between 0 and 1. It
indicates what the ThumbWheel widget suggests as the new position
after the event. This value is computed by adding or subtracting
the step from the current value and dividing by the total range.
When the callback is called, the value resource has already been
updated, so applications may use the value resource directly
instead of the vpos or hpos field.
XtNscrollResponse
In the SWIP there is a provision for scrollee widgets (i.e., the
widgets that are controlled by the wheel widget) to call back to
the wheel with their reaction to the scroll request as given by
the scrollCallback above. The scrollResponse resource (which is
read-only!) holds a pointer to a method function inside the wheel
widget. Calling this function with an appropriate XfwfScrollInfo
structure has the effect of updating the wheel to the values
provided by the scrollee. For more information, see the SWIP.
center box; cBsss lB|lB|lB|lB l|l|l|l. Core
Name Class Type Default XtNx XtCX Position 0
XtNy XtCY Position 0 XtNwidth XtCWidth Dimension 0
XtNheight XtCHeight Dimension 0
borderWidth XtCBorderWidth Dimension 0
XtNcolormap XtCColormap Colormap NULL
XtNdepth XtCDepth Int 0
destroyCallback XtCDestroyCallback XTCallbackList NULL
XtNsensitive XtCSensitive Boolean True
XtNtm XtCTm XTTMRec NULL
ancestorSensitive XtCAncestorSensitive Boolean False
accelerators XtCAccelerators XTTranslations NULL
borderColor XtCBorderColor Pixel 0
borderPixmap XtCBorderPixmap Pixmap NULL
background XtCBackground Pixel 0
backgroundPixmap XtCBackgroundPixmap Pixmap NULL
mappedWhenManaged XtCMappedWhenManaged Boolean True
XtNscreen XtCScreen Screen * NULL
- 5 - Formatted: December 15, 2025
(3) Version Unknown To Mankind (3)
Free Widget Foundation Free Widget Foundation
Exports
The scroll.h file contains the definition of XfwfScrollInfo and some
other things. It is exported so that applications do not have to
import it.
incl
<Xfwf/scroll.h>
Translations
Presses of each of the three mouse buttons are translated to calls to
the turn action. The argument indicates how fast to turn as a
percentage of the step size. An omitted argument is equivalent to 100
percent.
<Btn1Down>: turn()
<Btn2Down>: turn(50)
<Btn3Down>: turn(25)
<BtnUp>: stop_turning()
None<Key>Up: up()
!Shift<Key>Up: up(50)
!Ctrl<Key>Up: up(25)
- 6 - Formatted: December 15, 2025
(3) Version Unknown To Mankind (3)
Free Widget Foundation Free Widget Foundation
None<Key>Down: down()
!Shift<Key>Down: down(50)
!Ctrl<Key>Down: down(25)
Actions
up The up action has an optional argument percentage. It subtracts
step*percentage from the value resource and changes the displayed
picture. The change in picture is not (yet) related to the change
in value.
down The down action adds step*percentage to the value resource.
The turn action looks at the position of the mouse and if it is
in the top or bottom (left or right, if horizontal) area of the
widget it turns the wheel in discrete, timed steps, as long as
the button remains pressed. If the mouse is elsewhere, the
position is remembered and while the mouse remains pressed, the
wheel is turned an amount proportional to the distance that the
mouse moves from its initial position.
The optional argument gives the percentage of the step that the
wheel is turned with every event.
turn
- 7 - Formatted: December 15, 2025
(3) Version Unknown To Mankind (3)
Free Widget Foundation Free Widget Foundation
stop_turning
The stop_turning action removes the timer.
- 8 - Formatted: December 15, 2025
