Motif Widget Writer's Guide Migration Version

Motif 2.1 Widget Writer's Guide

XmQTtakesDefault

A button widget holding this trait can change its appearance to show that it is the default button

Format

#include <Xm/TakesDefT.h>
 
typedef struct {
        	int                             version;
        	XmTakesDefaultNotifyProc        showAsDefault;
} XmTakesDefaultTraitRec, *XmTakesDefaultTrait;
void
(*XmTakesDefaultNotifyProc)WidgetXtEnum

DESCRIPTION

You will use the XmQTtakesDefault trait if you are writing a PushButton-style primitive widget or a DialogBox-style manager widget.

A DialogBox widget displays several PushButton-style children. For example, a typical DialogBox widget might display three PushButton widgets: an OK button, a Cancel button, and a Help button. One of these PushButton-style children should be the default button. The default button is the PushButton-style child that is activated when the user presses Return anywhere in the widget. (The parent_process method of the DialogBox is responsible for detecting the activation event.)

A PushButton-style widget must be capable of altering its appearance to show that it is the default choice. Most PushButton-style widgets do this by highlighting their borders in a special way.

If you are writing a PushButton-style widget, then your widget should hold the XmQTtakesDefault trait. This trait announces to DialogBox widgets that the child is capable of changing its appearance to show that it is the default choice. Conversely, if you are writing a DialogBox widget, then your DialogBox widget should examine its button children for this trait.

The following standard Motif primitives hold this trait:

XmPushButton

XmPushButtonGadget

In addition, the ExmCommandButton demonstrates how to install this trait and how to define a showAsDefault trait method.

The following standard Motif managers examine their children widgets for this trait and call the showAsDefault trait method:

XmBulletinBoard and all its subclasses

The showAsDefault Trait Method

void showAsDefaultWidget
childWidgetXtEnum state

Every PushButton-style widget holding the XmQTtakesDefault trait must provide a showAsDefault trait method. The DialogBox that manages the PushButton-style widgets will call the XmQTtakesDefault trait method, each time passing a different value of state. The typical sequence of calls from the DialogBox manager is as follows:

The DialogBox calls the showAsDefault trait method of each child widget, specifying a state of XmDEFAULT_READY. This message tells the child to prepare to become the default button. The Motif Style Guide does not mandate a particular way of handling this message, so your widget may visually do as you please. One possible response would be to increase the widget's internal margins. (Calling XmDEFAULT_READY helps the manager avoid future unnecessary geometry requests.)

The DialogBox calls the showAsDefault trait method of the chosen default child, specifying a state of XmDEFAULT_ON. This message tells the child to become the default button. The child must change its visual appearance in some way to show the user that it is now the default button. For example, the ExmCommandButton demonstration widget increases its shadow thickness to show that it is the default. Another widget might display some sort of icon (perhaps an arrow) to symbolize that it is the default button.

If the default child widget changes, then the DialogBox calls the showAsDefault trait method twice. The first call specifies a state of XmDEFAULT_OFF in order to turn off one default button. The second call specifies a state of XmDEFAULT_ON in order to turn on the new default button. Upon receiving the XmDEFAULT_OFF message, the child widget must change its appearance to show that it is no longer the default.

XmDEFAULT_FORGET resets the visual appearance of a child widget so that it looks as it did prior to the XmDEFAULT_READY call.

childWidget

Specifies the child widget holding this trait.

state

Specifies one of the following states: XmDEFAULT_READY, XmDEFAULT_ON, XmDEFAULT_OFF, and XmDEFAULT_FORGET.

RELATED

XmBulletinBoard(3), XmPushButton(3), and ExmCommandButton(3).