Volume 6A: Motif Programming Manual

an absolute number; clicking on either of the directional arrows changes the ScrollBar's value incrementally; clicking

in the scrolling region, but not on the slider itself changes the ScrollBar's value by page lengths. The value is

measured in units, not pixels.

The view length is the size of the viewable area (clip window), as measured in unit lengths. The vertical ScrollBar for

a Text widget that is displaying 15 lines of text would have a view length of 15. The horizontal ScrollBar's view

length would be the number of columns that the clip window can display.

The page length is measured in unit lengths and is usually one less than the view length. If the user scrolls the window

by a page increment, the first line from the old view is retained as the last line in the new view for visual reference

because otherwise, the user might lose her orientation.

10.3.1 Resources

the figure illustrates the relationship between the elements listed above and introduces the ScrollBar resources that

correspond to these values.

Conceptual relationship between a ScrollBar and the object it scrolls

The XmNincrement resource represents the number of units that the ScrollBar reports having scrolled when the user

clicks on its incremental arrows. The value for XmNincrement in the figure is 1 because each incremental scroll on

the vertical ScrollBar should scroll the text one line. Internally, the Text widget knows that the number of pixels

associated with XmNincrement is the height of a line. For an automatic ScrolledWindow, it is rare to set the

resource to any value other than 1.

10 ScrolledWindows and ScrollBars 10.3.1 Resources

262

The XmNpageIncrement resource specifies the number of units that the ScrollBar should report having scrolled

when the user moves the ScrollBar by a page. Again, the ScrollBar doesn't actually perform the scrolling, it just

reports the scrolling action. However, the ScrollBar does use this value to calculate the new visual position for the

slider within the scrolling area and to update its display. The application can use this value, multiplied by

pixels−per−unit, to determine the new data to display in the work window.

The XmNmaximum resource is the largest size, measured in unit increments, that the object can have. For the Text

widget shown above, the value for XmNmaximum is 9. The Motif Text widget sets its horizontal ScrollBar's

XmNmaximum to the number of characters in its widest visible line, rather than the widest of all of its lines. The

XmN-minimum resource is the smallest size, measured in unit increments, that the object will ever have. The

XmNsliderSize resource corresponds to the view length. The resource specifies the size of the clip window in unit

lengths. For example, in the figure, the clip window can display five lines, so XmNsliderSize is 5.

The XmNvalue is the number of units that the data in the clip window is offset from the beginning of the work

window. For example, if the Text widget has been scrolled down by four lines from the top, the value of the vertical

ScrollBar's XmNvalue resource would be 4.

the source code demonstrates how the vertical ScrollBar resources get their values from a typical ScrolledText object.

XtSetLanguageProc() is only available in X11R5; there is no corresponding function in X11R4.

/* simple_sb.c −− demonstrate the Scrollbar resource values from

* a ScrolledText object. This is used as an introductory examination

* of the resources used by Scrollbars.

*/

#include <Xm/ScrolledW.h>

#include <Xm/RowColumn.h>

#include <Xm/PushBG.h>

#include <Xm/Text.h>

/* print the "interesting" resource values of a scrollbar */

void

get_sb(widget, client_data, call_data)

Widget widget;

XtPointer client_data;

XtPointer call_data;

{

Widget scrollbar = (Widget) client_data;

int increment=0, maximum=0, minimum=0;

int page_incr=0, slider_size=0, value=0;

XtVaGetValues (scrollbar,

XmNincrement, &increment,

XmNmaximum, &maximum,

XmNminimum, &minimum,

XmNpageIncrement, &page_incr,

XmNsliderSize, &slider_size,

XmNvalue, &value,

NULL);

printf ("increment=%d, max=%d, min=%d, page=%d, slider=%d, value=%d0,

increment, maximum, minimum, page_incr, slider_size, value);

}

main(argc, argv)

int argc;

char *argv[];

{

Widget toplevel, rowcol, text_w, pb, sb;

10 ScrolledWindows and ScrollBars 10.3.1 Resources

263

XtAppContext app;

Arg args[10];

int n = 0;

XtSetLanguageProc (NULL, NULL, NULL);

toplevel = XtVaAppInitialize (&app, "Demos",

NULL, 0, &argc, argv, NULL, NULL);

/* RowColumn contains ScrolledText and PushButton */

rowcol = XtVaCreateWidget ("rowcol",

xmRowColumnWidgetClass, toplevel, NULL);

XtSetArg (args[n], XmNrows, 10); n++;

XtSetArg (args[n], XmNcolumns, 80); n++;

XtSetArg (args[n], XmNeditMode, XmMULTI_LINE_EDIT); n++;

XtSetArg (args[n], XmNscrollHorizontal, False); n++;

XtSetArg (args[n], XmNwordWrap, True); n++;

text_w = XmCreateScrolledText (rowcol, "text_w", args, n);

XtManageChild (text_w);

/* get the scrollbar from ScrolledWindow associated with Text widget */

XtVaGetValues (XtParent (text_w), XmNverticalScrollBar, &sb, NULL);

/* provide a pushbutton to obtain the scrollbar's resource values */

pb = XtVaCreateManagedWidget ("Print ScrollBar Values",

xmPushButtonGadgetClass, rowcol, NULL);

XtAddCallback (pb, XmNactivateCallback, get_sb, sb);

XtManageChild (rowcol);

XtRealizeWidget (toplevel);

XtAppMainLoop (app);

}

This program simply displays a ScrolledText object and a PushButton. The ScrolledText object does not contain any

text by default; you can cut and paste some text into the object. The graphical output of the program is displayed in the

figure.

Output of simple_sb.c

10 ScrolledWindows and ScrollBars 10.3.1 Resources

264