Volume 6A: Motif Programming Manual

callback routines. This interactivity is the principal difference between PushButtons and Labels. There are other visual

differences, but these are adjusted automatically by the PushButton widget using Label resources.

<Xm/PushB.h> and <Xm/PushBG.h> are the header files for PushButton widgets and gadgets, respectively. These

objects can be created using XtVaCreateManagedWidget(), as in the following code fragment:

Widget pushb_w, pushb_g;

pushb_w = XtVaCreateManagedWidget ("name",

xmPushButtonWidgetClass, parent,

resource−value−list,

NULL);

pushb_g = XtVaCreateManagedWidget ("name",

xmPushButtonGadgetClass, parent,

resource−value−list,

NULL);

12.2.1 PushButton Callbacks

The major callback routine associated with the PushButton widget is the XmNactivateCallback. The functions

associated with this resource are called whenever the user activates the PushButton by pressing the left mouse button

over it or by pressing the SPACEBAR when the widget has the keyboard focus.

The other callback routines associated with the PushButton are the XmNarmCallback and the

XmNdisarmCallback. Each function in an arm callback list is called whenever the user presses the left mouse

button when the pointer is over the PushButton. When the PushButton is armed, the top and bottom shadows are

inverted and the background of the button changes to the arm color. The arm callback does not indicate that the button

has been released. If the user releases the mouse button within the widget, then the activate callback list is invoked.

The arm callback is always called before the activate callback, whether or not the activate callback is even called.

When the user releases the button, the disarm callback list is invoked. When the button is disarmed, its shadow colors

and the background return to their normal state. Like the arm callback, the disarm callback does not guarantee that the

activate callback has been invoked. If the user changes her mind before releasing the mouse button, she can move the

mouse outside of the widget area and then release the button. In this case, only the arm and disarm callbacks are

called. However, the most common case is that the user actually selects and activates the button, in which case the arm

callback is called first, followed by the activate callback and then the disarm callback.

The activate callback function is by far the most useful of the PushButton callbacks. It is generally unnecessary to

register arm and disarm callback functions, unless your application has a specific need to know when the button is

pushed and released, even if it is not activated. the source code demonstrates the use of the various PushButton

callbacks. XtSetLanguageProc() is only available in X11R5; there is no corresponding function in X11R4.

XmStringCreateLocalized() is only available in Motif 1.2; XmStringCreateSimple() is the

corresponding function in Motif 1.1.

/* pushb.c −− demonstrate the pushbutton widget. Display one

* PushButton with a single callback routine. Print the name

* of the widget and the number of "multiple clicks". This

* value is maintained by the toolkit.

*/

#include <Xm/PushB.h>

main(argc, argv)

int argc;

12 Labels and Buttons 12.2.1 PushButton Callbacks

314

char *argv[];

{

XtAppContext app;

Widget toplevel, button;

void my_callback();

XmString btn_text;

XtSetLanguageProc (NULL, NULL, NULL);

toplevel = XtVaAppInitialize (&app, "Demos",

NULL, 0, &argc, argv, NULL, NULL);

btn_text = XmStringCreateLocalized ("Push Here");

button = XtVaCreateManagedWidget ("button",

xmPushButtonWidgetClass, toplevel,

XmNlabelString, btn_text,

NULL);

XmStringFree (btn_text);

XtAddCallback (button, XmNarmCallback, my_callback, NULL);

XtAddCallback (button, XmNactivateCallback, my_callback, NULL);

XtAddCallback (button, XmNdisarmCallback, my_callback, NULL);

XtRealizeWidget (toplevel);

XtAppMainLoop (app);

}

void

my_callback(w, client_data, call_data)

Widget w;

XtPointer client_data;

XtPointer call_data;

{

XmPushButtonCallbackStruct *cbs =

(XmPushButtonCallbackStruct *) call_data;

if (cbs−>reason == XmCR_ARM)

printf ("%s: armed0, XtName (w));

else if (cbs−>reason == XmCR_DISARM)

printf ("%s: disarmed0, XtName (w));

else

printf ("%s: pushed %d times0, XtName (w), cbs−>click_count);

}

The callback structure associated with the PushButton callback routines is XmPushButtonCallbackStruct,

which is defined as follows:

typedef struct {

int reason;

XEvent *event;

int click_count;

} XmPushButtonCallbackStruct;

The reason parameter is set to XmCR_ACTIVATE, XmCR_ARM, or XmCR_DISARM depending on the callback that

invoked the callback routine. We use this value to decide what action to take in the callback routine. The event that

caused the callback routine to be invoked is referenced by the event field.

The value of the click_count field reflects how many times the PushButton has been clicked repeatedly. A

repeated button click is one that occurs during a predefined time segment since the last button click. Repeated button

clicks can only be done using the mouse. The time segment that determines whether a button click is repeated is

12 Labels and Buttons 12.2.1 PushButton Callbacks

315