Scrollbar(3w) — OLIT Widget Set
NAME
Scrollbar − scrollbar widget
SYNOPSIS
#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/Scrollbar.h>
. . .
Widget my_scrollbar, my_parent;
String my_name;
ArgList args;
Cardinal num_args;
my_scrollbar = XtCreate( my_name, scrollbarWidgetClass,
my_parent, args, num_args);
. . .
Widget menupane;
XtSetArg( args[0], XtNmenuPane, (XtArgVal) &menupaneP);
XtGetValues( my_scrollbar, args, 1);
Widget a_menu_item;
WidgetClass item_class;
String item_name;
a_menu_item = XtCreate( item_name, item_class, menupane, args, num_args);
DESCRIPTION
Components
Each full scrollbar has the following parts:
• cable, indicating the extent of scrolling
• anchors, top (left) and bottom (right), 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.
• elevator, which slides along the length of the cable, containing
• arrows, up (left) and down (right), used to move the view in the direction of the arrow by one unit.
• drag area, for moving the view by tracking the position of the mouse pointer relative to the scrollbar.
• 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.
• page indicator (optional), 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.
• scrollbar menu
Figure 1 Horizontal Scrollbar
Figure 2 Vertical Scroll Bar
Because a scrollbar can be seen and used horizontally as well as vertically, the 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.
Subwidgets
The Scrollbar contains one subwidget, a MenuShell provided automatically, and accessible through the XtNmenuPane resource.
Figure 3 Scrollbar Subwidgets Scrollbar
|
|
MenuShell (XtNmenupane)
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 4 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. SS "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 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 at this time, the elevator and pointer do not move, 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 the 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. While dragging SELECT, the drag area highlights. The pointer is constrained to stay within the Drag Area as the elevator moves.
Scrolling Limits
Clicking SELECT on one of the anchors causes the view of the Content to change to the corresponding pane, 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
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.
Pressing SELECT on the Cable repeats the action described above.
Elevator At 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 be 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.
When the content is scrolled to the end, the proportion indicator and the elevator align at the right or bottom end of the scrollbar, 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.
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/left – 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 – 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 – 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(3W) ). The ID of the Menu widget is available as a resource of the 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.
Note:
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.
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 associated menu.
Vertical Scrollbar Activation Types
_
Activation Type Expected Results
_
OL_MENUKEY, or
OL_VSBMENU Popup the scrollbar
OL_PAGEUP Scrolls up one
OL_PAGEDOWN Scrolls down one
OL_SCROLLUP Scrolls up one
OL_SCROLLDOWN Scrolls down one
OL_SCROLLTOP
Scrolls to top edge
OL_SCROLLBOTTOM
Scrolls to bottom edge
Horizontal Scrollbar Activation Types
_
Activation Type Expected Results
_
OL_MENUKEY, or
OL_HSBMENU Popup the scrollbar
OL_PAGELEFT Scrolls left one
OL_PAGERIGHT Scrolls right one
OL_SCROLLRIGHT Scrolls right one
OL_SCROLLLEFT Scrolls left one
OL_SCROLLRIGHTEDGE
Scrolls to right edge
OL_SCROLLLEFTEDGE
Scrolls to left edge
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 from the 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.
Keyboard Mnemonic Display
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.
Keyboard Accelerator Display
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.
RESOURCES
SUBSTRUCTURE
Scrollbar Menu component
Scrollbar Menu Resources
Name: menu Class: Menu
Table 1 Scrollbar Menu Resources
Scrollbar Menu Resources
Name Type Default Access
∗XtNcenter Boolean TRUE I
∗XtNhPad Dimension 4 I
∗XtNhSpace Dimension 4 I
∗XtNlayoutType OlDefine OL_FIXEDROWS I
∗XtNmeasure int 1 I
XtNpushpin OlDefine OL_NONE I
XtNpushpinDefault Boolean FALSE I
∗XtNsameSize OlDefine OL_COLUMNS I
XtNtitle String "Scrollbar" I
∗XtNvPad Dimension 4 I
∗XtNvSpace Dimension 4 I
Access:S = XtSetValues G = XtGetValues
I = init timeO = other access
Menu(3w) and ControlArea(3w)
†† see resources(3w)
Scrollbar Resources
Table 2 Scrollbar Resource Set
Scrollbar Resource Set
Name Type Default Access
XtNaccelerator String NULL SGI
XtNacceleratorText String Dynamic SGI
XtNancestorSensitive Boolean TRUE GO
XtNbackground Pixel XtDefaultBackground SGI
XtNbackgroundPixmap Pixmap (none) SGI
XtNconsumeEvent XtCallbackList NULL SGI
XtNcurrentPage int 1 SGI
XtNdestroyCallback XtCallbackList NULL SI
XtNdragCBType OlDefine OL_CONTINUOUS SGI
XtNforeground Pixel XtDefaultForeground SGI
XtNgranularity int 1 SGI
XtNheight Dimension (calculated) SGI
XtNinputFocusColor Pixel XtDefaultForeground SGI
XtNinitialDelay int 500 SGI
XtNmappedWhenManaged Boolean TRUE SGI
XtNmenuPane Widget (none) G
XtNmnemonic unsigned char NULL
XtNorientation OlDefine OL_VERTICAL GI
XtNproportionLength int (variable) SGI
XtNreferenceName String NULL SGI
XtNreferenceWidget Widget NULL SGI
XtNrepeatRate int 100 SGI
XtNsensitive Boolean TRUE GIO
XtNshowPage OlDefine OL_NONE SGI
XtNsliderMax int 100 SGI
XtNsliderMin int 0 SGI
XtNsliderMoved XtCallbackList NULL SI
XtNsliderValue int 0 SGI
XtNstopPosition OlDefine OL_ALL SGI
XtNtraversalOn Boolean TRUE SGI
XtNuserData XtPointer NULL SGI
XtNuseSetValCallback Boolean FALSE SGI
XtNwidth Dimension (calculated) SGI
XtNx Position 0 SGI
XtNy Position 0 SGI
Access:S = XtSetValues G = XtGetValues
I = init timeO = other access
† see resources(3w)
XtNbackground
class:XtCBackground type:Pixel default:Whiteaccess:SGI
Action: redisplay the anchors, the elevator, and the proportion indicator in the new color.
XtNcurrentPage
class:XtCCurrentPage type:int default:1access:SGIT
Action: typically not selectable.
However, there are two exceptions. If XtNshowPage is set via XtSetValues, 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.
XtNforeground
class:XtCForeground type:Pixel default:Blackaccess:SGI
Action: 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.
XtNgranularity
class:XtCGranularity type:int default:1access:SGI
Action: specifies distance elevator attempts to move when clicking or pressing SELECT on an arrow.
Values: 1 ≤ XtNgranularity ≤ XtNsliderMax - XtNsliderMin
Normally, the drag operation does not honor granularity unless enforcement is set in the XtNsliderMoved callback procedure.
XtNinitialDelay
class:XtCInitialDelay type:int default:500access:SGI
Action: gives the time, in milliseconds, before the first action occurs when SELECT is pressed on the cables or arrows.
Values: 0 < XtNinitialDelay
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
class:XtCMenuPane type:Widget default:(none)access:G
Action: specifies 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 ErrorHandling(3W).
XtNorientation
class:XtCOrientation type:OlDefine default:OL_VERTICALaccess:SGI
Action: defines the direction for the visual presentation of the widget.
Values: OL_HORIZONTAL, OL_VERTICAL
This resource cannot be changed via .""XtSetValues
Values: OL_HORIZONTAL, OL_VERTICAL
XtNproportionLength
class:XtCProportionLength type:int default:(variable)access:SGI
Action: gives the size of the proportion indicator
Values: 1 ≤ XtNproportionLength ≤ (XtNsliderMax - XtNsliderMin)
Default: (XtNsliderMax - XtNsliderMin)
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
class:XtCRepeatRate type:int default:100access:SGI
Action: 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.
XtNscale
class:XtCScale type:Int default:12access:SGI
Action: determines size of graphical elements, in points
Values:
0 < XtNscale
This resource sets the size of graphical elements (widgets) in a manner similar to other scale resources.
Note that the units of this resource are points (1/72 of an inch) , not pixels.
Note: Only sizes 10, 12, 14, 19 are presently supported. If this resource is set to any other value, one of these is substituted instead.
XtNshowPage
Action: controls page indicator during dragging.
Values: OL_LEFT, OL_RIGHT, OL_NONE
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.
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.
XtNsliderMax
class:XtCSliderMax type:int default:100access:SGI class:XtCSliderMin type:int default:0access:SGI
Action: calibration of the scrollbar
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.
Values: XtNsliderMin < XtNsliderMax
XtNsliderMoved
class:XtCSliderMoved type:XtCallbackList default:NULLaccess:SI
Action: defines callback lists used when the scrollbar is manipulated.
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:
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 is used to set the page number. To see the page number, you have to set XtNshowPage to OL_LEFT or OL_RIGHT.
ok – initially set to TRUE; the application sets the value to indicate 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 ok 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 are the same values as in the XtNsliderMin and XtNsliderMax resources.
delta 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
class:XtCSliderValue type:int default:0access:SGI
Action: gives the current position of the elevator.
Values: XtNsliderMin ≤ XtNsliderValue ≤ XtNsliderMax - XtNproportionLength
The Scrollbar widget keeps this resource up to date; however, an application can also get the current value through the XtNsliderMoved callbacks.
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 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.
XtNuseSetValCallback
class:XtCUseSetValCallback type:Boolean default:FALSEaccess:SGI
Action: determines callback action with programmatic control of slider value
Values:
TRUE – call the callbacks specified in XtNsliderMoved when the slider value changes, even if it changes under program control instead of as the result of mouse action.
FALSE – do not call the callbacks specified in XtNsliderMoved when the slider value changes under program control.
The callbacks listed in XtNsliderMoved are called as the result of mouse action by the user changing the slider value. This resource allows those callbacks to be called when the slider value changes under program control as well as by mouse action.
SEE ALSO
Menu(3w), ControlArea(3Ww, resources(3w)
Version 3.0 — Last change: 19 July 91 — Last change: 19 July 91