Nearly all the basic controls are subclasses of XmPrimitive or XmGadget. XmPrimitive, in turn, is a subclass of the Intrinsics Core class, and XmGadget is a subclass of the Intrinsics RectObj class.

Labels, buttons, and separators are simple widgets built on XmPrimitive.

A widget can act as a viewport onto a virtual scroll. The ScrollBar is the control that moves the viewport horizontally or vertically relative to the underlying scroll. A ScrollBar consists of a rectangle, called the scroll region, representing the full size of the scroll. It has a smaller rectangle, called the slider, within the scroll region, representing the position and size of the viewport relative to the full scroll. The ScrollBar usually has arrow graphics at both ends of the larger rectangle.

A ScrollBar has translations and actions that allow the user to move the slider. By clicking on an arrow, the user moves the slider one small increment in the direction of the arrow. By clicking in the scroll region between an arrow and the slider, the user moves the slider a larger increment (the page increment) in the direction of the arrow. When the ScrollBar has keyboard focus the user can use the keyboard to move the slider in this way. The user can also drag the slider using the mouse.

By itself, the ScrollBar does not have an association with a widget acting as a viewport onto a scroll. Most applications use a ScrolledWindow, a Manager widget with a child to be scrolled and possibly with one or two ScrollBars to control the scrolling. ScrolledWindow can automatically control the interaction between the scrolled child and the ScrollBars, or it can allow the application to control the interaction. For more information see Chapter 9, "Scrolling, Panes, and Frames."

ScrollBar has a number of resources that allow the application to use it to control scrolling:

Two convenience routines, XmScrollBarGetValues and XmScrollBarSetValues, allow the application to get and set the value, slider size, increment, and page increment in one call.

A Scale displays a value within a range and optionally allows the user to supply a new value. Its appearance and behavior are much like those of a ScrollBar without arrows. It also has a title and can display the current value next to the slider.

Like a ScrollBar, a Scale has minimum, maximum, and current integral values. The application has no access to the slider size, and the current value ranges between the minimum and maximum. The increment by which the arrow keys move the slider is always 1, but the application can supply a multiple increment (XmNscaleMultiple) analogous to ScrollBar's XmNpageIncrement. Scale has two callback lists: XmNvalueChangedCallback is invoked when the user changes the value but is not in the process of dragging the slider, and XmNdragCallback is invoked when the user changes the value while dragging the slider.

Scale also has resources controlling whether the orientation is vertical or horizontal and which end of the Scale represents the minimum value. Other resources control aspects of the Scale's appearance, including the width and height, the title string, whether or not the Scale displays the current value next to the slider, the number of decimal places in the displayed value, and a font list for the title and value.

Two convenience routines, XmScaleGetValue and XmScaleSetValue, allow the application to get and set the value.

By default, a Scale has no labels or tic marks along the rectangle in which the slider moves. The application can add these by creating a series of widgets—such as LabelGadgets or SeparatorGadgets—as children of the Scale. For example, LabelGadgets could display values at intervals between the minimum and maximum, or SeparatorGadgets could display short lines as tic marks. The Scale positions any children, in order of creation, along the rectangle containing the slider, as follows:

The following example creates a Scale with five tic marks:

#define NUM_TICS 5
Widget          parent, scale, tics[NUM_TICS];
Arg             args[10];
Cardinal        i, n;
unsigned char   scale_orientation, tic_orientation;
Dimension       tic_long_dim = 10, tic_short_dim = 5;
Dimension       tic_width, tic_height;
char            tic_name[10];
...
scale = XmCreateScale(parent, "scale", args, n);
XtManageChild(scale);
...
n = 0;
XtSetArg(args[n], XmNorientation, &scale_orientation);   n++;
XtGetValues(scale, args, n);
if (scale_orientation == XmHORIZONTAL) {
    tic_orientation = XmVERTICAL;
    tic_width = tic_short_dim;
    tic_height = tic_long_dim;
} else {
    tic_orientation = XmHORIZONTAL;
    tic_width = tic_long_dim;
    tic_height = tic_short_dim;
}
for (i = 0; i < NUM_TICS; i++) {
    sprintf(tic_name, "tic_%d", i);
    n = 0;
    XtSetArg(args[n], XmNseparatorType, XmSINGLE_LINE);  n++;
    XtSetArg(args[n], XmNorientation, tic_orientation);  n++;
    XtSetArg(args[n], XmNwidth, tic_width);              n++;
    XtSetArg(args[n], XmNheight, tic_height);            n++;
    tics[i] = XmCreateSeparatorGadget(scale, tic_name,
                                        args, n);
}
XtManageChildren(tics, NUM_TICS);
...

A List is an array of textual items from which the user selects one or more entries. Each item is a compound string. List has four modes, controlled by the XmNselectionPolicy resource, for selecting items:

When the user makes a selection, the List invokes one of four callback lists, depending on the selection policy:

By default, the List does not invoke a callback list when the List is in Single Select or Extended Select mode and the user drags the mouse cursor over a new item. It does invoke the callbacks when the user releases the mouse button. If XmNautomaticSelection is True, the List invokes the callbacks while the user is dragging the mouse.

The widget data passed to selection callback routines contains both the selected items—the compound strings—and integers representing the positions within the list of the selected items. The first item in the list is at position 1, the second item at position 2, and so on.

List has another callback list, XmNdefaultActionCallback, which it invokes when the user double clicks or presses KActivate on an item. The widget data passed to these callback routines contains only the item at the location cursor and its position, not the selected items. When the user performs the default action via a double click, the List calls the appropriate selection callbacks on the first click and the XmNdefaultActionCallback callbacks on the second click.

List includes several other sets of resources:

A ScrolledList is a List inside a ScrolledWindow. The application can use XmCreateScrolledList to create one.

In addition to its resources, List has a variety of convenience routines that allow the application to add, remove, select, and deselect items; specify the first or last visible item; find the position of an item or the positions of the selected items; set Add Mode; and scroll the List horizontally.

Text is a widget for displaying and, optionally, editing text. When the Text is editable and the user presses a key that represents a text character, that character is inserted into the text. Other translations and actions allow the user to navigate or to select, cut, copy, paste, or scroll the text.

For more information on Text and TextField, see Chapter 8, "Text."