http://invisible-island.net/athena_widgets/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: \\
~Meta<Key>space: StartScroll(Forward) NotifyScroll(FullLength) \\n\\
Meta<Key>space: 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 *) &top;
        XtSetArg(args[0], XtNshown, *l_top);
}

XawPlus_________________________________________________________