The Scrollbar Widget
Author: Roland Krause 2002, roland_krause@freenet.de
Description: Documentation to XawPlus

### _________________________________________________________XawPlus

### The Scrollbar Widget

Application Header file Class Header file Class Class Name Superclass | <X11/XawPlus/Scrollbar.h> <X11/XawPlus/ScrollbarP.h> scrollbarWidgetClass Scrollbar Simple

The Scrollbar widget is a rectangular area containing a slide region, a thumb (also known as a slide bar) and two arrow keys. A Scrollbar can be used alone, as a value generator, or it can be used within a composite widget (for example, a Viewport). A Scrollbar can be oriented either vertically or horizontally.

When a Scrollbar is created, it is drawn with the thumb as a 3D styled bar and the arrow keys at the ends of the slide region. The thumb is normally used to scroll client data and to give visual feedback (through its length) on the percentage of the client data, that is visible.

Each pointer button invokes a specific action. By default clicking with the middle mouse button (poiter button 2) let the thumb jump to the current pointer position in the slide region. With pointer 1 or 3 (left or right mouse button) the user can step page by page up or down through the corresponding document. If the pointer button 1 or 3 is clicked onto the thumb, held down and the pointer is moved, the thumb follows the pointer.

While scrolling is in progress, the application receives notification through callback procedures. For both discrete scrolling actions, the callback returns the scrollbar widget, the client_data, and the pixel position of the pointer when the button was released. For continuous scrolling, the callback routine returns the scrollbar widget, the client data, and the current relative position of the thumb.

### Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the Scrollbar widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75. Since Release 2.0 of XawPlus the scrollbar is Motif styled. The implementation is derived from the scrollbar implementation of Xaw3d Release 1.4.

The resources foreground and thumb and all the cursor resources are not longer used.

### Resources

When creating a Scrollbar widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name | Class | Type | Default Value
OBJECT: |  |  |
destroyCallback | Callback | Pointer | NULL
RECTANGLE: |  |  |
borderWidth height sensitive width x y | BorderWidth Height Sensitive Width Position Position | Dimension Dimension Boolean Dimension Position Position | 0 12 True 12 0 0
CORE: |  |  |
border background mappedWhenManaged | BorderColor Background MappedWhenManaged | Pixel Pixel Boolean | XtDefaultForeground grey75 True
SIMPLE: |  |  |
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth | Cursor Cursor Foreground Background Insensitive International Background Background Width | Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension | None left_ptr XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
SCROLLBAR: |  |  |
accelerators ancestorSensitive jumpProc scrollProc thumbProc translations length minimumThumb thickness orientation shown topOfThumb | Accelerators AncestorSensitive Callback Callback Callback Translations Length MinimumThumb Thickness Orientation Shown TopOfThumb | AcceleratorTable Boolean XtCallbackList XtCallbackList XtCallbackList TranslationTable Dimension Dimension Dimension XtOrientation Float Float | NULL True NULL NULL NULL see above 1 12 16 XtorientVertical 0.0 0.0

jumpProc | All functions on this callback list are called when the NotifyThumb action is invoked. See the Scrollbar Actions section for details.
length | The height of a vertical scrollbar or the width of a horizontal scrollbar.
minimumThumb | The smallest size in pixels, to which the thumb can shrink.
orientation | 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. See the Scrollbar Actions section for details.
shown | This is the size of the thumb, expressed as a percentage (0.0 - 1.0) of the length of the scrollbar.
thickness | The width of a vertical scrollbar or the height of a horizontal scrollbar.
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.

### Scrollbar 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 scrollProc callbacks and passes either; the position of the pointer, if value is Proportional, or the full length of the scroll bar, if value 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 Scrollbar's thumb to the current pointer location.
NotifyThumb() | Calls the jumpProc callbacks and passes the relative position of the pointer as a percentage of the scroll bar length.

The default bindings for Scrollbar are:

> <Btn1Down> : <Btn2Down> : <Btn3Down> : <Btn1Motion> : <Btn2Motion> : <Btn3Motion> : <BtnUp> : | NotifyScroll() MoveThumb() NotifyThumb() NotifyScroll() HandleThumb() HandleThumb() MoveThumb() NotifyThumb() EndScroll()

Examples of additional bindings a user might wish to specify in a resource file are:

> *Scrollbar.Translations: \\
> ~Metaspace: StartScroll(Forward) NotifyScroll(FullLength) \\n\\
> Metaspace: StartScroll(Backward) NotifyScroll(FullLength) \\n\\
> EndScroll()

### Scrollbar Callbacks

There are two callback lists provided by the Scrollbar widget. The procedural interface for these functions is described here.

The calling interface to the scrollProc callback procedure is:

> void ScrollProc(scrollbar, client_data, position)
> Widget scrollbar;
> XtPointer client_data;
> XtPointer position; /* int */

> scrollbar | Specifies the Scrollbar widget.
> client_data | Specifies the client data.
> position | Specifies a pixel position in integer form.

The scrollProc callback is used for incremental scrolling and is called by the NotifyScroll action. The position argument 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 calling interface to the jumpProc callback procedure is:

> void JumpProc(scrollbar, client_data, percent)
> Widget scrollbar;
> XtPointer client_data;
> XtPointer percent_ptr; /* float* */

> scrollbar | Specifies the ID of the scroll bar widget.
> client_data | Specifies the client data.
> percent_ptr | Specifies the floating point position of the thumb (0.0, -1.0).

The jumpProc 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; i.e.

> float percent = *(float*)percent_ptr;

With the default button bindings, button 2 (the middle mouse button) moves the thumb interactively, and the jumpProc 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.

### Convenience Routines

To set the position and length of a Scrollbar thumb, use XawScrollbarSetThumb():

> void XawScrollbarSetThumb(w, top, shown)
> Widget w;
> float top;
> float shown;

> w | Specifies the Scrollbar widget.
> top | Specifies the position of the top of the thumb as a fraction of the length of the Scrollbar.
> shown | Specifies the length of the thumb as a fraction of the total length of the Scrollbar.

XawScrollbarThumb() moves the visible thumb to a new position (0.0, -1.0) and length (0.0, -1.0). Either the top or shown arguments 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 jumpProc, XawScrollbarSetThumb() has no effect.

### Setting Float Resources

The shown and topOfThumb 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);
>     }

### XawPlus_________________________________________________________