WIDGET CLASS NAME

Scrollbar

SYNOPSIS

#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <Scrollbar.h>

static Widget scrollbar, menupane, w;

Arg args[1];

scrollbar = XtCreateWidget(name, scrollbarWidgetClass, ...);

/∗use the following instruction to add a button to the scrollbar menu∗/

XtSetArg(args[0], XtNmenuPane, &menupane);
XtGetValues(scrollbar, args, 1)
w = XtCreateWidget(name, widget-class, menupane, ...);

DESCRIPTION

Scrollbar Components

Each full scrollbar has the following parts:

—Top (Left) Anchor

—Bottom (Right) Anchor

—Up (Left) Arrow

—Down (Right) Arrow

—Drag Area

—Elevator

—Cable

—Proportion Indicator

—Scrollbar Menu

—Page Indicator (optional)

A scrollbar consists of two Anchors, an Elevator, a Cable, a Proportion Indicator, a Menu, and optionally a Page Indicator.  The Anchors are located at both ends of the cable.  They are used to move the view to the corresponding extreme of the item or list of items being viewed.  The Elevator, which slides along the length of the cable, consists of the Up Arrow, Down Arrow, and a Drag Area in the middle for moving the view.  The arrow boxes are used to move the view in the direction of the arrow by one unit of granularity.  The Drag Area is used to move the view by tracking the position of the mouse pointer relative to the scrollbar.  The Proportion Indicator moves along with the Elevator to indicate the size of the view and its position relative to the entire item or list of items being viewed.  The optional Page Indicator located next to the Drag Area indicates the page number of the content being viewed.  The Page Indicator will be displayed only when the SELECT button is pressed in the Drag Area. 

  Figure 1 Horizontal Scroll Bar

  Figure 2 Vertical Scroll Bar

Because a scrollbar can be seen and used horizontally as well as vertically, the parts Top Anchor and Bottom Anchor have the aliases Left Anchor and Right Anchor, respectively. 

Each scrollbar is associated with a Content, as defined by the application.  The Content is composed of Units (e.g. lines of text) that are visible in a viewing area.  For a scrollbar to be useful, the Content typically has more Units than can fit in the viewing area.  Hence, "scrolling" the Content brings Units into view as other Units move out of view.  The amount of the Content that is visible at one time is called a pane in the descriptions below.  Abbreviated Scrollbar

The Scrollbar widget responds to a parent’s request to resize smaller by shortening the Cable (and Proportion Indicator) but leaving the other elements full-sized.  The Scrollbar widget will eliminate the Cable entirely, if necessary, to meet a resize request.  These abbreviated scrollbars are shown in the diagram Abbreviated Scroll Bars. 

  Figure 3 Abbreviated Scroll Bars

Elevator Motion

As visual feedback to the user, the Elevator moves up and down (or left and right) along the line of the Cable as the Content scrolls or changes panes.  The range of motion of the Elevator is not necessarily the full distance between the Anchors.  The application decides how far the Elevator can be moved by evaluating each attempt to move it. 

The user manipulates the scrollbar by pressing or clicking SELECT.  The action performed depends on the position of the pointer and whether the application is willing to scroll the Content.  Scrolling One Unit

Clicking SELECT on one of the Up, Down, Left, or Right Arrows moves the Elevator in the direction of the arrow, moves the pointer to stay on the Arrow, and changes the Content to move one Unit out of view and another Unit into view, such that the view scrolls in the opposite direction of the Elevator motion.  If the application cannot scroll this time, the Elevator and pointer do not move, the view does not change, and the Scrollbar widget makes the system beep. 

Pressing SELECT on an Arrow repeats the action described above. 

When SELECT is clicked or pressed, the Arrow highlights while the scrolling action takes place.  If SELECT is pressed, the highlighting stays until SELECT is released. 

When the Elevator has reached the end of a Cable, the Arrow in that direction is made inactive.  Scrolling Several Units

Dragging SELECT on the Drag Area moves the Elevator along the Cable, to track the component of the pointer motion parallel to the Cable.  The Content scrolls in the opposite direction, bringing one or more Units into view as other Units move out of view. 

If granularity is enforced and the Elevator is moved to a position that represents a non-integral number of Units, the closest integral number of Units is considered instead.  If granularity is not enforced, the Elevator is moved by the non-integral number of Units.  The XtNsliderMoved callback allows the application to enforce The XtNsliderMoved callback allows the application to enforce granularity. 

When the application reaches the limit that it can scroll, the view no longer changes and the Elevator stops moving. 

While dragging SELECT, the Drag Area highlights.  The pointer is constrained to stay within the Drag Area as the Elevator moves.  Scrolling to Limits

Clicking SELECT on one of the Top, Bottom, Left, or Right Anchors causes the view of the Content to change to the top-most, bottom-most, left-most, or right-most pane, respectively, and moves the Elevator to the limit in the direction of the Anchor.  If the Elevator is already at the limit, nothing happens. 

Clicking SELECT on an Anchor highlights the Anchor while the scrolling action takes place.  Scrolling a Pane of Units

Clicking SELECT on the Cable above/left-of or below/right-of the Elevator causes the view of the Content to change to the previous or next pane, respectively.  The pointer is moved along the direction of the Elevator travel to keep it off the Elevator.  If only a partial pane remains before the limit of the Content is reached, the effect is as if the user clicked SELECT on the corresponding Anchor.  If the application cannot move to another pane, the view does not change, the Elevator and pointer do not move, and the Scrollbar makes the system beep. 

Pressing SELECT on the Cable repeats the action described above. 

Elevator Approaching Limits

The application calibrates the scrollbar so that the position of the elevator on the scrollbar is in units useful to the application.  In general, these units will not be pixels or points.  If the scrollbar is close enough to an Anchor, the separation in application units may equate to zero pixels, because of the discrete nature of pixels.  Here, the elevator is kept away from the Anchor so that two points of the Cable length are visible.  The Elevator is placed at the limit of motion only when the user explicitly moves the elevator to an Anchor by clicking SELECT on the Anchor, or drags the Elevator until it reaches the limit.  Indicating View Proportion

The Proportion Indicator gives a gross measure of what part of the Content is in view.  Its size relative to the length of the Cable is the same as the size of the pane relative to the size of the Content.  However, the scrollbar widget does not maintain this relation but relies on the application to provide the length of the Proportion Indicator. 

The Proportion Indicator moves with the Elevator such that both reach the limits together: When the Content is scrolled to the beginning, the proportion indicator and the elevator align at the left or top end of the scrollbar, as in  the diagram Window with Two Sets of Scrollbars.  When the Content is scrolled to the end, the proportion indicator and the elevator align at the right or bottom end of the scrollbar, as in the diagram Elevator and Proportion Indicator at Left/Top Limits.  For intermediate positions, the Elevator is positioned proportionally between the ends of the Proportion Indicator.  Thus, as the Content is scrolled at a constant rate (e.g. by dragging SELECT), the Elevator creeps from one end of the Proportion Indicator to the other at a constant rate. 

  Figure 4 Window with Two Sets of Scrollbars

  Figure 5 Elevator and Proportion Indicator at Left/Top Limits

Scrollbar Menu

The Scrollbar Menu (not shown in the figures) pops up when the user presses MENU anywhere over the scrollbar widget.  The menu has three default choices depending on the scrollbar orientation. 

Here to Top

Here to LeftThis choice scrolls the Content so that the Unit next to the pointer is placed at the top or left of the viewing area. 

Top to Here

Left to HereThis choice scrolls the Content so that the Unit at the top or left of the viewing area is placed next to the pointer. 

PreviousThis choice scrolls the Content to restore the previous view.  The scrollbar widget remembers only the last two scroll positions, so repeated access to this choice alternates the Content between two views. 

An application can add choices to this menu, using the same technique for populating other menus (see MENU WIDGET(3W)).  The ID of the menu widget is available as a resource of the scroll bar. 
Scrollbar Coloration

the diagram Elevator and Proportion Indicator at Right/Bottom Limits illustrates the resources that affect the coloration of the Scrollbar widget. 

  Figure 6 Elevator and Proportion Indicator at Right/Bottom Limits

SUBSTRUCTURE

Scrollbar Menu component

Name: menu
Class: Menu

  Table 1 Scrollbar Application Resources Application Resources
             Name       Type      Default  Access
       ∗XtNcenter    Boolean         TRUE       I
         ∗XtNhPad  Dimension            4       I
       ∗XtNhSpace  Dimension            4       I
      ∗XtNmeasure        int            1       I XtNpushpinDefault    Boolean        FALSE       I
         XtNtitle     String  "Scrollbar"       I
         ∗XtNvPad  Dimension            4       I
       ∗XtNvSpace  Dimension            4       I ∗See the Menu and ControlArea widgets for the descriptions of these resources.

RESOURCES

  Table 2 Scrollbar Resource Set Scrollbar Resource Set\\∗(cO
                Name            Type       Default   Access XtNancestorSensitive         Boolean          TRUE       G∗
       XtNbackground           Pixel         White  SGI†
 XtNbackgroundPixmap          Pixmap        (none)  SGI†
      XtNcurrentPage             int             1     SGIT
            XtNdepth             int    (parent’s)       GI
  XtNdestroyCallback  XtCallbackList          NULL       SI
       XtNforeground           Pixel         Black      SGI
      XtNgranularity             int             1      SGI
           XtNheight       Dimension  (calculated)      SGI
     XtNinitialDelay             int           500      SGI XtNmappedWhenManaged         Boolean          TRUE      SGI
         XtNmenuPane          Widget        (none)        G
 XtNproportionLength             int    (variable)      SGI
       XtNrepeatRate             int           100      SGI
        XtNsensitive         Boolean          TRUE      GI∗
        XtNsliderMax             int           100      SGI
        XtNsliderMin             int             0      SGI
      XtNsliderMoved  XtCallbackList          NULL       SI
      XtNsliderValue             int             0      SGI
         XtNuserData       XtPointer          NULL      SGI
            XtNwidth       Dimension  (calculated)      SGI
                XtNx        Position             0      SGI
                XtNy        Position             0      SGI XtNbackground

Whenever this resource is changed, the Anchors, the Elevator, and the Proportion Indicator will be redisplayed with the new color.  XtNcurrentPage

This resource is typically not selectable.  However, there are two exceptions.  If XtNshowPage is set via SetValues(), exceptions.  If XtNshowPage is set via SetValues(), XtNcurrentPage should also be set in the same call.  If XtNcurrentPage should also be set in the same call.  If XtNshowPage is already set, and later XtNshowPage is already set, and later XtNsliderValue is changed via SetValues(), XtNsliderValue is changed via SetValues(), XtNcurrentPage should also be set in the same call.  XtNcurrentPage should also be set in the same call.  XtNforeground

This resource defines the foreground color for the widget.  Whenever this resource is changed, the entire scrollbar will be redisplayed with the new color for the Cables and anchors. See the note about the interaction of this resource with other color resources under the description of the XtNbackground resource in CORE(3W).  XtNgranularity

Range of Values:

1 ≤ XtNgranularity ≤ XtNsliderMax - XtNsliderMin

Clicking or pressing SELECT on an Up, Left, Down, or Right Arrow attempts to change the position of the Elevator by the distance given in this resource.  Normally, the drag operation does not honor granularity unless enforcement is set in the XtNsliderMoved callback procedure.  enforcement is set in the XtNsliderMoved callback procedure.  XtNinitialDelay

Range of Values:

0 < XtNinitialDelay

This resource gives the time, in milliseconds, before the first action occurs when SELECT is pressed on the Cables or Arrows.  Note that 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.  XtNmenuPane

This is the widget where scroll bar menu items can be attached; its value is set once the scrollbar is created.  Menu items can be added to this widget just as they are to a menu pane for a Menu or ButtonStack widget. 

The menu initially contains the items

—Here to Top (Here to Left)

—Top to Here (Left to Here)

—Previous

If these items are removed from the menu by the application, a warning is generated (see ERROR HANDLING(3W)).  XtNorientation

Range of Values:

OL_HORIZONTAL/"horizontal"
OL_VERTICAL/"vertical"

This resource defines the direction for the visual presentation of the widget.  This resource cannot be changed via SetValues().  XtNproportionLength

Range of Values:

1 ≤ XtNproportionLength ≤ (XtNsliderMax - XtNsliderMin)

Default:

(XtNsliderMax - XtNsliderMin)

This resource gives the size of the Proportion Indicator.  The application uses the XtNsliderMax and XtNsliderMin resources to calibrate the scrollbar, making its overall length correspond to the overall length of the Content, and uses the XtNproportionLength resource to indicate how much of the Content is visible. 

While this resource gives the overall length of the Proportion Indicator, the Elevator always covers part of it.  If the Elevator would completely hide the Proportion Indicator, 3-point sections of it are shown above and below (or left of and right of) the Elevator.  If the Elevator is too close to an Anchor to show all of a 3-point section, as much as possible of the section is shown on that side (this may be a zero-length section).  XtNrepeatRate

Range of Values:

0 < XtNrepeatRate

This resource gives the time, in milliseconds, between repeated actions when SELECT is pressed on the Cables or Arrows.  Note that 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.  XtNshowPage

Range of Values:

OL_NONE
OL_LEFT
OL_RIGHT

If XtNshowPage changes from OL_NONE to one of the other If XtNshowPage changes from OL_NONE to one of the other values, a pop-up window for the page indicator is created.  If the value changes to OL_NONE, then the pop-up is destroyed. 

This value is checked when dragging is initiated.  If it is not set to OL_NONE, the page indicator will be popped to the screen.  While dragging, the page number in the indicator is constantly updated.  XtNsliderMax
XtNsliderMin

Range of Values:

XtNsliderMin < XtNsliderMax

These two resources are used to calibrate the Scrollbar widget.  An application should set their values to correspond to the range of the Content, and should set the value of the XtNproportionLength resource to the length of the view into the Content.  This calibrates the scrollbar.  The Scrollbar uses the calibration to convert the pixel location of the Elevator into a value in the range

The explanation for this range relation follows:  First, an

application calibrates the scrollbar as described above, so that XtNsliderMin and XtNsliderMax span the length of the Content and XtNproportionLength gives the length of the view of the Content.  Consider that the Elevator tracks a fixed position in the view; the position is arbitrary, but remains the same as the view is scrolled over the Content.  This can be the first line in the view.  When the view is at the top of the Content, the Elevator is at the top of the scrollbar and the calibrated position of the first line is XtNsliderMin. However, when the view is at the bottom of the content, the Elevator is at the bottom of the scrollbar and the calibrated position of the first line is XtNsliderMax – XtNproportionLength. 

  Figure 7 Scrollbar Coloration XtNsliderMoved

This resource defines the callback lists used when the scrollbar is manipulated in various ways.  The Scrollbar widget passes the final location of the Elevator, as an integer between XtNsliderMin and XtNsliderMax inclusive, in a structure pointed to by the call_data parameter.  The structure, OlScrollbarVerify, looks like this:

typedef struct _OlScrollbarVerify {
        int new_location;
        int new_page;
        Boolean ok;
        int slider_min;
        int slider_max;
        int delta;
} OlScrollbarVerify;

new_location
When the XtNsliderMoved callbacks are made, the new_location member gives the position of the attempted scroll.  This will be the new value of the XtNsliderValue resource if the scroll attempt is successful; however, the XtNsliderValue resource is not updated until after the callbacks return. 

new_page
new_page is used to set the page number. To see the page number, you have to set XtNshowPage to OL_LEFT or OL_RIGHT. 

okThe ok member of this structure is initially set to TRUE; the application should set a value that reflects whether the scroll attempt is allowed.  Since more than one callback routine may be registered for these resources, each callback routine can first check the ok member to see if a previous callback routine in the list has already rejected the scroll attempt.  The scrollbar will complete the scroll attempt only if, after the last callback has returned, the ok member is still TRUE. 

If the ok member is FALSE after the last callback returns, the Scrollbar restores the Elevator to the position it was in before the user attempted to move it.  This is required only when the Elevator has been dragged.  The Scrollbar does not move the Elevator for other scrollbar manipulations until the scroll attempt has been verified. 

slidermin

slidermax
These are the same values as in the XtNsliderMin and XtNsliderMax resources. 

deltaThis is the distance between the new scroll position and the old, as a signed value:

A callback can change

the new_location value to reflect a partial scroll.  For example, if the scrolling granularity causes a scroll attempt past the end of an application’s partially full buffer, the application should adjust new_location to a value representing the end of the buffer.  The adjusted value must lie between the values present before the attempted scroll and the new values given in the OlScrollbarVerify structure.  The XtNsliderMoved callbacks are issued when the Elevator position has been conditionally changed by the user

—clicking or pressing SELECT on the Up/Left or Down/Right arrow buttons;

—moving the Elevator to a new position by dragging SELECT on the Drag Area;

—clicking SELECT on the Top/Left or Bottom/Right Anchors;

—clicking or pressing SELECT on the Cable. 

XtNsliderValue

Range of Values:

XtNsliderMin ≤ XtNsliderValue ≤ XtNsliderMax - XtNproportionLength

This resource gives the current position of the Elevator.  The Scrollbar widget keeps this resource up to date; however, an application can also get the current value through the XtNsliderMoved callbacks. 

Sun Release 4.1  —  Last change: 1/26/90