Application header file <X11/Xaw/Scrollbar.h> Class header file <X11/Xaw/ScrollbarP.h> Class scrollbarWidgetClass Class Name Scrollbar Superclass Simple A Scrollbar widget is a rectangle, called the ``canvas,'' on which another rectangle, the ``thumb,'' moves in one dimension, either vertically or horizontally. A Scrollbar can be used alone, as a value generator, or it can be used within a composite widget (for example, a Viewport). When a Scrollbar is used to move, or ``scroll,'' the contents of another widget, the size and the position of the thumb usually give feedback as to what portion of the other widget's contents are visible. Each pointer button invokes a specific action. Pointer buttons 1 and 3 do not move the thumb automatically. 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 cursor appears as a double-headed arrow that points in the direction that scrolling can occur. When pointer button 1 or 3 is pressed, the cursor appears as a single-headed arrow that points in the logical direction that the thumb will move. When pointer button 2 is pressed, the cursor appears as an arrow that points to the top or the left of the thumb. When the user scrolls, 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 scroll bar widget, the 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 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. When creating a Scrollbar widget instance, the following resources are retrieved from the argument list or from the resource database: Name Class Type Notes Default Value accelerators Accelerators AcceleratorTable NULL ancestorSensitive AncestorSensitive Boolean D True background Background Pixel XtDefaultBackground backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap borderColor BorderColor Pixel XtDefaultForeground borderPixmap Pixmap Pixmap XtUnspecifiedPixmap borderWidth BorderWidth Dimension 1 colormap Colormap Colormap parent's Colormap cursor Cursor Cursor None cursorName Cursor String NULL depth Depth int C parent's Depth destroyCallback Callback XtCallbackList NULL foreground Foreground Pixel XtDefaultForeground height Height Dimension A depends on orientation insensitiveBorder Insensitive Pixmap GreyPixmap international International Boolean C False jumpProc Callback XtCallbackList NULL length Length Dimension 1 mappedWhenManaged MappedWhenManaged Boolean True minimumThumb MinimumThumb Dimension 7 orientation Orientation Orientation XtorientVertical (vertical) pointerColor Foreground Pixel XtDefaultForeground pointerColorBackground Background Pixel XtDefaultBackground screen Screen Screen R parent's Screen scrollDCursor Cursor Cursor XC_sb_down_arrow scrollHCursor Cursor Cursor XC_sb_h_double_arrow scrollLCursor Cursor Cursor XC_sb_left_arrow scrollProc Callback XtCallbackList NULL scrollRCursor Cursor Cursor XC_sb_right_arrow scrollUCursor Cursor Cursor XC_sb_up_arrow scrollVCursor Cursor Cursor XC_sb_v_arrow sensitive Sensitive Boolean True shown Shown Float 0.0 thickness Thickness Dimension 14 thumb Thumb Bitmap GreyPixmap thumbProc Callback XtCallbackList NULL topOfThumb TopOfThumb Float 0.0 translations Translations TranslationTable See below width Width Dimension A depends on orientation x Position Position 0 y Position Position 0 foreground A pixel value which indexes the widget's colormap to derive the color used to draw the thumb. 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. 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. scrollProc All functions on this callback list may be called when the NotifyScroll action is invoked. See the \fBScrollbar Actions\fP section for details. 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. 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. thumb This 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. (See Converting Bitmaps for details.) 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. 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 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<Key>space: StartScroll(Forward) NotifyScroll(FullLength) \\n\\ Meta<Key>space: StartScroll(Backward) NotifyScroll(FullLength) \\n\\ EndScroll(\|) 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 Widget scrollbar XtPointer client_data XtPointer position 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 Widget scrollbar XtPointer client_data XtPointer percent_ptr 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 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. To set the position and length of a Scrollbar thumb, use void XawScrollbarSetThumb 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. 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); }