Volume 7A: XView Programming Manual

10

Scrollbars

Scrollbars are used to change what you view in a subwindow. For instance, in a text subwin-

dow, scrollbars are used to scroll through a document. In a canvas subwindow, scrollbars can

be used to see another portion of the paint window (which can be larger than the canvas

subwindow). This chapter addresses specific functions of scrollbars themselves. These func-

tions are applicable to any XView package that has scrollbars attached. If you are interested

in how to utilize scrollbars for a particular package, you should consult the chapter that dis-

cusses that package.

OPEN LOOK describes scrollbars using the visual metaphor of an elevator riding on a cable,

which is attached at both ends to anchors. Figure 10-1 shows a scrollbar from the OPEN

LOOK

GUI Specification Guide.

Figure 10-1. An

OPEN LOOK

scrollbar

Scrollbars

Scrollbars 253

The elevator contains directional arrows and a drag box. A subwindow can have vertical or

horizontal scrollbars. Horizontal scrollbars are placed to the right of the subwindow while

vertical scrollbars are placed at the bottom. OPEN LOOK defines precisely how scrollbars

look and behave—the programmer or user cannot change it. All the programmer can control

is the scrollbar’s color, length, and various other common and generic attributes.

One of the functions of the scrollbar is the ability to split a view. The OPENWIN package pro-

vides objects such as text subwindows and canvases that may be split into several views; the

scrollbar provides the functional interface. Certain XView packages, such as text subwin-

dows, automatically create their own scrollbars. Canvases, on the other hand, require the

programmer to create and attach scrollbars.

The scrollbar’s look and feel is related to the size of the object it scrolls. Attributes are asso-

ciated with each of the following terms:

Orientation The orientation of a scrollbar indicates whether it is horizontal or vertical.

Object Length The length of the object is registered with the scrollbar. The proportional

indicator (the darkened part of the elevator cable) uses this value. For

example, the object length for a text subwindow is the number of lines in

the editing buffer.

Page Length When the object length is larger than what the view window can contain,

the overall area is broken up into pages. When the user selects the elevator

cable, the scrollbar scrolls in page segments in the direction of the cursor

(e.g., left, right, up, or down) relative to the elevator.

Unit Length When the user clicks on the elevator arrows, the scrollbar scrolls one unit.

Units are measured in pixels, so arbitrary or abstract objects that are to be

scrolled should be measured in terms of pixels so that scrolling seems con-

sistent with the object. For example, a text subwindow sets its scrollbar’s

unit length to the size of the characters in the font. Unit scrolling results in

the window moving line by line up or down.

View Length The view length is the same size as the height or width of the subwindow

the scrollbar is associated with depending on the scrollbar’s orientation.

Figure 10-2 illustrates the terminology used above.

10.1 Creating Scrollbars

The definitions necessary to use scrollbars are found in the header file <xview/scrollbar.h>.

The basic scrollbar is created using the following code fragment:

Scrollbar scrollbar;

scrollbar = (Scrollbar)xv_create(owner, SCROLLBAR, NULL);

254 XView Programming Manual

(Values measured in units)

SCROLLBAR_VIEW_START (2)

SCROLLBAR_VIEW_LENGTH (5)

object

being

scrolled

unit size

SCROLLBAR_OBJECT_LENGTH (8)

SCROLLBAR_VIEW_START

SCROLLBAR_VIEW_LENGTH

Figure 10-2. Relationship between a scrollbar and the object it scrolls

The owner must be an object subclassed from the OPENWIN package or the FRAME package.

Figure 10-3 shows the class hierarchy for the SCROLLBAR package.

Scrollbars

Scrollbars 255

Generic

Object

(Drawable) Window Scrollbar

Figure 10-3. Scrollbar class hierarchy

The scrollbar inherits certain attributes from the parent while other attributes are initialized

automatically. For example, if the owner of the scrollbar is a canvas, the scrollbar’s color is

inherited from the canvas, while the scrollbar’s object length is set by the canvas explicitly;

that is, you are not required to set it. This is usually desirable when creating objects that are

used together.

10.2 Relationship Between Scrollbars and Objects

Most scrollbar attributes describe the relationship between the scrollbar and the object such

as a canvas or text subwindow that is affected by scrolling. The foremost is

SCROLLBAR_PIXELS_PER_UNIT

, which describes the number of pixels in a scrolling unit.

For text subwindows, the unit is the text width and height. For canvases, it is one pixel (by

default). If you were to build a canvas subwindow intended to browse a set of 64x64 bit-

maps, then you would set this to 64. Scrolling actions occur in scrollbar units, so this would

mean that the clicking on one of the elevator arrows causes a scrolling movement of 64 pix-

els at a time. Most scrollbar attribute values are based on the unit value.

The size of the object itself (a graphic image, text stream or whatever) is stored as the

SCROLLBAR_OBJECT_LENGTH while the size of the viewable window is represented as the

scrollbar’s SCROLLBAR_VIEW_LENGTH. After having been scrolled, the scrollbar’s current

offset into the object is reflected in SCROLLBAR_VIEW_START. When paging is done (select-

ing the cable portion of the elevator), the amount scrolled is set by

SCROLLBAR_PAGE_LENGTH. These values are in object units, so to get their values in pixels,

multiply by the value of

SCROLLBAR_PIXELS_PER_UNIT.

The scrollbar manages its own events, resizes and repaints automatically. It is not necessary

to interpose event handlers for the scrollbar. By default, the event handling mechanism

determines the type of scrolling that has been done and changes the appropriate attributes.

All OPENWIN objects that support scrollbars also redisplay the window to show the results of

scrolling.

Even though you do not need to know when the scrollbar is scrolled to manage the scrolling,

you might be interested in knowing when the scrolling action occurs. XView objects such as

text subwindows that manage their own data (text, in this case) handle this automatically.

See Chapter 5, Canvases and Openwin, for discussion on scrolling canvases.

256 XView Programming Manual

If a window that has a scrollbar is resized, the scrollbar is resized accordingly. If the window

is sized too small for all of the parts of the scrollbar to be visible or usable, then those parts

cannot be available. At the very least, the scrolling arrows must be visible. Figure 10-4

shows a text subwindow that has been split twice. Notice the scrollbars to the right of the

text subwindows. The uppermost window cannot be split again because the minimum size of

the scrollbar has been reached.

Figure 10-4. Splitting a text subwindow twice

Scrollbars

Scrollbars 257