[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Programmer's Guide

Building Blocks: Primitive Widgets and Gadgets

Primitive widgets are the fundamental units of input and output in Motif. Primitives are commonly the widgets at the leaves of an application's widget hierarchy. These widgets do not have children of their own. The name primitive does not imply simplicity; some primitives, such as the Text widget, have quite complicated behavior. Primitive is meant to contrast with manager, a widget that usually has children. It also suggests a basic component from which composite widgets are built. Primitives are often referred to as controls.

The XmPrimitive Motif widget class is the superclass for all primitives. XmPrimitive is itself a subclass of the fundamental Xt widget class, Core. Core has resources that describe the widget's width, height, and x and y coordinates with respect to its parent. Other Core resources control characteristics of the window, such as its background color; whether or not the widget can receive input events; and the mapping that Xt uses to translate events into calls to the widget's action routines.

XmPrimitive adds two groups of features to the Core class. One group consists of resources to control additional visual characteristics, including the characteristic three-dimensional shadow and a highlighting rectangle that can appear when the widget is the focus for keyboard input. The second group controls keyboard traversal, the use of the keyboard to move focus from one widget to another. This group includes several resources and a set of translations and actions that allow the user to move the keyboard focus to another widget by pressing an arrow key. XmPrimitive also provides callbacks to let the application provide help information when the user presses osfHelp.

The XmGadget widget class is the superclass for all gadgets. XmGadget is a subclass of the Xt widget class RectObj. This class provides resources to determine the dimensions and position of the gadget's rectangular area inside its parent. XmGadget is equivalent to XmPrimitive, with two exceptions:

  1. Gadgets have color and pixmap resources, but if these resources are not set, gadgets inherit their values from their parents.

  2. Gadgets do not have translations or actions. A gadget's parent controls keyboard traversal from the gadget to another widget, and it dispatches events to the gadget when appropriate.

    XmPrimitive and XmGadget are used only as superclasses for other classes of widgets. XmPrimitive and XmGadget are not instantiable; that is, an application cannot create an actual widget that is an instance of either of these classes. Motif has several specialized subclasses of primitives and gadgets, summarized in the following sections.

  3. Label and Separator

    Labels provide the ability to display static (uneditable) text or a pixmap. A Label or LabelGadget itself is useful for displaying a message, title, or description. Label and LabelGadgets are also superclasses for buttons used as menu items, toggles, or controls.

    A Label can display either text or a pixmap. When a Label displays text, it uses a construct called a compound string. This is a stream of components that represents zero or more pieces of text, each with an associated rendition tag and display direction. When Motif displays the compound string, it matches each tag with a tag in the widget's render table and uses the corresponding font or fonts, colors, and other features so described.

    A Separator or SeparatorGadget separates controls or groups of controls. It usually appears as a horizontal or vertical line and supports several styles of line drawing.

    Labels and Separators are described in more detail in Chapter 5.


    A button is a basic control that performs some action when the user activates it. Buttons commonly appear in menus, RadioBoxes and CheckBoxes, SelectionBoxes and MessageBoxes. Motif has the following classes of buttons:

    1. A CascadeButton or CascadeButtonGadget is used inside a menu and, when activated, usually causes a PulldownMenu to appear.

    2. A PushButton or PushButtonGadget can appear either inside or outside a menu. It performs some action determined by the application. When a PushButton is armed, or ready to be activated, it changes its appearance so that it looks as if the user has pressed it in. When it is disarmed, it reverts to the appearance of extending out.

    3. ToggleButtons and ToggleButtonGadgets have different states: like toggle switches, they are either on or off. They can appear in menus or in nonmenu RowColumn WorkAreas, including RadioBoxes and CheckBoxes. They can also have an indeterminate state.

    4. A DrawnButton is an empty button surrounded by a shadow border. It is intended to be used as a PushButton but with graphics drawn by the application.

      Buttons are described in more detail in Chapter 5.

    5. ScrollBar

      A widget can act as a viewport onto a virtual scroll. The scroll is a plane with text, graphics, a list of items, or other contents. The viewport is a fixed-size window onto a portion of the scroll.

      A 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.

      ScrollBars are described in more detail in Chapter 5.


      A List is an array of textual items from which the user selects one or more entries. Each item is a compound string. A List has four modes for selecting items: two that allow the user to select one item at a time, and two that allow the user to select more than one item in either contiguous or discontiguous ranges.

      Lists are described in more detail in Chapter 5.


      The Text widget is available for displaying and possibly editing text, and represents text as a multibyte or wide-character string. When the widget 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.

      The text can be multiline or constrained to be a single line. In a single-line widget, actions that move up and down one line in a multiline widget instead traverse to another widget, and pressing osfTab moves the keyboard focus to another group of widgets instead of inserting a Tab character.

      A TextField is essentially the same as a Text widget in single-line mode, except that its performance is optimized for single-line text operations.

      Text is described in more detail in Chapters 5 and 10.

      [ Previous | Next | Contents | Glossary | Home | Search ]