Slider(3W)
NAME
Slider − slider widget
SYNOPSIS
#include <Xol/OpenLook.h>
#include <Xol/Slider.h>
. . .
ANCESTRY
Core-Primitive-Slider
DESCRIPTION
Components
The Slider widget enables the user to graphically set a numeric value, as shown in
Figure 1 Horizontal Slider
A Slider consists of the following elements:
• top (left) anchor
• bottom (right) anchor
• drag box
• bar (typically)
• shaded bar (typically)
• current value (not visible)
• minimum value (not visible)
• maximum value (not visible)
The current value is the numeric value a user attempts to change with the Slider widget.
Drag Box Motion
As visual feedback to the user, the drag box moves up or down (or left or right) along the bar as the current value changes.
Figure 2 Vertical Slider
Dragging SELECT
The user can change the current value by dragging the drag box with SELECT. The pressing of SELECT must start with the pointer in the drag box, but the drag box (and the current value) track the pointer motion regardless of where it goes while SELECT is pressed. This means it is not possible for the user to change the current value by first pressing SELECT outside the drag box and then moving the pointer into it. Only the component of the pointer motion parallel to the Bar is tracked, and the motion of the drag box (and change in the current value) are limited by the length of the Bar.
Clicking SELECT
Clicking SELECT above the drag box for a vertical slider, or to the right for a horizontal slider, increases the current value by an application-specified amount, moves the drag box to correspond to the new current value, and moves the pointer to keep it on the drag box.
Clicking SELECT to the other side of the drag box decreases the value by the same amount and moves the drag box and pointer accordingly.
Pressing SELECT repeats this action.
Moving Drag Box to Limits
Clicking SELECT on one of the bottom/left or top/right anchors causes the current value to take on the minimum value or maximum value, respectively, and moves the drag box to the limit in the direction of the Anchor. If the drag box is already at the limit, nothing happens.
Clicking SELECT on an anchor highlights the anchor while the current value is changed.
Application Notification
The application finds out about a change in the current value on the release of SELECT for either the drag or click. It is responsible for providing any feedback to the end user deemed appropriate, such as updating the current value in a text field.
Coloration
When the Slider widget receives the input focus through keyboard traversal, the background color of the widget changes to the input focus color, found in the resource XtNinputFocusColor. If the user traverses out of the Slider widget, the background of the widget shall revert to its original background color.
EXCEPTION:
If the input focus color is the same as either the foreground or background color, then the widget shows input focus by switching the background and foreground colors.
of the Slider widget.
Figure 3 Slider Coloration
Keyboard Traversal
The Slider’s default value of the XtNtraversalOn resource is TRUE.
The user can operate the Slider by using the keyboard to move the Drag Box and access the Anchors. The following keys manipulate the Current Value:
—SCROLLUP and SCROLLRIGHT increase the Current Value by an application-specified amount, and move the Drag Box to correspond to the new Current Value.
—SCROLLDOWN and SCROLLLEFT decrease the Current Value by an application-specified amount, and move the Drag Box to correspond to the new Current Value.
—SCROLLTOP and SCROLLRIGHTEDGE cause the Current Value to take on the Maximum Value, and move the Drag Box to a vertical slider’s top anchor or a horizontal slider’s right anchor. The anchor is briefly highlighted while the Current Value is changed and the Drag Box is moved.
—SCROLLBOTTOM and SCROLLLEFTEDGE cause the Current Value to take on the Minimum Value, and move the Drag Box to a vertical slider’s bottom anchor or a horizontal slider’s left anchor. The anchor is briefly highlighted while the Current Value is changed and the Drag Box is moved.
Vertical Slider Activation Types
Activation Type Expected Results
OL_SCROLLUP Drag Box moves up one Unit
OL_SCROLLDOWN Drag Box moves down one Unit
OL_SCROLLTOP Drag Box moves to top anchor
OL_SCROLLBOTTOM Drag Box moves to bottom anchor
Horizontal Slider Activation Types
Activation Type Expected Results
OL_SCROLLRIGHT Drag Box moves right one Unit
OL_SCROLLLEFT Drag Box moves left one Unit
OL_SCROLLRIGHTEDGE Drag Box moves to right anchor
OL_SCROLLLEFTEDGE Drag Box moves to left anchor
The Slider widget responds to the following keyboard navigation keys:
—NEXT_FIELD , MOVEDOWN , and MOVERIGHT move to the next traversable widget in the window
—PREV_FIELD , MOVEUP , and MOVELEFT move to the previous traversable widget in the window
—NEXTWINDOW moves to the next window in the application
—PREVWINDOW moves to the previous window in the application
—NEXTAPP moves to the first window in the next application
—PREVAPP moves to the first window in the previous application
Keyboard Mnemonic Display
The Slider does not display the mnemonic accelerator. If the Slider is the child of a Caption widget, the Caption widget will display the mnemonic as part of the label.
Keyboard Accelerators Display
The Slider does not respond to a keyboard accelerator because the results of clicking the SELECT button on a Slider depends on the pointer position. So, the Slider does not display a keyboard accelerator.
RESOURCES
Table 1 Slider Resource Summary
Name Type Default Access
XtNaccelerator- String NULL SGI
XtNacceleratorText- String Dynamic SGI
XtNancestorSensitive- Boolean TRUE G
XtNbackground- Pixel XtDefaultBackground SGI
XtNbackgroundPixmap- Pixmap (none) SGI
XtNconsumeEvent- XtCallbackList NULL SGI
XtNdestroyCallback- XtCallbackList NULL SI
XtNdragCBType OlDefine OL_CONTINUOUS SGI
XtNendBoxes Boolean TRUE SGI
XtNfont FontStruct∗ (OPEN LOOK default) SGI
XtNfontColor Pixel XtDefaultForeground SGI
XtNforeground- Pixel XtDefaultForeground SGI
XtNgranularity int 1 SGI
XtNheight- Dimension (calculated) SGI
XtNinitialDelay int 500 SGI
XtNinputFocusColor- Pixel Black SGI
XtNmappedWhenManaged- Boolean TRUE SGI
XtNminLabel String NULL SGI
XtNmaxLabel String NULL SGI
XtNmnemonic- unsigned char NULL SGI
XtNorientation OlDefine OL_VERTICAL GI
XtNpointerWarping Boolean FALSE SGI
XtNrecomputeSize Boolean FALSE SGI
XtNreferenceName- String NULL SGI
XtNreferenceWidget- Widget NULL SGI
XtNrepeatRate int 100 SGI
XtNscale int 12 SGI
XtNuseSetValCallback Boolean FALSE SGI
XtNsensitive- Boolean TRUE GI∗
XtNsliderMax int 100 SGI
XtNsliderMin int 0 SGI
XtNsliderMoved XtCallbackList NULL SI
XtNsliderValue int 0 SGI
XtNspan Dimension OL_IGNORE SGI
XtNstopPosition OlDefine OL_ALL SGI
XtNticks int 0 SGI
XtNtickUnit OlDefine OL_NONE SGI
XtNtraversalOn- Boolean TRUE SGI
XtNuserData- XtPointer NULL SGI
XtNwidth- Dimension (calculated) SGI
XtNx- Position 0 SGI
XtNy- Position 0 SGI
Access: S = XtSetValues G = XtGetValues
I = init time O = other access
† see resources(3W)
XtNdragCBType
class:XtCdragCBTypetype:OlDefinedefault:OL_CONTINUOUSOL_CONTINUOUS’u’access:SGISGI’u’
Action: determines the frequency of issuing XtNsliderMoved callbacks during a drag operation.
Values: OL_CONTINUOUS/continuous
OL_GRANULARITY/granularity
OL_RELEASE/release
If set to OL_CONTINUOUS , callbacks will be issued continuously (as in OLIT 2.0). If set to OL_GRANULARITY , callbacks will be issued only when the drag box crosses any granularity positions. If set to OL_RELEASE , callback will be issued only once when the SELECT button is released.
XtNendBoxes
class:XtCendBoxestype:Booleandefault:TRUETRUE’u’access:SGISGI’u’
Action: selects the display of the end boxes.
XtNfont
class:XtCFonttype:XFontStruct∗default:(OPEN LOOK font)(OPEN LOOK font)’u’access:SISI’u’
Action: specifies the font used to draw the labels.
Values: defaults to the OPENLOOK default font.
XtNfontColor
class:XtCfontColortype:Pixeldefault:foregroundforeground’u’access:SGISGI’u’
Action: specifies the color used to draw the labels.
Values: defaults to the foreground color of the slider widget.
XtNforeground
class:XtCForegroundtype:Pixeldefault:XtDefaultForegroundXtDefaultForeground’u’access:SGISGI’u’
Action: defines the foreground color for the widget.
XtNgranularity
class:XtCGranularitytype:intdefault:11’u’access:SGISGI’u’
Action: determines how much clicking SELECT changes current value.
Values: 1 ≤ XtNgranularity ≤ (XtNsliderMax - XtNsliderMin)
Clicking SELECT on the bar or shaded bar attempts to change the current value by the amount given in this resource. Dragging the drag box with SELECT changes the current value by this amount before the XtNsliderMoved callbacks are issued.
XtNinitialDelay
class:XtCInitialDelaytype:intdefault:500500’u’access:SGISGI’u’
Action: gives the time, in milliseconds, before the first action occurs when SELECT is pressed on the bar or shaded bar.
Values: 0 < XtNinitialDelay
Note: millisecond timing precision may not be possible for all implementations, so the value may be rounded up to the nearest available unit by the toolkit.
XtNmaxLabel
class:XtCLabeltype:Stringdefault:NULLNULL’u’access:SGISGI’u’
This is the label to be placed next to the maximum value position. For a vertical slider, the label is placed to the right of the minimum value position. If there is not enough space for the entire label and XtNrecomputeSize is FALSE, the label will be truncated from the end. If there is not enough space for the entire label and XtNrecomputeSize is TRUE, then the widget will request more space to show the entire label.
For a horizontal slider, the label is placed centered and below the maximum value position. If there is not enough room to center the label and XtNrecomputeSize is set to FALSE, the end of the label will be aligned with the left anchor. If this label collides with the min label, some part of the labels will overlap. If there is not enough room to center the label and XtNrecomputeSize is set to TRUE, the widget will request more space to center the label below the maximum value position.
XtNminLabel
class:XtCLabeltype:Stringdefault:NULLNULL’u’access:SGISGI’u’
This is the label to be placed next to the minimum value position. For a vertical slider, the label is placed to the right of the minimum value position. If there is not enough space for the entire label and XtNrecomputeSize is FALSE, the label will be truncated from the end. If there is not enough space for the entire label and XtNrecomputeSize is TRUE, then the widget will request more space to show the entire label.
For a horizontal slider, the label is placed centered and below the minimum value position. If there is not enough room to center the label and XtNrecomputeSize is set to FALSE, the beginning of the label will be aligned with the left anchor and is drawn to the right. If this label collides with the max label, some part of the labels will overlap. If there is not enough room to center the label and XtNrecomputeSize is set to TRUE, the widget will request more space to center the label below the minimum value position.
XtNorientation
class:XtCOrientationtype:OlDefinedefault:OL_VERTICALOL_VERTICAL’u’access:II’u’
Action: defines the direction for the visual presentation of the widget.
Values: ,OL_HORIZONTAL/horizontal"" OL_VERTICAL/vertical""
XtNpointerWarping
class:XtCPointerWarpingtype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’
Action: Specifies whether pointer will move along with the drag box when SELECT is pressed on the bar. Values: TRUE – the pointer moves with the drag box. FALSE – the pointer doesn’t move with the drag box.
XtNrecomputeSize
class:XtCRecomputeSizetype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’
This resource, if set to TRUE, allows the slider widget to resize itself whenever needed, to compensate for the space needed to show the tick marks and the labels. The slider widget uses the XtNspan, the sizes of the labels, and XtNtickUnit to determine the preferred size.
XtNrepeatRate
class:XtCRepeatRatetype:intdefault:100100’u’access:SGISGI’u’
Action: gives the time, in milliseconds, between repeated actions when SELECT is pressed on the bar or shaded bar.
Values: 0 < XtNrepeatRate
Note: millisecond timing precision may not be possible for all implementations, so the value may be rounded up to the nearest available unit by the toolkit.
XtNscale
class:XtCScaletype:Intdefault:1212’u’access:SGISGI’u’
Action: determines size of graphical elements, in points (1/72 inch), not pixels
Values: 0 < XtNscale
This resource sets the size of graphical elements (widgets) in a manner similar to other scale resources. Only sizes 10, 12, 14, and 19 are presently supported. If this resource is set to any other value, one of these is substituted instead.
XtNsliderMax
class:XtCSliderMaxtype:intdefault:100100’u’access:SGISGI’u’
XtNsliderMin
class:XtCSliderMaxtype:intdefault:00’u’access:SGISGI’u’
Action: give the range of values tracked by the Slider widget.
Values: XtNsliderMin < XtNsliderMax
Mathematically, the range is open on the right; that is, the range is the following subset of the set of integers: XtNsliderMin ≤ range ≤ XtNsliderMax.
This is independent of the drag box displayed in the Slider widget. The Slider widget is responsible for taking into account the size of the drag box when relating the physical range of movement to the range of values.
Figure 4 Drag Box Range of Movement
XtNsliderMoved
class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:SISI’u’
Action: defines the callback list used when the Slider widget is manipulated.
The call_data parameter is a pointer to a structure of the form;
typedef struct OlSliderVerify {
int new_location;
Boolean more_cb_pending;
} OlSliderVerify;
new_location provides the new slider location. more_cb_pending specifies if there are more callbacks pending. An XtGetValue() inside the callback will return the previous value.
XtNsliderValue
class:XtCSliderValuetype:intdefault:00’u’access:SGISGI’u’
Action: gives the current position of the drag box.
Values: XtNsliderMin ≤ XtNsliderValue ≤ XtNsliderMax
The position lies in the range [ XtNsliderMin , XtNsliderMax ]. The Slider widget keeps this resource up to date; however, an application can also get the current value through the XtNsliderMoved callbacks.
XtNspan
class:XtCSpantype:Dimensiondefault:OL_IGNOREOL_IGNORE’u’access:SGISGI’u’
If XtNrecomputeSize is set to TRUE, then XtNspan should be set to reflect the preferred length of the slider, not counting the space needed for the labels. The slider widget uses the span value, the sizes of the labels, and XtNtickUnit to determine the preferred size.
XtNstopPosition
class:XtCstopPositiontype:OlDefinedefault:OL_ALLOL_ALL’u’access:SGISGI’u’
Action: determines the behavior of the drag box at the end of a drag operation.
Values: OL_ALL/"all"
OL_TICKMARK/"tickmark"
OL_GRANULARITY/"granularity"
If set to OL_ALL , upon the release of the SELECT button in a drag operation, the drag box will be positioned where it stops. If set to OL_TICKMARK , the drag box will snap to the nearest tickmark position. If set to OL_GRANULARITY , the drag box will snap to the nearest granularity position.
XtNticks
class:XtCTickstype:intdefault:00’u’access:SGISGI’u’
Action: the interval between tick marks.
Values: The unit of the interval value is determined by XtNtickUnit.
XtNtickUnit
class:XtCTickUnittype:Oldefinedefault:OL_NONEOL_NONE’u’access:SGISGI’u’
Values: OL_NONE/"none"
OL_SLIDERVALUE/"slidervalue"
OL_PERCENT/"percent"
This resource can have one of the values: OL_NONE , OL_SLIDERVALUE , or OL_PERCENT. If it is OL_NONE , then no tick marks will be displayed and XtNticks is ignored. If it is OL_PERCENT , then XtNticks is interpreted as the percent of the slider value range. If it is OL_SLIDERVALUE , the XtNticks is interpreted as the same unit as slider value.
XtNuseSetValCallback
class:XtCUseSetValCallbacktype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’
Action: Controls whether XtNsliderMoved callback is called when slider is manipulated when slider is manipulated by doing an XtSetValues
Values: TRUE, FALSE
Version 3.0.1 — Last change: June 92