Name

DwtMenu, DwtMenuCreate, DwtMenuPulldownCreate, DwtMenuPopupCreate − Creates a menu widget to contain other menu items (subwidgets) for the display of application menus. 

Creates a pull-down (pop-up) menu. 

Creates a pop-up menu (MB2 only). 

Syntax

Widget DwtMenu(parent_widget, name, x, y, format,
                orientation, entry_callback, map_callback,
                help_callback)
     Widget parent_widget;
     char *name;
     Position x, y;
     int format;
     unsigned char orientation;
     DwtCallbackPtr entry_callback;
     DwtCallbackPtr map_callback;
     DwtCallbackPtr help_callback;

Widget DwtMenuCreate (parent_widget, name,
                     override_arglist, override_argcount)
     Widget parent_widget;
     char *name;
     ArgList override_arglist;
     int override_argcount;

Widget DwtMenuPulldownCreate (parent_widget, name,
                              override_arglist,
                              override_argcount)
     Widget parent_widget;
     char *name;
     ArgList override_arglist;
     int override_argcount;

Widget DwtMenuPopupCreate (parent_widget, name,
                           override_arglist, override_argcount)
     Widget parent_widget;
     char *name;
     ArgList override_arglist;
     int override_argcount;

Arguments

parent_widget
Specifies the parent widget ID.

nameSpecifies the name of the created widget. 

xSpecifies the placement, in pixels, of the left side of the widget window relative to the inner upper left corner of the parent window.  This argument sets the DwtNx core widget attribute. 

ySpecifies, in pixels, the placement of the upper left corner of the widget window relative to the inner upper left corner of the parent window.  This argument sets the DwtNy core widget attribute. 

formatSpecifies the type of menu widget.  You can pass DwtMenuPopup, DwtMenuPulldown, or DwtMenuWorkArea. 

orientationSpecifies whether the menu list is vertical or horizontal.  You can pass DwtOrientationHorizontal or DwtOrientationVertical.  This argument sets the DwtNorientation attribute associated with DwtMenuCreate. 

entry_callback
If this callback is defined, all menu entry activation callbacks are revectored to call back through this callback. If this callback is NULL, the individual menu entry callbacks work as usual. For this callback, the reason is DwtCRActivate.  This argument sets the DwtNentryCallback attribute associated with DwtMenuCreate. 

map_callbackSpecifies the callback function or functions called when the window is about to be mapped.  For this callback, the reason is DwtCRMap.  The map_callback argument is supported only if format is DwtMenuPopup or DwtMenuPulldown.  The map_callback argument is ignored if format is DwtMenuWorkArea. 

This argument sets the DwtNmapCallback attribute associated with DwtMenuCreate. 

help_callbackSpecifies the callback function or functions called when a help request is made.  This argument sets the DwtNhelpCallback common widget attribute. 

override_arglist
Specifies the application override argument list.

override_argcount
Specifies the number of attributes in the application override argument list (override_arglist). 

Description

The DwtMenu and DwtMenuCreate functions create an instance of a menu widget and return its associated widget ID.  The DwtMenuPulldownCreate function creates an instance of a pull-down menu widget and returns its associated widget ID.  The DwtMenuPopupCreate function creates an instance of a pop-up menu widget and returns its associated widget ID.  A menu is a composite widget that contains other widgets (push buttons, pull-down menus, toggle buttons, labels, and separators).  The subwidgets handle most I/O that display information and query the user for input.  The menu widget provides no input semantics over and above the semantics of its subwidgets.  The menu widget works with these widget subclasses: push buttons, toggle buttons, pull-down menu entries, labels, and separators.  If DwtNentryCallback is non-NULL when activated, all subwidgets call back to this callback.  Otherwise, the individual subwidgets handle the activated callbacks. 

Inherited Attributes

The following table lists the attributes inherited by the menu widget. 

The following table lists the attributes inherited by the pull-down menu and pop-up menu widgets. 

Widget-Specific Attributes

The following table lists the widget-specific attributes for the menu widget.  Descriptions of these attributes follow the table. 

DwtNspacingSpecifies in pixels the spacing between menu bar entry windows. 

DwtNmarginHeight
Specifies the number of pixels remaining around the entries. The height is the number of blank pixels above the first entry and below the last entry (for vertical menus).

DwtNmarginWidth
Specifies the number of pixels remaining around the entries. The width is the number of blank pixels between the left and right edges of the menu and the border of the entries.

DwtNorientation
Specifies whether the menu list is vertical or horizontal. You can pass DwtOrientationHorizontal or DwtOrientationVertical. 

DwtNadjustMargin
Specifies a boolean value that indicates whether the inner minor dimension margins of all entries should be set to the same value.

All label subclass widgets have two types of margins.  The two outer margins (DwtNmarginWidth and DwtNmarginHeight) are symmetrical about the center of the widget.  The number of pixels specified in DwtNmarginWidth are blank to the right and the left of the widget.  The four inner margins (DwtNmarginLeft, DwtNmarginRight, DwtNmarginTop, and DwtNmarginBottom) specify the number of pixels to leave on each side inside the outer margins. 

The outer margins are used to accommodate such things as the border highlighting of widgets.  The inner margins are used to accommodate such things as pull-down widget hot spots and toggle button indicators. 

If True, all entries in a given column or row will have exactly the same minor dimension margins.  (If DwtNorientation is DwtOrientationHorizontal, the minor dimension is vertical; if DwtNorientation is DwtOrientationVertical, the minor dimension is horizontal.)  All margins will have the value of the largest individual margin in the group.  This keeps the left edge of text lined up, regardless of whether some entries have toggle indicators. 

DwtNentryBorder
Specifies the border width of windows on the entry widgets.

DwtNmenuAlignment
Specifies a boolean value that, when True, indicates all entries are aligned.  If False, entry alignment is unchanged.  This is applied only to subclasses of labelwidgetclass. 

DwtNentryAlignment
Specifies the type of label alignment that is enforced for all entries when DwtNmenuAlignment is True.  You can pass DwtAlignmentCenter (center alignment), DwtAlignmentBeginning (alignment at the beginning), or DwtAlignmentEnd (alignment at the end). 

DwtNmenuPacking
Specifies how to pack the entries of a menu into the whole menu. The value of DwtNorientation determines the major dimension.  You can pass DwtMenuPackingTight, DwtMenuPackingColumn, or DwtNmenuPackingNone. 

DwtMenuPackingTight indicates that given the current major dimension of the menu, entries are placed one after the other until the menu must wrap.  When the menu wraps, it extends in the minor dimension as many times as required. 

Each entry’s major dimension is left unaltered; its minor dimension is set to the same value as the greatest entry in that particular row or column.  Note that the minor dimension of any particular row or column is independent of other rows or columns. 

DwtMenuPackingColumn indicates that all entries are placed in identically sized boxes.  The box is based on the size of the largest entry while the value of DwtNmenuNumColumns determines how many boxes are placed in the major dimension before extending in the minor dimension. 

DwtNmenuPackingNone indicates that no packing is performed.  The DwtNx and DwtNy attributes of each entry are left alone and the menu attempts to become large enough to enclose all entries. 

DwtNmenuNumColumns
Specifies the number of minor dimension extensions that will be made to accommodate the entries. This attribute is used only if DwtNmenuPacking is set to DwtMenuPackingColumn. 

For menus with an orientation of DwtOrientationVertical, this attribute indicates how many columns will be built.  The number of entries per column will be adjusted to maintain this number of columns (if possible).  For menus with an orientation of DwtOrientationHorizontal, this attribute indicates how many rows will be built. 

DwtNmenuRadioSpecifies a boolean value that, when True, indicates that when one button is already on and another button is turned on, the first button is turned off automatically. 

DwtNradioAlwaysOne
Specifies a boolean value that indicates if the radio button exclusivity should also ensure that one button must always be on. If True, when the only radio button on is turned off, it will automatically be turned back on.  Note that this attribute has no effect unless DwtNmenuRadio is True. 

DwtNmenuIsHomogeneous
Specifies a boolean value that indicates if the menu should enforce exact homogeneity among the children of this menu. If True, only the DwtNmenuEntryClass class (not subclass but exact class) will be allowed as children of this menu. 

DwtNmenuEntryClass
Specifies the only widget class that can be added to the menu. For this to occur, the DwtNmenuIsHomogeneous attribute must be True.  All other widget classes will not be added to the menu. 

DwtNmenuHistory
Holds the widget ID of the last menu entry that was activated. If DwtNmenuRadio is True, DwtNmenuHistory holds the widget ID of the last toggle button to change from off to on.  This attribute may be set to precondition option menus and pop-up menus

DwtNentryCallback
If this callback is defined, all menu entry activation callbacks are revectored to call back through this callback. If this callback is NULL, the individual menu entry callbacks work as usual. For this callback, the reason is DwtCRActivate. 

DwtNmenuHelpWidget
If non-NULL, the help menu widget points to the menu item to be placed in the lower right corner of the menu bar.

DwtNchangeVisAtts
Specifies a boolean value that, when True, indicates that a menu widget can optionally make these changes to its children: (1) Set the border to a uniform widget; (2) align labels; (3) make margins for the border highlight at least 2 pixels wide; (4) set the indicator shape to oval for toggle buttons in radio boxes; (5) set DwtNvisibleWhenOff to False for toggle buttons. 

When DwtNchangeVisAtts is False, a menu widget cannot make any of these changes. 

DwtNmenuExtendLastRow
Specifies the boolean value that indicates whether the active area of each menu entry extends to the width of the menu (for vertical menus) or the height of the menu (for horizontal menus).

If True for vertical menus, all menu entries extend to the menu width; if False, menu entries vary in length depending on the length of the label in the menu entry.  If True for horizontal menus, all menu entries extend to the menu height; if False, menu entries vary in height, depending on the length of the label in the menu entry. 

The following table lists the widget-specific attributes for the pull-down and pop-up menu widgets.  Descriptions of these attributes follow the table. 

DwtNmapCallback
Specifies the callback function or functions called when the menu is mapped.

DwtNunmapCallback
Specifies the callback function or functions called when the menu is unmapped.

Return Value

These functions return the ID of the created widget. 

Callback Information

The following structure is returned to your callback:

typedef struct {
int reason;
XEvent *event;
Widget s_widget;
char *s_tag;
char *s_callbackstruct;
} DwtMenuCallbackStruct;

The reason member is set to a constant that represents the reason why this callback was invoked. For this callback, the reason member can be set to:

The event member is a pointer to the Xlib structure XEvent, which describes the event that generated this callback.  This structure is a union of the individual structures declared for each event type.  For information on XEvent and event processing, see the Guide to the Xlib Library: C Language Binding.  The s_widget member is set to the ID of the activating subwidget.  The s_tag member is set to the tag supplied by the application programmer when the subwidget callback function was specified.  The s_callbackstruct member is set to the subwidget’s callback structure. 

See Also

Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

Subroutines