Solaris Common Desktop Environment: Programmer's Guide

Menu Button Widget (DtMenuButton)

Use the DtMenuButton widget to provide menu-cascading functionality outside of a menu pane.

DtMenuButton widget is a command widget that complements the menu cascading functionality of an XmCascadeButton widget. As a complement to XmCascadeButton widget, it can only be instantiated outside a MenuBar, Pulldown, or Popup (use XmCascadeButton widget inside a MenuPane.) Figure 7-1 shows examples of a DtMenuButton widget.

Figure 7-1 Examples of menu button widget (DtMenuButton)

Library and Header Files

The DtMenuButton widget is in the libDtWidget library. The header file is Dt/MenuButton.h.

Demo Program

A demo containing an example of the DtMenuButton widget is in /usr/dt/examples/dtwidget/controls.c.

Convenience Functions

DtCreateMenuButton() is a convenience function that creates a Common Desktop Environment widget.

DtMenuButton widget is a subclass of XmLabel class. Visually, DtMenuButton widget has a label string and a menu glyph. The menu glyph always appears on the right end of the widget and, by default, is a downward pointing arrow.

DtMenuButton widget has an implicitly created submenu attached to it. The submenu is a pop-up menu and has this DtMenuButton widget as its parent. The name of the implicitly created submenu is obtained by prefixing submenu_ to the name of this DtMenuButton widget. You can obtain the widget ID of the submenu by setting an XtGetValues on DtNsubMenuId resource of this DtMenuButton widget. The implicitly created submenu must not be destroyed by the user of this widget.

The submenu can be popped up by pressing the menu post button (see XmNmenuPost resource of XmRowColumn) anywhere on the DtMenuButton widget or by pressing the Motif Cancel key (usually Escape).

Classes

DtMenuButtonWidget inherits behavior and resources from Core, XmPrimitive, and XmLabel classes.

The class pointer is dtMenuButtonWidgetClass.

The class name is DtMenuButtonWidget.

DtMenuButtonWidget does not support subclassing.

Resources

DtMenuButtonWidget provides the following resources. Table 7-1 shows the class, type, default, and access for these resources.

DtNcascadingCallback specifies the list of callbacks that are called before the attached submenu is displayed.
DtNcascadePixmap specifies the pixmap that is displayed as the menu glyph. If no pixmap is specified, a downward pointing arrow is displayed.
DtNsubMenuId specifies the widget ID of the pop-up menu pane to be associated with this DtMenuButton widget. You must create the pop-up menu pane with this DtMenuButton as its parent. You cannot specify this resource when the widget is created because the submenu is automatically destroyed by this widget when the resource is set.

See the DtMenuButtonWidget(3X) man page for more information.

The codes in the access column show if you can:

Set the resource at creation time (C)
Set by using XtSetValues (S)
Retrieve by using XtGetValues (G)

Table 7-1 DtMenuButtonWidget Resources


Name	Class	Type	Default	Access
`DtNcascadingCallback`	`DtCCallback`	`XtCallbackList`	`NULL`	`C`
`DtNcascadePixmap`	`DtCPixmap`	`Pixmap`	`XmUNSPECIFIED_PIXMAP`	`CSG`
`DtNsubMenuId`	`DtCMenuWidget`	`Widget`	`NULL`	`SG`

Callback Structures

The callback structure follows and is described in Table 7-2.

typedef struct {
 	int 	reason;
 	XEvent	*event;
} XmAnyCallbackStruct;

Table 7-2 DtMenuButtonWidget Callback Structures


Structure	Description
`reason`	Returns reason why the callback was invoked.
`event`	Points to the `XEvent` that triggered the callback or `NULL` if the callback was not triggered by an XEvent.

Example of DtMenuButton Widget

The following example shows how to create and use a DtMenuButton widget. You can find this code as part of the controls.c demo in the /usr/dt/examples/dtwidget directory.

/*
  * Example code for DtMenuButton
  */  

#include Dt/DtMenuButton.h  

/* MenuButton custom glyph */  

#define menu_glyph_width 16 
#define menu_glyph_height 16 
static unsigned char menu_glyph_bits[] = {
 	0xe0, 0x03, 0x98, 0x0f, 0x84, 0x1f, 0x82, 0x3f, 0x82, 0x3f, 0x81,
 	0x7f, 0x81, 0x7f, 0xff, 0x7f, 0xff, 0x40, 0xff, 0x40, 0xfe, 0x20, 0xfe,
 	0x20, 0xfc, 0x10, 0xf8, 0x0c, 0xe0, 0x03, 0x00, 0x00};

static void CreateMenuButtons(Widget parent) {
     Widget menuButton, submenu, titleLabel, button;
     Pixmap cascadePixmap;
     Pixel fg, bg;
     Cardinal depth;
     XmString labelString;
     Arg args[20];
     int i, n;

      /* Create title label */

     labelString = XmStringCreateLocalized("MenuButton Widget");
     n = 0;
     XtSetArg(args[n], XmNlabelString, labelString); n++;
     titleLabel = XmCreateLabel(parent, "title", args, n);
     XtManageChild(titleLabel);
     XmStringFree(labelString);

     /*
      * Create a MenuButton.
      * Add push buttons to the built-in popup menu.
      */

     labelString = XmStringCreateLocalized("Action"); n = 0;
     XtSetArg(args[n], XmNlabelString, labelString); n++;
     menuButton = DtCreateMenuButton(parent, "menuButton1", args, n);
     XtManageChild(menuButton);
     XmStringFree(labelString);
     XtVaGetValues(menuButton, DtNsubMenuId, &submenu, NULL);
     button = XmCreatePushButton(submenu, "Push", NULL, 0);
     XtManageChild(button);
     button = XmCreatePushButton(submenu, "Pull", NULL, 0);
     XtManageChild(button);
     button = XmCreatePushButton(submenu, "Turn", NULL, 0);
     XtManageChild(button);

     /*
      * Create a MenuButton.
      * Replace the built-in popup menu with a tear-off menu.
      * Add a custom pixmap in the colors of the MenuButton.
      */

     labelString = XmStringCreateLocalized("Movement");
     n = 0;
     XtSetArg(args[n], XmNlabelString, labelString); n++;
  	  menuButton = DtCreateMenuButton(parent, "menuButton1", args, n);
     XtManageChild(menuButton);
     XmStringFree(labelString);

     /* Create a tear-off menu */

     n = 0;
     XtSetArg(args[0], XmNtearOffModel, XmTEAR_OFF_ENABLED); n++;
     submenu = XmCreatePopupMenu(menuButton, "submenu", args, n);
     button = XmCreatePushButton(submenu, "Run", NULL, 0);
     XtManageChild(button);
     button = XmCreatePushButton(submenu, "Jump", NULL, 0);
     XtManageChild(button);
     button = XmCreatePushButton(submenu, "Stop", NULL, 0);
     XtManageChild(button);

     XtVaSetValues(menuButton, DtNsubMenuId, submenu, NULL);

     /* Create a pixmap using the menu button's colors and depth */

     XtVaGetValues(menuButton,
 			XmNforeground, &fg,
 			XmNbackground, &bg,
 			XmNdepth, &depth,
 			NULL);

     cascadePixmap = XCreatePixmapFromBitmapData(XtDisplay
 	  (menuButton),DefaultRootWindow(XtDisplay
 	  (menuButton)),
 	  (char*)menu_glyph_bits,
 	  menu_glyph_width, menu_glyph_height,
     fg, bg, depth);
     XtVaSetValues(menuButton, DtNcascadePixmap, cascadePixmap,
 	  NULL); 
}