Volume 6A: Motif Programming Manual

single−purpose widgets that you can create directly.

The widgets in this latter group are collectively referred to as primitive widgets −− not because they are simple, but

because they are designed to work alone. The contrast is not between primitive and sophisticated widgets, but between

primitive and manager widgets. Some of the primitive Motif widget classes have corresponding gadget classes. The

following sections describe the different types of primitive application controls available in the Motif toolkit.

The compound objects in the Motif toolkit are composed of primitive widgets and gadgets. Because an understanding

of these objects relies on an understanding of the primitive widgets, as well as the Motif manager and shell widgets,

we are going to postpone discussing compound objects until later in the chapter.

4.2.1 The Primitive Widget Class

The Primitive widget class is a superclass for all of the Motif primitive widgets. This widget class is a metaclass; it

serves only to define certain common behavior used by all its sub-classes, so one never instantiates a widget directly

from the Primitive class. This statement is somewhat like saying that hammer is a class of object, but that you never

really have a -generic hammer. You can only have a specific type of hammer, like a claw hammer, a ball peen

hammer, or a sledge hammer. A claw hammer has the prongs in the back behind the hammer−head that allow you to

pull nails out of a wall; a ball peen hammer has a round corner where the claw would be otherwise be; a sledge

hammer is the large, heavyweight hammer used to drive thick nails through concrete or to destroy things.

Just as all hammers have particular characteristics that qualify them as hammers, the Primitive widget class provides

its subclasses with common resources such as window border -attributes, highlighting, and help with keyboard

traversal (so the user can avoid the mouse and navigate through the controls in a window using the keyboard). The

actual widget classes that you use are subclassed from the Primitive class, as shown in the figure.

The Primitive widget class hierarchy

The Primitive class itself inherits even more basic widget behavior from the Xt−defined Core widget class, which

establishes the basic nature of "widgetness." The Core class provides widgets with the capability to have windows and

background colors, as well as translations, actions, and so on. You could actually use a simple Core widget as an

instance and define your own translations and action routines, although this technique is not used frequently.

Complete details are provided in Volume Four, X Toolkit Intrinsics Programming Manual. The Label widget

provides a visual label either as text or as an image in the form of a Pixmap. The text of a Label is an XmString, or

compound string, not a character string (char*). A compound string can be oriented from left−to−right or

4 Overview of the Motif Toolkit 4.2.1 The Primitive Widget Class

46

right−to−left and it can also contain multiple lines and multiple fonts. Chapter 19, Compound Strings, discusses

functions that manipulate compound strings, as well as functions that convert between character strings and compound

strings.

The Label widget does not provide any callback routines, since it does not have any specified behavior. Using Xt, you

could install event translations and action routines to make a Label respond to user input, but the Label widget is not

intended to be used this way. It is only meant to be used to display labels or other visual aids. In Motif 1.2, instances

of Label and all of its subclasses are automatically registered as drag sources for drag and drop operations by the

toolkit.

Label widgets are described in detail in Chapter 11, Labels and Buttons. the figure displays a single Label widget

with multiple lines and multiple fonts.

A Label with multiple lines and fonts

The PushButton widget supports the same visual display capabilities as a Label, since it is subclassed from Label. In

addition, the PushButton provides resources for the programmer to install callback routines that are called when the

user arms, activates, or disarms the button. The PushButton also displays a shadow border that changes in appearance

to indicate when the pointer is in the widget and when it has been activated.

When a PushButton is not selected, it appears to project out towards the user. When the pointer moves into the button,

its border is highlighted. When the user actually selects the button by pressing the first mouse button on it, the button

appears to be pushed in and is said to be armed. The user activates a PushButton by releasing the mouse button while

the button is armed. PushButton widgets are also covered in detail in Chapter 11, Labels and Buttons. the figure

shows some examples of PushButtons.

PushButton widgets

The DrawnButton widget is similar to a PushButton in its functionality and its three−dimensional appearance.

However, the DrawnButton is used when an application wants to draw the text or image directly into the widget's

window, rather than have the widget handle the drawing. If the image is dynamic and changes frequently during the

course of an application, you may want to handle the drawing yourself. The DrawnButton provides additional callback

resources that are called when the button is resized or exposed and additional ways to draw an outlined border. The

DrawnButton widget is discussed in Chapter 11, Labels and Buttons. the figure shows some DrawnButtons.

4 Overview of the Motif Toolkit 4.2.1 The Primitive Widget Class

47

DrawnButtons widgets

The ToggleButton widget displays text or graphics like a Label widget, but it has an additional indicator graphic (a

square or diamond shape) to the left of the label. The indicator shows the state of the ToggleButton: on or off. When

the ToggleButton is on, the indicator is colored and appears to be pushed in. When the button is off, the indicator

appears to project outward. The ToggleButton provides a additional resource for specifying a callback routine that is

called when the user changes the state of the ToggleButton.

One common use of ToggleButtons is to set the application state. In this case, the callback routines typically set

simple Boolean variables internal to the application. ToggleButtons can also be arranged in two different kinds of

groups. In one configuration, known as a RadioBox, only one button in the group of buttons can be chosen at a time.

The other configuration, a CheckBox, allows the user to select any number of buttons. When ToggleButtons are

grouped as a RadioBox, the indicators are diamond−shaped; otherwise, they are square−shaped. ToggleButton

widgets are described in detail in Chapter 11. the figure shows the two different ways that ToggleButtons can be

grouped.

ToggleButtons in a CheckBox and a RadioBox

The CascadeButton widget is a special kind of button that is used to pop up menus. A CascadeButton can only be used

as a child of a RowColumn widget, such as: in a MenuBar as the title of a PulldownMenu, in a PulldownMenu pane as

an item that has a cascading menu associated with it, or as the button in an OptionMenu. The menu that is posted by a

CascadeButton is not a part of the widget itself; the menu is associated with the button through a resource. A

CascadeButton merely provides the label and other visual aids that support the appearance that a menu can pop up

from the object. Even though the CascadeButton widget class is subclassed from Label and could inherit all of its

functionality, Motif imposes restrictions on the labels that a CascadeButton can display. CascadeButton labels cannot

4 Overview of the Motif Toolkit 4.2.1 The Primitive Widget Class

48

contain multiple lines or multiple fonts. Because CascadeButtons are typically used in menus, they do not display

border shadows like other buttons. They do have similar highlighting behavior when selected, however.

CascadeButton widgets are explained in both Chapter 4, The Main Window, and Chapter 15, Menus. Despite the

similarity in its name, the ArrowButton widget is not subclassed from Label like the other button widgets. Like the

remaining widgets described in this section, it is subclassed directly from the Primitive widget class. The

ArrowButton widget contains an image of an arrow pointing in one of four directions: up, down, left, or right. When

the user selects this widget, the ArrowButton provides visual feedback giving the illusion that the button is pressed in

and invokes a callback routine that an application can use to perform application−specific positioning.

In most respects, an ArrowButton can be considered identical to a PushButton, as it is easy enough to provide an

arrow pixmap for a PushButton. Since directional arrows are a common user−interface element, the ArrowButton is

provided as a separate widget class for -simplicity. ArrowButton widgets are covered in detail in Chapter 11, Labels

and Buttons. the figure shows the four variations of the ArrowButton widget.

ArrowButton widgets

The List widget provides a mechanism for the programmer to make a list of text items available to the user for

selection. The user selects items from a List using the mouse or the keyboard. The List widget allows you to specify

whether the user can select a single item or multiple items. While List is a Primitive widget, it is typically created as

part of a ScrolledList compound object using a Motif convenience function. The advantage of the ScrolledList object

is that it provides a ScrollBar when the List grows bigger than the size of its visible area. In Motif 1.2, instances of the

List widget are automatically registered as drag sources for drag and drop operations by the toolkit. We explore the

List widget in detail in Chapter 12, The List Widget. the figure shows a List widget in context with other interface

-elements.

4 Overview of the Motif Toolkit 4.2.1 The Primitive Widget Class

49

A List widget in an application

The ScrollBar widget is one of the more intuitive user−interface elements in the Motif toolkit. ScrollBars are almost

always used as children of a ScrolledWindow widget. When the contents of a window are larger than the viewing

area, a ScrollBar allows the user to scroll the window to view the entire contents.

ScrollBars can be oriented vertically or horizontally. The ScrollBar also provides a number of callback resources that

allow you to control its operation. ScrollBar widgets are discussed in Chapter 9, ScrolledWindows and ScrollBars.

the figure shows both vertical and horizontal ScrollBars.

Horizontal and vertical ScrollBar widgets in a ScrolledWindow

The Separator widget is used as a visual aid to separate adjacent items in a display. A Separator appears as a line

between the objects it is separating; it can be oriented vertically or horizontally. Separators can be used in menus to

separate menu items, in dialog boxes to -separate discrete areas of control, and at various points in an interface for

purely aesthetic -reasons. The Text widget is a complete text editor contained in a widget. The Text widget provides

4 Overview of the Motif Toolkit 4.2.1 The Primitive Widget Class

50