Manual pages › OPEN LOOK widgets (3W)
olScrollbar(3W)
Scrollbar
From the original Amiga UNIX 2.1 manual. Some things it mentions may not be in this release.
WIDGET CLASS NAME · SYNOPSIS · DESCRIPTION · SUBSTRUCTURE · RESOURCES
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
Amiga Unix Last change: 1
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 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
Amiga Unix Last change: 2
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 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
Amiga Unix Last change: 3
to an Anchor by clicking SELECT on the Anchor, or drags the Elevator until it reaches the limit.
Amiga Unix Last change: 4
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 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. 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 Figure 6 illustrates the resources that affect the coloration of the Scrollbar widget.
Amiga Unix Last change: 5
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_|__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
Amiga Unix Last change: 6
______________________________________________________________________________________
_____________________________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______|__OL_VERTICAL_|__SGI___|
| XtNproportionLength | XtCProportionLength | int | (variable) | SGI |
|_____________________|______________________|________________|______________|________|
|_XtNrepeatRate_______|__XtCRepeatRate_______|__int___________|__100_________|__SGI___|
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI* |
|_____________________|______________________|________________|______________|________|
|_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___|
| 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 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 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().
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 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
values, a pop-up window for the page indicator is created.
If the value changes to OL_NONE, then the pop-up is des-
troyed. 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
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 call_data param-
eter. 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
The new_page 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 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.
delta This is the distance between the new scroll position
and the old, as a signed value:
.delta = .new_location - old location
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.
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; however, an application can also get the current value through the XtNsliderMoved callbacks.
Amiga Unix Last change: 6