Scrollbar(3W) UNIX System V Scrollbar(3W)
NAME
Scrollbar - moves or scrolls the view of an associated pane
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
10/89 Page 1
Scrollbar(3W) UNIX System V Scrollbar(3W)
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 and
drag area entirely, if necessary, to meet a resize request. These
abbreviated scrollbars are shown in Figure 3.
Page 2 10/89
Scrollbar(3W) UNIX System V Scrollbar(3W)
Figure 3. Abbreviated Scroll Bars
Minimum Scrollbar
If necessary, the Scrollbar widget will eliminate the anchors (in
addition to the Cable and drag area) to meet a resize request to form a
minimum scrollbar.
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, and the view does not change.
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 granularity.
When the application reaches the limit that it can scroll, the view no
longer changes and the Elevator stops moving.
10/89 Page 3
Scrollbar(3W) UNIX System V Scrollbar(3W)
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 and the Elevator and
pointer do not move.
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 Figure 4. 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 Figure 5. 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
Page 4 10/89
Scrollbar(3W) UNIX System V Scrollbar(3W)
Indicator to the other at a constant rate.
Figure 4. Elevator and Proportion Indicator at Left/Top Limits
Figure 5. Elevator and Proportion Indicator at Right/Bottom 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 Left This 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 Here This choice scrolls the Content so that the Unit at the
top or left of the viewing area is placed next to the
pointer.
Previous This 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. Note: If the
Scrollbar menu was invoked from the keyboard, then only
the "Previous" button is usable. In this case, the "Here
To" button and the "To Here" button are not sensitive.
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 scrollbar.
Scrollbar Coloration
When the Scrollbar widget receives the input focus through keyboard
traversal, the background color of the widget changes to the input focus
color, found in the resource XtNinputFocusColor. If the user traverses
out of the Scrollbar widget, the background of the widget reverts to its
original background color.
EXCEPTION: If the input focus color is the same as either the foreground
or background color, then the widget shows input focus by switching the
background and foreground colors.
Figure 6 illustrates the resources that affect the coloration of the
Scrollbar widget.
Figure 6. Scrollbar Coloration
10/89 Page 5
Scrollbar(3W) UNIX System V Scrollbar(3W)
Keyboard Traversal
The Scrollbar's default values of the XtNtraversalOn resource is True.
The user can operate the Scrollbar by using the keyboard to move the
Elevator and access the Anchors. The following keys manipulate the
Scrollbar:
- SCROLLUP and SCROLLDOWN (SCROLLLEFT and SCROLLRIGHT for horizontal
Scrollbars) move the Elevator one Unit in the given direction. The
Content changes 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 at this time, the
Elevator does not move and the view does not change.
The appropriate arrow in the Elevator highlights while the scrolling
action takes place.
- SCROLLTOP and SCROLLBOTTOM (SCROLLLEFTEDGE and SCROLLRIGHTEDGE for
horizontal Scrollbars) cause the view of the Content to change to the
top-most, bottom-most, left-most, or right-most pane respectively. The
Elevator moves to the limit in the direction of the Anchor.
These keys cause the appropriate Anchor to highlight while the scrolling
action takes place.
- PAGEUP and PAGEDOWN (PAGELEFT and PAGERIGHT for horizontal Scrollbars)
cause the view of the Content to change to the previous or next pane,
respectively.
- MENUKEY posts the Scrollbar's Menu.
__________________________________________________
| Vertical Scrollbar Activation Types |
|________________|________________________________|
| Activation Type| Expected Results |
|________________|________________________________|
| OL_MENUKEY, or | |
| OL_VSBMENU | Popup the scrollbar menu |
| OL_PAGEUP | Scrolls up one view |
| OL_PAGEDOWN | Scrolls down one view |
| OL_SCROLLUP | Scrolls up one Unit |
| OL_SCROLLDOWN | Scrolls down one Unit |
| OL_SCROLLTOP | Scrolls to top edge of pane |
| OL_SCROLLBOTTOM| Scrolls to bottom edge of pane|
|________________|________________________________|
_____________________________________________________
Horizontal Scrollbar Activation Types
Page 6 10/89
Scrollbar(3W) UNIX System V Scrollbar(3W)
_____________________________________________________
| Horizontal Scrollbar Activation Types |
|___________________|________________________________|
| Activation Type | Expected Results |
|___________________|________________________________|
|___________________|________________________________|
| Activation Type | Expected Results |
|___________________|________________________________|
| OL_MENUKEY, or | |
| OL_HSBMENU | Popup the scrollbar menu |
| OL_PAGELEFT | Scrolls left one view |
| OL_PAGERIGHT | Scrolls right one view |
| OL_SCROLLRIGHT | Scrolls right one Unit |
| OL_SCROLLLEFT | Scrolls left one Unit |
| OL_SCROLLRIGHTEDGE| Scrolls to right edge of pane |
| OL_SCROLLLEFTEDGE | Scrolls to left edge of pane |
|___________________|________________________________|
The Scrollbar widget responds to the following keyboard navigation keys:
- NEXT_FIELD, MOVEDOWN, and MOVERIGHT move to the next traversable widget
in the window
- PREV_FIELD, MOVEUP, and MOVELEFT move to the previous traversable widget
in the window
- NEXTWINDOW moves to the next window in the application
- PREVWINDOW moves to the previous window in the application
- NEXTAPP moves to the first window in the next application
- PREVAPP moves to the first window in the previous application
Operating the Scrollbar with keyboard disables any pointer warping.
Scrollbar Menu
The default choices in the Scrollbar Menu are created with XtNtraversalOn
set to True and XtNmnemonic set to the first character of their label.
When the Scrollbar Menu is posted via keyboard traversal, the "Here to
Top" and "Top to Here" buttons are not sensitive. These buttons depend
on the position of the pointer when the menu is posted, and so they are
not applicable when the menu is posted from the keyboard.
Display of Keyboard Mnemonic
The Scrollbar does not display the mnemonic accelerator. If the
Scrollbar is the child of a Caption widget, the Caption widget can be
used to display the Scrollbar's mnemonic.
10/89 Page 7
Scrollbar(3W) UNIX System V Scrollbar(3W)
Display of Keyboard Accelerators
The Scrollbar does not respond to a keyboard accelerator because clicking
the SELECT button on a Scrollbar activates depending on the pointer
position. So, the Scrollbar does not display a keyboard accelerator.
SUBSTRUCTURE
Scrollbar Menu component
Name: menu
Class: Menu
___________________________________________________________________________
| Application Resources |
|__________________|___________________|___________|______________|________|
| Name | Class | Type | Default | Access|
|__________________|___________________|___________|______________|________|
|__________________|___________________|___________|______________|________|
| *XtNcenter | XtCCenter | Boolean | TRUE | I |
|__________________|___________________|___________|______________|________|
| *XtNhPad | XtCHPad | Dimension| 4 | I |
|__________________|___________________|___________|______________|________|
| *XtNhSpace | XtCHSpace | Dimension| 4 | I |
|__________________|___________________|___________|______________|________|
| *XtNlayoutType | XtCLayoutType | OlDefine | OL_FIXEDROWS| I |
|__________________|___________________|___________|______________|________|
| *XtNmeasure | XtCMeasure | int | 1 | I |
|__________________|___________________|___________|______________|________|
| XtNpushpin | XtCPushpin | OlDefine | OL_NONE | I |
|__________________|___________________|___________|______________|________|
| XtNpushpinDefault| XtCPushpinDefault| Boolean | FALSE | I |
|__________________|___________________|___________|______________|________|
| *XtNsameSize | XtCSameSize | OlDefine | OL_COLUMNS | I |
|__________________|___________________|___________|______________|________|
| XtNtitle | XtCTitle | String | "Scrollbar" | I |
|__________________|___________________|___________|______________|________|
| *XtNvPad | XtCVPad | Dimension| 4 | I |
|__________________|___________________|___________|______________|________|
| *XtNvSpace | XtCVSpace | Dimension| 4 | I |
|__________________|___________________|___________|______________|________|
*See the Menu and ControlArea widgets for the descriptions of these
resources.
RESOURCES
_______________________________________________________________________________________
Scrollbar Resource Set
_______________________________________________________________________________________
Name Class Type Default Access
Page 8 10/89
Scrollbar(3W) UNIX System V Scrollbar(3W)
_______________________________________________________________________________________
| Scrollbar Resource Set |
|_____________________|______________________|________________|_______________|________|
| Name | Class | Type | Default | Access|
|_____________________|______________________|________________|_______________|________|
|_____________________|______________________|________________|_______________|________|
_______________________________________________________________________________________
XtNaccelerator XtCAccelerator String NULL SGI
_______________________________________________________________________________________
XtNacceleratorText XtCAcceleratorText String Dynamic SGI
_______________________________________________________________________________________
XtNancestorSensitive XtCAncestorsensitive Boolean TRUE G*
_______________________________________________________________________________________
XtNbackground XtCBackground Pixel White SGI†
_______________________________________________________________________________________
XtNbackgroundPixmap XtCBackgroundPixmap Pixmap (none) SGI†
_______________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SGI
_______________________________________________________________________________________
XtNcurrentPage XtCCurrentPage int 1 SGIT
_______________________________________________________________________________________
XtNdestroyCallback XtCDestroyCallback XtCallbackList NULL SI
_______________________________________________________________________________________
XtNdragCBType XtCDragCBType OlDefine OL_CONTINUOUS SGI
_______________________________________________________________________________________
XtNforeground XtCForeground Pixel Black SGI
_______________________________________________________________________________________
XtNgranularity XtCGranularity int 1 SGI
_______________________________________________________________________________________
XtNheight XtCHeight Dimension (calculated) SGI
_______________________________________________________________________________________
XtNinputFocusColor XtCInputFocusColor Pixel Black SGI
_______________________________________________________________________________________
XtNinitialDelay XtCInitialDelay int 500 SGI
_______________________________________________________________________________________
XtNmappedWhenManaged XtCMappedWhenManaged Boolean TRUE SGI
_______________________________________________________________________________________
XtNmenuPane XtCMenuPane Widget (none) G
_______________________________________________________________________________________
XtNmnemonic XtCMnemonic unsigned char NULL SGI
_______________________________________________________________________________________
XtNorientation XtCOrientation OlDefine OL_VERTICAL GI
_______________________________________________________________________________________
XtNproportionLength XtCProportionLength int (variable) SGI
_______________________________________________________________________________________
XtNreferenceName XtCReferenceName String NULL SGI
_______________________________________________________________________________________
XtNreferenceWidget XtCReferenceWidget Widget NULL SGI
_______________________________________________________________________________________
XtNrepeatRate XtCRepeatRate int 100 SGI
_______________________________________________________________________________________
XtNsensitive XtCSensitive Boolean TRUE GI*
10/89 Page 9
Scrollbar(3W) UNIX System V Scrollbar(3W)
_______________________________________________________________________________________
| Scrollbar Resource Set (cont'd) |
|_____________________|______________________|________________|_______________|________|
| Name | Class | Type | Default | Access|
|_____________________|______________________|________________|_______________|________|
|_____________________|______________________|________________|_______________|________|
| XtNshowPage | XtCShowPage | OlDefine | OL_NONE | SGI |
|_____________________|______________________|________________|_______________|________|
| XtNsliderMax | XtCSliderMax | int | 100 | SGI |
|_____________________|______________________|________________|_______________|________|
| XtNsliderMin | XtCSliderMin | int | 0 | SGI |
|_____________________|______________________|________________|_______________|________|
| XtNsliderMoved | XtCSliderMoved | XtCallbackList| NULL | SI |
|_____________________|______________________|________________|_______________|________|
| XtNsliderValue | XtCSliderValue | int | 0 | SGI |
|_____________________|______________________|________________|_______________|________|
| XtNstopPosition | XtCStopPosition | OlDefine | OL_ALL | SGI |
|_____________________|______________________|________________|_______________|________|
| XtNtraversalOn | XtCTraversalOn | Boolean | TRUE | SGI |
|_____________________|______________________|________________|_______________|________|
| XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_____________________|______________________|________________|_______________|________|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|_____________________|______________________|________________|_______________|________|
| XtNx | XtCPosition | Position | 0 | SGI |
|_____________________|______________________|________________|_______________|________|
| XtNy | XtCPosition | 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(), XtNcurrentPage should
also be set in the same call. If XtNshowPage is already set, and later
XtNsliderValue is changed via SetValues(), XtNcurrentPage should also be
set in the same call.
XtNdragCBType
Range of values:
OL_CONTINUOUS/"continuous"
OL_GRANULARITY/"granularity"
OL_RELEASE/"release"
This resource determines the frequency of issuing XtNsliderMoved
callbacks. If set to OL_CONTINUOUS, callbacks will be issued continuously
(just like in Xt+ 2.0). If set to OL_GRANULARITY, callbacks will only be
issued when the drag box crosses any granularity positions. If set to
OL_RELEASE, callback will only be issued once when the SELECT button is
released.
Page 10 10/89
Scrollbar(3W) UNIX System V Scrollbar(3W)
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.
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 scrollbar 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(3W) in the Convenience Routines section).
XtNorientation
Range of Values:
OLHORIZONTAL/"horizontal"
OLVERTICAL/"vertical"
This resource defines the direction for the visual presentation of the
widget. This resource cannot be changed via SetValues().
10/89 Page 11
Scrollbar(3W) UNIX System V Scrollbar(3W)
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).
For example, if you have 100 items to be displayed and only one item is
viewable in the pane at a time, then set XtNsliderMin to 0, XtNsliderMax
to 100, and XtNproportionLength to 1. The possible sliderValues are from
0 to 99, inclusive. Another example, 100 items, but 25 items viewable at
a time, then set XtNsliderMin to 0, XtNsliderMax to 100,
XtNproportionLength to 25. The possible sliderValues are from 0 to 75,
inclusive.
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:
OLNONE
OLLEFT
OLRIGHT
If XtNshowPage changes from OLNONE to one of the other values, a pop-up
window for the page indicator is created. If the value changes to
OLNONE, 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.
Page 12 10/89
Scrollbar(3W) UNIX System V Scrollbar(3W)
NOTE:
The page indicator feature is not popped to the screen when using the
keyboard rather than the mouse for drag operations.
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
XtNsliderMin < range < XtNsliderMax - XtNproportionLength
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. As Figure 7 shows, 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. Elevator Range of Movement
10/89 Page 13
Scrollbar(3W) UNIX System V Scrollbar(3W)
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 calldata
parameter. The structure, OlScrollbarVerify, looks like this:
typedef struct OlScrollbarVerify {
int newlocation;
int newpage;
Boolean ok;
int slidermin;
int slidermax;
int delta;
Boolean movecbpending;
} OlScrollbarVerify;
newlocation
When the XtNsliderMoved callbacks are made, the newlocation
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.
newpage
This will be the new value of the XtNcurrentPage resource if the
scroll attempt is succssful. newpage is used to set the page
number. To see the page number, you have to set XtNshowPage to
OLLEFT or OLRIGHT.
ok The 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
Page 14 10/89
Scrollbar(3W) UNIX System V Scrollbar(3W)
slidermax
These are the same values as in the XtNsliderMin and XtNsliderMax
resources.
delta This is the distance between the new scroll position and the old,
as a signed value:
delta = newlocation - old location
A callback can change the newlocation 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 newlocation 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.
movecbpending
The boolean, movecbpending, is set to TRUE, if more callbacks
are pending. If an application received a callback with this set
to TRUE, it is guaranteed that a callback with movecbpending
set to FALSE will follow shortly, before or when an operation is
completed. Currently, movecbpending is set to TRUE only during
a drag operation.
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.
XtNstopPosition
Range of values:
OL_ALL/"all"
OL_GRANULARITY/"granularity"
This resource determines the disposition of the drag box at the end of an
drag operation. If set to OL_ALL, upon the release of the SELECT button
10/89 Page 15
Scrollbar(3W) UNIX System V Scrollbar(3W)
in a drag operation, the drag box will be positioned at where it stops.
If set to OL_GRANULARITY, the drag box will snap to the nearest
granularity position.
Page 16 10/89