SCROLLBAR WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
SC
SROLLBAR WIDGET(3W)
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 correspond-
ing 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
Amiga Unix Last change: 1
SCROLLBAR WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
SC
SROLLBAR WIDGET(3W)
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, respec-
tively. 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 Figure 3.
Figure 3. Abbreviated Scroll Bars
Elevator Motion As visual feedback to the user, the Eleva-
tor 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 per-
formed 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 appli-
cation 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 scrol-
ling action takes place. If SELECT is pressed, the
Amiga Unix Last change: 2
SCROLLBAR WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
SC
SROLLBAR WIDGET(3W)
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 XtNslider-
Moved callback allows the application to enforce granular-
ity. 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 Con-
tent 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 direc-
tion 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 gen-
eral, 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
Amiga Unix Last change: 3
SCROLLBAR WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
SC
SROLLBAR WIDGET(3W)
to an Anchor by clicking SELECT on the Anchor, or drags
the Elevator until it reaches the limit.
Amiga Unix Last change: 4
SCROLLBAR WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
SC
SROLLBAR WIDGET(3W)
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 Con-
tent. However, the scrollbar widget does not maintain
this relation but relies on the application to provide the
length of the Proportion Indicator. The Proportion Indi-
cator 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 drag-
ging SELECT), the Elevator creeps from one end of the Pro-
portion 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 fig-
ures) 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. An applica-
tion 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 Figure 6
illustrates the resources that affect the
coloration of the Scrollbar widget.
Amiga Unix Last change: 5
SCROLLBAR WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
SC
SROLLBAR WIDGET(3W)
Figure 6. Scrollbar Coloration
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_|__OLFIXEDROWS|__I_____|
| *XtNmeasure | XtCMeasure | int | 1 | I |
|__________________|___________________|___________|______________|________|
|_XtNpushpin_______|__XtCPushpin_______|__OlDefine_|__OLNONE_____|__I_____|
| XtNpushpinDefault| XtCPushpinDefault| Boolean | FALSE | I |
|__________________|___________________|___________|______________|________|
|_*XtNsameSize_____|__XtCSameSize______|__OlDefine_|__OLCOLUMNS__|__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
Amiga Unix Last change: 6
SCROLLBAR WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
SC
SROLLBAR WIDGET(3W)
______________________________________________________________________________________
_____________________________Scrollbar_Resource_Set\*(cO______________________________
Name Class Type Default Access
______________________________________________________________________________________
Amiga Unix Last change: 7
() MISC. REFERENCE MANUAL PAGES ()
______________________________________________________________________________________
|_XtNancestorSensitive___XtCAncestorsensitive___Boolean__________TRUE___________G*____|
| XtNbackground | XtCBackground | Pixel | White | SGI† |
|_____________________|______________________|________________|______________|________|
|_XtNbackgroundPixmap_|__XtCBackgroundPixmap_|__Pixmap________|__(none)______|__SGI†__|
| XtNcurrentPage | XtCCurrentPage | int | 1 | SGIT |
|_____________________|______________________|________________|______________|________|
|_XtNdepth____________|__XtCDepth____________|__int___________|__(parent's)__|__GI____|
| XtNdestroyCallback | XtCDestroyCallback | XtCallbackList| NULL | SI |
|_____________________|______________________|________________|______________|________|
|_XtNforeground_______|__XtCForeground_______|__Pixel_________|__Black_______|__SGI___|
| XtNgranularity | XtCGranularity | int | 1 | SGI |
|_____________________|______________________|________________|______________|________|
|_XtNheight___________|__XtCHeight___________|__Dimension_____|__(calculated)|__SGI___|
| XtNinitialDelay | XtCInitialDelay | int | 500 | SGI |
|_____________________|______________________|________________|______________|________|
|_XtNmappedWhenManaged|__XtCMappedWhenManaged|__Boolean_______|__TRUE________|__SGI___|
| XtNmenuPane | XtCMenuPane | Widget | (none) | G |
|_____________________|______________________|________________|______________|________|
|_XtNorientation______|__XtCOrientation______|__OlDefine______|__OLVERTICAL_|__SGI___|
| XtNproportionLength | XtCProportionLength | int | (variable) | SGI |
|_____________________|______________________|________________|______________|________|
|_XtNrepeatRate_______|__XtCRepeatRate_______|__int___________|__100_________|__SGI___|
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI* |
|_____________________|______________________|________________|______________|________|
|_XtNshowPage_________|__XtCShowPage_________|__OlDefine______|__OLNONE_____|__SGI___|
| XtNsliderMax | XtCSliderMax | int | 100 | SGI |
|_____________________|______________________|________________|______________|________|
|_XtNsliderMin________|__XtCSliderMin________|__int___________|__0___________|__SGI___|
| XtNsliderMoved | XtCSliderMoved | XtCallbackList| NULL | SI |
|_____________________|______________________|________________|______________|________|
|_XtNsliderValue______|__XtCSliderValue______|__int___________|__0___________|__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.
Amiga Unix Last change: 1
() MISC. REFERENCE MANUAL PAGES ()
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 descrip-
tion 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 opera-
tion 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 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:
OLHORIZONTAL/"horizontal"
OLVERTICAL/"vertical"
This resource defines the direction for the visual presenta-
tion of the widget. This resource cannot be changed via
SetValues().
Amiga Unix Last change: 2
() MISC. REFERENCE MANUAL PAGES ()
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 Eleva-
tor. 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:
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 des-
troyed. This value is checked when dragging is initiated.
If it is not set to OLNONE, 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
Amiga Unix Last change: 3
() MISC. REFERENCE MANUAL PAGES ()
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 8 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
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 param-
eter. The structure, OlScrollbarVerify, looks like this:
typedef struct OlScrollbarVerify {
int newlocation;
int newpage;
Boolean ok;
int slidermin;
int slidermax;
int delta;
} 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
The newpage member is currently unused.
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
Amiga Unix Last change: 4
() MISC. REFERENCE MANUAL PAGES ()
registered for these resources, each callback rou-
tine can first check the ok member to see if a pre-
vious 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.
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.
Amiga Unix Last change: 5
() MISC. REFERENCE MANUAL PAGES ()
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; how-
ever, an application can also get the current value through
the XtNsliderMoved callbacks.
Amiga Unix Last change: 6