Volume 6A: Motif Programming Manual

Output of getusers.c

The components in the program do not have any functionality; the program is used solely to demonstrate how panels

of arbitrary widgets can be displayed in a ScrolledWindow. The widget hierarchy is irrelevant to the operation of the

ScrolledWindow. In this particular case, the ScrolledWindow is a child of the top−level shell. We could have used a

MainWindow widget in place of a ScrolledWindow; these two components are interchangeable because the

MainWindow is subclassed from the ScrolledWindow. See Chapter 4, The Main Window, for more details on how

the MainWindow widget fits into the design of an application.

We used arbitrary values for the width and height of the ScrolledWindow; they were chosen because they seemed to

work best. If you are using a ScrolledWindow with a number of other widgets in an interface, you do not need to

specify an initial size for the ScrolledWindow. Since the ScrolledWindow is extremely flexible, you can allow its

parent or its siblings to control its size. ScrolledWindows work well with PanedWindows because they can be

adjusted easily. However, the ScrolledWindow does not have a sensible default size, so you should provide an initial

geometry if the ScrolledWindow is going to control its own size. In this case, the size that you choose for the widget

should be based on the aesthetics of the data that is being displayed.

In the example, the child of the ScrolledWindow is the main_rc widget, which is a RowColumn that contains all of

the children that represent the password file information. After getusers() is called, the program loops through

each item in the array of UserInfo structures and creates a Form widget that contains a ToggleButton, two Labels,

and a Text widget. All of the Forms are stacked vertically on top of one another in the RowColumn. Once complete,

the user can scroll around and access any of the elements without the application having to support any of the

scrolling mechanisms because they are completely automated by the toolkit. In most cases, an application does not

need to do anything other than what we described in this section to take advantage of automatic scrolling.

10.3 Working Directly With ScrollBars

The ScrollBar is the backbone of the ScrolledWindow. Although the ScrollBar is a stand-alone widget that can be

created and manipulated without being the child of a ScrolledWindow, we are not going to discuss this usage because

10 ScrolledWindows and ScrollBars10.3 Working Directly With ScrollBars

260

it is not consistent with the Motif Style Guide. The kinds of things that you can do with a ScrollBar individually are no

more interesting than the sorts of things that you can do with them as children of ScrolledWindows, anyway. We are

going to discuss how to control a ScrollBar directly from an application in the context of a ScrolledWindow widget.

This information is useful if you want to monitor scrolling, if you want to fine−tune the way that automatic scrolling is

handled, or if you want to implement application−defined scrolling.

Before we begin, it is important to understand that the ScrollBar does not handle scrolling itself. The widget merely

reports scrolling actions through its callback routines. It is up to the internals of an application or a widget to install

callback procedures on the ScrollBar that adjust the work window appropriately. The ScrollBar manages its own

display in accordance with scrolling actions, so you do not need to update the ScrollBar's display unless the

underlying data of the object being scrolled changes. To change the display, you can set resources that are associated

with the different elements of the ScrollBar. the figure illustrates the design of a ScrollBar and identifies its elements.

This figure represents a vertical ScrollBar; a ScrollBar can also be oriented horizontally.

Elements of a ScrollBar

The appearance and behavior of a ScrollBar is directly related to the object that it scrolls. The relationship between the

ScrollBar and the object it scrolls is proportional, so that the size of the slider in the ScrollBar represents how much of

the object that is being scrolled is visible in the clip window. The size of the object being scrolled is broken down into

equally sized units; the size of the units is called the unit length. When the user clicks on one of the incremental

arrows (also called directional arrows), the ScrollBar scrolls in the direction indicated by the arrow in unit increments.

It is important to realize that the unit length is stored and interpreted internally by the object being scrolled; it is of no

interest to the ScrollBar itself, since it does not affect the display of the ScrollBar. While this value is not set on the

ScrollBar itself, it plays a key role in understanding how ScrollBars work.

All of the other resource values for the ScrollBar are measured in terms of the unit length. A Text widget might set its

unit length for the vertical ScrollBar to the height of the tallest character in the widget's font set, plus some margin for

whitespace on the top and bottom of the character. As a result, vertical scrolling adjusts the window so that the text is

always displayed without lines being partially obscured. However, it is the Text widget's responsibility to know the

unit length value. The unit length for the horizontal ScrollBar unit length might be the average width of the characters

in the font that is being used.

The value of a ScrollBar is the offset, measured in unit lengths, of the data in the clip window from the object's origin.

For example, if the top of the clip window displays the fourth line of text in a Text widget, the ScrollBar is said to

have a value of 3, since it is offset from 0. Clicking and dragging the slider directly changes the ScrollBar's value to

10 ScrolledWindows and ScrollBars10.3 Working Directly With ScrollBars

261