NAME
Scrollbar widget − widget to control scrolling of viewing area in another widget.
SYNOPSIS
Public Headers:<X11/StringDefs.h> <X11/Xaw/Scrollbar.h>
Private Header:<X11/Xaw/ScrollbarP.h>
Class Name:Scrollbar
Class Pointer:scrollbarWidgetClass
Instantiation:widget = XtCreateWidget(name, scrollbarWidgetClass, ...)
CLASS HIERARCHY
Core → Simple → Scrollbar
DESCRIPTION
The Scrollbar widget is a rectangular area that contains a slide region and a thumb (slide bar). A Scrollbar can be used alone, as a valuator, or within a composite widget (for example, a Viewport). A Scrollbar can be aligned either vertically or horizontally.
When a Scrollbar is created, it is drawn with the thumb in a contrasting color. The thumb is normally used to scroll client data and to give visual feedback on the percentage of the client data that is visible.
Each pointer button invokes a specific scrollbar action. That is, given either a vertical or horizontal alignment, the pointer button actions will scroll or return data as appropriate for that alignment. Pointer buttons 1 and 3 do not perform scrolling operations by default. Instead, they return the pixel position of the cursor on the scroll region. When pointer button 2 is clicked, the thumb moves to the current pointer position. When pointer button 2 is held down and the pointer is moved, the thumb follows the pointer.
The pointer cursor in the scroll region changes, depending on the current action. When no pointer button is pressed, the pointer cursor appears as an arrow that points in the direction(s) in which scrolling can occur. When pointer button 1 or 3 is pressed, the pointer cursor appears as a single-headed arrow that points in the logical direction that the client will move the data. When pointer button 2 is pressed, the pointer cursor appears as an arrow that points to the thumb.
While scrolling is in progress, the application receives notification from callback procedures. For both scrolling actions, the callback returns the Scrollbar widget ID, client_data, and the pixel position of the pointer when the button was released. For smooth scrolling, the callback routine returns the scroll bar widget, client_data, and the current relative position of the thumb. When the thumb is moved using pointer button 2, the callback procedure is invoked continuously. When either button 1 or button 3 is pressed, the callback procedure is invoked only when the button is released, and the client callback procedure is responsible for moving the thumb.
RESOURCES
When creating a Scrollbar widget instance, the following resources are retrieved from the argument list or from the resource database:
| Name (XtN...) | Type | Default | Description | |||
| XtNaccelerators | AcceleratorTable | NULL | List of event-to-action bindings to be executed by this widget, even though the event occurred in another widget. | |||
| XtNancestor− Sensitive |
Boolean | True | (D) Sensitivity state of the ancestors of this widget: a widget is insensitive if either it or any of its ancestors is insensitive. | |||
| XtNbackground | Pixel | XtDefault− Background |
Window background color. | |||
| XtNbackground− Pixmap |
Pixmap | XtUnspecified− Pixmap |
Window background pixmap. | |||
| XtNborderColor | Pixel | XtDefault− Foreground |
Window border color. | |||
| XtNborderPixmap | Pixmap | XtUnspecified− Pixmap |
Window border pixmap. | |||
| XtNborderWidth | Dimension | 1 | Width of button border. | |||
| XtNcolormap | Colormap | Parent’s colormap. | Colormap that this widget will use. | |||
| XtNdepth | int | Parent’s depth. | (C) Depth of this widget’s window. | |||
| XtNdestroy− Callback |
XtCallbackList | NULL | Callbacks for XtDestroyWidget. | |||
| XtNforeground | Pixel | XtDefault− Foreground |
Thumb color. | |||
| XtNheight | Dimension | See below. | (A) Height of scroll bar. | |||
| XtNjumpProc | XtCallbackList | NULL | Callback for thumb select. | |||
| XtNlength | Dimension | 1 | Major dimension (height of XtorientVertical). | |||
| XtNmappedWhen− Managed |
Boolean | TRUE | Whether XtMapWidget() is automatic. | |||
| XtNminimumThumb | Dimension | 7 | Smallest size, in pixels, to which the thumb can shrink. | |||
| XtNorientation | XtOrientation | XtorientVertical | Orientation (vertical or horizontal). | |||
| XtNscreen | Screen | Parent’s screen. | (R) Screen on which this widget is displayed. | |||
| XtNscrollDCursor | Cursor | XC_sb_down_arrow | Cursor for scrolling down. | |||
| XtNscrollHCursor | Cursor | XC_sb_h_double_ arrow |
Idle horizontal cursor. | |||
| XtNscrollLCursor | Cursor | XC_sb_left_arrow | Cursor for scrolling left. | |||
| XtNscrollProc | XtCallbackList | NULL | Callback for the slide region. | |||
| XtNscrollRCursor | Cursor | XC_sb_right_arrow | Cursor for scrolling right. | |||
| XtNscrollUCursor | Cursor | XC_sb_up_arrow | Cursor for scrolling up. | |||
| XtNscrollVCursor | Cursor | XC_sb_v_arrow_ | Idle vertical cursor. | |||
| XtNsensitive | Boolean | TRUE | Whether widget receives input. | |||
| XtNshown | float | 0.0 | Percentage the thumb covers. | |||
| XtNthickness | Dimension | 14 | Minor dimension (height if XtorientHorizontal). | |||
| XtNthumb | Bitmap | Gray pixmap. | Thumb pixmap. | |||
| XtNtopOfThumb | float | 0.0 | Position on scroll bar. | |||
| XtNtranslations | Translation− Table |
See below. | Event-to-action translations. | |||
| XtNwidth | Dimension | Depends on orientation. | (A) Width of scroll bar. | |||
| XtNx | Position | NULL | x coordinate in pixels. | |||
| XtNy | Position | NULL | y coordinate in pixels. | |||
The new resource defined by this widget are:
XtNforeground
A pixel value which indexes the widget’s colormap to derive the color used to draw the thumb.
XtNjumpProc
All functions on this callback list are called when the NotifyThumb action is invoked. See the Scrollbar Actions section for details.
XtNminimumThumb
The smallest size, in pixels, to which the thumb can shrink.
XtNorientation
The orientation is the direction that the thumb will be allowed to move. This value can be either XtorientVertical or XtorientHorizontal.
scrollProc
All functions on this callback list may be called when the NotifyScroll action is invoked.
shownThis is the size of the thumb, expressed as a percentage (0.0 - 1.0) of the length of the scrollbar.
thumbThis pixmap is used to tile (or stipple) the thumb of the scrollbar. If no tiling is desired, then set this resource to None. This resource will accept either a bitmap or a pixmap that is the same depth as the window. The resource converter for this resource constructs bitmaps from the contents of files.
topOfThumb
The location of the top of the thumb, as a percentage (0.0 - 1.0) of the length of the scrollbar. This resource was called top in previous versions of the Athena widget set. The name collided with the a Form widget constraint resource, and had to be changed.
You can set the dimensions of the Scrollbar two ways. As for all widgets, you can use the XtNwidth and XtNheight resources. In addition, you can use an alternative method that is independent of the vertical or horizontal orientation:
XtNlength
Specifies the height for a vertical Scrollbar and the width for a horizontal Scrollbar.
XtNthickness
Specifies the width for a vertical Scrollbar and the height for a horizontal Scrollbar.
The Scrollbar has six cursor resources. The class for all cursor resources is XtCCursor.
scrollDCursor
This cursor is used when scrolling backward in a vertical scrollbar.
scrollHCursor
This cursor is used when a horizontal scrollbar is inactive.
scrollLCursor
This cursor is used when scrolling forward in a horizontal scrollbar.
scrollRCursor
This cursor is used when scrolling backward in a horizontal scrollbar, or when thumbing a vertical scrollbar.
scrollUCursor
This cursor is used when scrolling forward in a vertical scrollbar, or when thumbing a horizontal scrollbar.
scrollVCursor
This cursor is used when a vertical scrollbar is inactive.
TRANSLATIONS AND ACTIONS
The actions supported by the Scrollbar widget are:
StartScroll(value)
The possible values are Forward, Backward, or Continuous. This must be the first action to begin a new movement.
NotifyScroll(value)
The possible values are Proportional or FullLength. If the argument to StartScroll was Forward or Backward, NotifyScroll executes the XtNscrollProc callbacks and passes either the position of the pointer if its argument is Proportional or the full length of the scroll bar if its argument is FullLength. If the argument to StartScroll was Continuous, NotifyScroll returns without executing any callbacks.
EndScroll()This must be the last action after a movement is complete.
MoveThumb()Repositions the scroll bar thumb to the current pointer location.
NotifyThumb()
Calls the XtNjumpProc callbacks and passes the relative position of the pointer as a percentage of the scroll bar length.
The default bindings for Scrollbar are: <Btn1Down>:StartScroll(Forward) <Btn2Down>: StartScroll(Continuous) MoveThumb() NotifyThumb() <Btn3Down>: StartScroll(Backward) <Btn2Motion>: MoveThumb() NotifyThumb() <BtnUp>: NotifyScroll(Proportional) EndScroll() Examples of additional bindings a user might wish to specify in a resource file are:
∗Scrollbar.Translations: \
~Meta<KeyPress>space:StartScroll(Forward) NotifyScroll(FullLength) \
Meta<KeyPress>space:StartScroll(Backward) NotifyScroll(FullLength) \ EndScroll()
CALLBACK FUNCTIONS
•The XtNscrollProc callback is used for incremental scrolling and is called by the NotifyScroll action. XtNscrollProc looks like this: void ScrollProc(scrollbar, client_data, position)
Widget scrollbar;
XtPointer client_data;
XtPointer position; /∗ int ∗/ where:
scrollbarSpecifies the ID of the Scrollbar.
client_data
Specifies the client data.
positionReturns the pixel position of the thumb in integer form.
position is a signed quantity and should be cast to an int when used. Using the default button bindings, button 1 returns a positive value and button 3 returns a negative value. In both cases, the magnitude of the value is the distance of the pointer in pixels from the top (or left) of the Scrollbar. The value will never be greater than the length of the Scrollbar.
•The XtNjumpProc callback is used for jump scrolling and is called by the NotifyThumb action. The XtNjumpProc callback procedure looks like this: void JumpProc(scrollbar, client_data, percent)
Widget scrollbar;
XtPointer client_data;
XtPointer percent_ptr; /∗ float∗ ∗/ where:
scrollbarSpecifies the ID of the scroll bar window.
client_data
Specifies the client data.
percent_ptr
Specifies the floating point position of the thumb (0.0 − 1.0).
The XtNjumpProc callback is used to implement smooth scrolling and is called by the NotifyThumb action. percent_ptr must be cast to a pointer to float before use: float percent = ∗(float∗)percent_ptr; With the default button bindings, button 2 moves the thumb interactively, and the XtNjumpProc is called on each new position of the pointer, while the pointer button remains down. The value specified by percent_ptr is the current location of the thumb (from the top or left of the Scrollbar) expressed as a percentage of the length of the Scrollbar. An older interface used XtNthumbProc and passed the percentage by value rather than by reference. This interface is not portable across machine architectures but is still supported as of R5 for those (nonportable) applications that used it.
•To set the position and length of a Scrollbar thumb, use XawScrollbarSetThumb(): void XawScrollbarSetThumb(w, top, shown)
Widget w;
float top;
float shown; where:
wSpecifies the Scrollbar widget ID.
topSpecifies the position of the top of the thumb as a fraction of the length of the Scrollbar.
shownSpecifies the length of the thumb as a fraction of the total length of the Scrollbar.
XawScrollbarThumb moves the visible thumb to position (0.0 − 1.0) and length (0.0 − 1.0). Either top or shown can be specified as −1.0, in which case the current value is left unchanged. Values greater than 1.0 are truncated to 1.0. If called from XtNjumpProc, XawScrollbarSetThumb() has no effect.
SETTING FLOAT RESOURCES
The XtNshown and XtNtopOfThumb resources are of type float. These resources can be difficult to get into an argument list. The reason is that C performs an automatic cast of the float value to an integer value, usually truncating the important information. The following code fragment is one portable method of getting a float into an argument list. top = 0.5; if (sizeof(float) > sizeof(XtArgVal)) { /∗ ∗ If a float is larger than an XtArgVal then pass this ∗ resource value by reference. ∗/ XtSetArg(args[0], XtNshown, &top); } else { /∗ ∗ Convince C not to perform an automatic conversion, which ∗ would truncate 0.5 to 0. ∗/ XtArgVal ∗ l_top = (XtArgVal ∗) ⊤ XtSetArg(args[0], XtNshown, ∗l_top); }
SEE ALSO
Viewport.