(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: April 20, 2024 (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: April 20, 2024 (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: April 20, 2024 (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: April 20, 2024 (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: April 20, 2024 (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: April 20, 2024 (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: April 20, 2024 (3) Version Unknown To Mankind (3) Free Widget Foundation Free Widget Foundation stop_turning The stop_turning action removes the timer. - 8 - Formatted: April 20, 2024