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

Labels, Buttons, and Separators

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

Labels

Labels provide the ability to display static (uneditable) text or a pixmap. Your application can use a Label or LabelGadget to display a message, title, or description. Label and LabelGadget also serve as superclasses for button widgets and gadgets. However, unlike button widgets, Label provides no additional callbacks beyond those that it inherits from Primitive.

The application can specify the following characteristics of Labels, LabelGadgets, and their subclasses:

  1. The compound string or pixmap to be displayed. When using a pixmap, the application can supply a separate pixmap to be displayed when the widget is insensitive.

  2. The render table that describes the attributes of the compound string.

  3. The positioning of the text or pixmap within the widget. One set of resources determines the space allocated for the margins; another determines the distance between the margins and the text or pixmap inside. The XmNalignment and XmNlayoutDirection resources together determine whether the text or pixmap is centered or is left or right justified within the widget.

  4. A resource, XmNrecomputeSize, that determines whether the widget attempts to remain large enough to contain the text or pixmap. When this resource is True and a resource that affects the size of the text or pixmap, the margins, or the widget itself is changed, the widget tries to resize itself to be just large enough to contain the text or pixmap.

    In addition, Label and LabelGadget provide the following facilities for button subclasses in menus:

    1. A keysym used as a mnemonic to select the button. The user can activate the button by pressing the mnemonic key when the button is visible.

    2. An accelerator, a KeyPress event by which the user can activate the button whether or not it is visible. Accelerators are supported only for PushButtons and ToggleButtons in PulldownMenus and PopupMenus.

    3. Translations and actions for keyboard traversal within the menu or menu system.

      A Label or LabelGadget can be the source of a drag and drop operation, but cannot be the destination. In other words, you can drag a value from a Label or LabelGadget, but you cannot drop a value into a Label or LabelGadget. The XmNenableUnselectableDrag resource of XmDisplay holds a Boolean value. If this value is True, then users can drag from a Label or LabelGadget. If this value is False, then users cannot drag from a Label or LabelGadget.

      4. Buttons

      A button is a basic control that performs some action when the user activates it. Buttons commonly appear in menus, RadioBoxes, CheckBoxes, SelectionBoxes, and MessageBoxes. This section describes some of the functions of each subclass.

      CascadeButtons

      A CascadeButton or CascadeButtonGadget is used inside a menu and, when activated, usually causes a PulldownMenu to appear. CascadeButtons have the following resources and behavior:

      1. A pixmap displayed at one end of the widget in a PopupMenu or PulldownMenu to indicate that activating the CascadeButton posts another menu.

      2. A resource, XmNsubMenuId, that holds the widget ID of the PulldownMenu posted when the user activates the button.

      3. XmNactivateCallback callbacks, which the widget invokes when the user activates it, and XmNcascadingCallback callbacks, which the widget invokes just before posting a PulldownMenu.

      4. A resource to provide a delay between the time the mouse enters the widget and the time it posts a menu.

      5. Translations and actions to activate the widget and to post and unpost PulldownMenus. In general, pressing Btn1 or dragging Btn1 into the widget posts the PulldownMenu. Releasing Btn1 in the widget causes the PulldownMenu to remain posted and enables keyboard traversal. When keyboard traversal is enabled, pressing osfActivate or osfSelect in the widget posts the PulldownMenu and enables keyboard traversal in that menu.

        6. PushButtons

        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. PushButtons provide the following behavior:

        1. Callbacks that the widget invokes when it is armed, disarmed, and activated. The application usually provides only an XmNactivateCallback procedure to perform the action associated with the button.

        2. Resources to provide a color or pixmap to be displayed when the button is armed and not inside a menu. When a button in a menu is armed, the top and bottom shadows switch colors.

        3. A resource to determine whether or not the widget considers multiple mouse clicks distinct from single mouse clicks.

        4. A resource to determine whether or not the button is marked as the default button when outside a menu. In a BulletinBoard, the default button is the one activated when the user presses osfActivate and no other button has keyboard focus. The default button has a distinctive shadow whose thickness is controlled by the XmNdefaultButtonShadowThickness resource and whose appearance is controlled by the XmNdefaultButtonEmphasis resource of XmDisplay.

        5. Translations to arm, disarm, and activate the button. In general, a button is activated upon pressing Btn1 while on a button, or dragging Btn1 or traversing to a button while in menu. Releasing Btn1 or pressing osfActivate (in a menu) or osfSelect (in the widget) activates and disarms the button.

          6. ToggleButtons

          ToggleButtons and ToggleButtonGadgets are typically in one of two states: they are either "set" or "unset." In addition, ToggleButtons and ToggleButtonGadgets can also be in an indeterminate state; that is, neither set nor unset. They can appear in menus or in nonmenu RowColumn WorkAreas, including RadioBoxes and CheckBoxes. In a RadioBox only one ToggleButton at a time can be on; in a CheckBox more than one ToggleButton can be on. ToggleButtons can have indicators with distinctive shapes to distinguish whether or not more than one button at a time can be set. However, it is the RowColumn parent, not the ToggleButton, that controls this behavior.

          ToggleButtons have the following characteristics:

          1. Callbacks that the widget invokes when it is armed or disarmed and when it changes state. The widget invokes the XmNvalueChangedCallback callbacks when the button's state changes from set to unset or from unset to set.

          2. Resources to control the appearance of the indicator. If XmNindicatorOn is False or if XmNvisibleWhenOff is False and the button is in the unset state no indicator is displayed. Otherwise, XmNindicatorType determines whether the indicator shows that only one or more than one button at a time can be set.

          3. A color to be displayed when the button is armed and XmNfillOnSelect is True and another color to be displayed when the button is not set.

          4. Pixmaps to be displayed when the button is selected and the Label or LabelGadget superclass's XmNlabelType is XmPIXMAP.

          5. Translations to arm and disarm the button and to change its state. In general, a button is activated upon pressing Btn1 while on a button, or dragging Btn1 or traversing to a button while in menu. Releasing Btn1 or pressing osfActivate (in a menu) or osfSelect (in the widget) activates and disarms the button.

            6. DrawnButtons

            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. Like a PushButton, it has translations and actions to arm, disarm, and activate the button and invoke the corresponding callbacks. If XmNpushButtonEnabled is True, it draws the shadow so that the button appears pressed in when armed and popped out when disarmed.

            Other than this, the application must manage the button's visual appearance. It has XmNexposeCallback and XmNresizeCallback callbacks to notify the application that the button has been exposed or resized and therefore needs to be redrawn. The application must be careful not to draw within the button's shadows or highlight areas. The application can use a clipping rectangle in the widget's graphics context that takes account of the button's XmNhighlightThickness and XmNshadowThickness.

            ArrowButtons

            An ArrowButton or ArrowButtonGadget is a button with an arrow graphic and a shadow. A resource controls the direction of the arrow. Unlike other buttons, it is not a subclass of XmLabel or XmLabelGadget, but it has some of the same behavior as other buttons. It has callbacks that the widget invokes when armed, disarmed, or activated. It has translations and actions similar to those of other buttons to arm, disarm, or activate the button.

            Separators

            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. Resources control its orientation and the type of line it draws. One line style consists of no line at all. This allows the application to control the appearance of the separator by setting its XmNbackgroundColor or XmNbackgroundPixmap.

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