DwtMenu(3Dwt) DwtMenu(3Dwt)
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.
name Specifies the name of the created widget.
x Specifies 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.
y Specifies, 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.
format Specifies the type of menu widget. You can pass DwtMenuPopup, DwtMenuPulldown, or DwtMenuWorkArea.
orientation
Specifies 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 argu-
ment sets the DwtNentryCallback attribute associated with DwtMenuCreate.
map_callback
Specifies 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_callback
Specifies 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 but-
tons, 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.
------------------------------------------------------------------
Attribute Name Data Type Default
------------------------------------------------------------------
Core Attributes
DwtNx Position Determined by the geome-
try manager
DwtNy Position Determined by the geome-
try manager
DwtNwidth Dimension If menu orientation is
DwtOrientationVertical,
default is the maximum
entry DwtNwidth or 16
pixels.
If menu orientation is
DwtOrientationHorizon-
tal, default is the sum
of DwtNwidth and
DwtNspacing or 16 pix-
els.
DwtNheight Dimension If menu orientation is
DwtOrientationVertical,
default is the sum of
DwtNheight and DwtNspac-
ing or 16 pixels.
If menu orientation is
DwtOrientationHorizon-
tal, default is the max-
imum entry DwtNheight or
16 pixels.
DwtNborderWidth Dimension One pixel
DwtNborder Pixel Default foreground color
DwtNborderPixmap Pixmap NULL
DwtNbackground Pixel Default background color
DwtNbackgroundPixmap Pixmap NULL
DwtNcolormap Colormap Default color map
DwtNsensitive Boolean True
Setting the sensitivity
of the menu causes all
widgets contained in
that menu to be set to
the same sensitivity.
DwtNancestorSensitive Boolean The bitwise AND of the
parent widget's DwtNsen-
sitive and DwtNances-
torSensitive attributes
DwtNaccelerators XtTranslations NULL
DwtNdepth int Depth of the parent win-
dow
DwtNtranslations XtTranslations NULL
DwtNmappedWhenManaged Boolean True
DwtNscreen Screen * The parent screen
DwtNdestroyCallback DwtCallbackPtr NULL
Common Attributes
DwtNforeground Pixel Default foreground color
DwtNhighlight Pixel Default foreground color
DwtNhighlightPixmap Pixmap NULL
DwtNuserData Opaque * NULL
DwtNdirectionRToL unsigned char DwtDirectionRightDown
DwtNfont DwtFontList The default XUI Toolkit
font
DwtNhelpCallback DwtCallbackPtr NULL
------------------------------------------------------------------
The following table lists the attributes inherited by the pull-down menu and pop-up menu widgets.
------------------------------------------------------------------
Attribute Name Data Type Default
------------------------------------------------------------------
Core Attributes
DwtNx Position For DwtMenuPopupCreate,
determined by the geome-
try manager
For DwtMenuPulldownCre-
ate, this attribute is
not supported
DwtNy Position For DwtMenuPopupCreate,
determined by the geome-
try manager
For DwtMenuPulldownCre-
ate, this attribute is
not supported
DwtNwidth Dimension Set as large as neces-
sary to hold all child
widgets
DwtNheight Dimension Set as large as neces-
sary to hold all child
widgets
DwtNborderWidth Dimension One pixel
DwtNborder Pixel Default foreground color
DwtNborderPixmap Pixmap NULL
DwtNbackground Pixel Default background color
DwtNbackgroundPixmap Pixmap NULL
DwtNcolormap Colormap Default color map
DwtNsensitive Boolean True
DwtNancestorSensitive Boolean The bitwise AND of the
parent widget's DwtNsen-
sitive and DwtNances-
torSensitive attributes
DwtNaccelerators XtTranslations NULL
DwtNdepth int Depth of the parent win-
dow
DwtNtranslations XtTranslations NULL
DwtNmappedWhenManaged Boolean True
DwtNscreen Screen * The parent screen
DwtNdestroyCallback DwtCallbackPtr NULL
Common Attributes
DwtNforeground Pixel Default foreground color
DwtNhighlight Pixel Default foreground color
DwtNhighlightPixmap Pixmap NULL
DwtNuserData Opaque * NULL
DwtNdirectionRToL unsigned char DwtDirectionRightDown
DwtNfont DwtFontList The default XUI Toolkit
font
DwtNhelpCallback DwtCallbackPtr NULL
Menu Attributes
DwtNspacing Dimension Zero pixels
DwtNmarginHeight Dimension 3 pixels
DwtNmarginWidth Dimension Three pixels
DwtNorientation unsigned char DwtOrientationVertical
DwtNadjustMargin Boolean True
DwtNentryBorder short Zero pixels
DwtNmenuAlignment Boolean True
DwtNentryAlignment unsigned char DwtAlignmentBeginning
DwtNmenuPacking unsigned char DwtMenuPackingTight (for
all menu types except
for radio boxes)
DwtMenuPackingColumn
(for radio boxes)
DwtNmenuNumColumns short One row or column
DwtNmenuRadio Boolean False
True (for radio boxes)
DwtNradioAlwaysOne Boolean True
DwtNmenuIsHomogeneous Boolean False
True (for radio boxes)
DwtNmenuEntryClass WidgetClass NULL
Radio boxes, however,
default to the toggle-
buttonwidgetclass.
DwtNmenuHistory Widget Zero
DwtNentryCallback DwtCallbackPtr NULL
DwtNmenuHelpWidget Widget NULL
DwtNchangeVisAtts Boolean True
DwtNmenuExtendLastRow Boolean True
------------------------------------------------------------------
Widget-Specific Attributes
The following table lists the widget-specific attributes for the menu widget. Descriptions of these attributes follow the table.
---------------------------------------------------------
Attribute Name Data Type Default
---------------------------------------------------------
DwtNspacing Dimension Zero pixels
DwtNmarginHeight Dimension 3 pixels
DwtNmarginWidth Dimension Three pixels
DwtNorientation unsigned char DwtOrientation-
Vertical
DwtNadjustMargin Boolean True
DwtNentryBorder short Zero pixels
DwtNmenuAlignment Boolean True
DwtNentryAlignment unsigned char DwtAlignmentBe-
ginning
DwtNmenuPacking unsigned char DwtMenuPack-
ingTight (for
all menu types
except for
radio boxes)
DwtMenuPacking-
Column (for
radio boxes)
DwtNmenuNumColumns short One row or col-
umn
DwtNmenuRadio Boolean False
True (for radio
boxes)
DwtNradioAlwaysOne Boolean True
DwtNmenuIsHomogeneous Boolean False
True (for radio
boxes)
DwtNmenuEntryClass WidgetClass NULL
Radio boxes,
however,
default to the
togglebutton-
widgetclass.
DwtNmenuHistory Widget Zero
DwtNentryCallback DwtCallbackPtr NULL
DwtNmenuHelpWidget Widget NULL
DwtNchangeVisAtts Boolean True
DwtNmenuExtendLastRow Boolean True
---------------------------------------------------------
DwtNspacing Specifies 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 sym-
metrical 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 DwtAl-
ignmentCenter (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 dimen-
sion. 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 num-
ber 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.
DwtNmenuRadio Specifies 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 but-
tons.
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 fol-
low the table.
-----------------------------------------------------
Attribute Name Data Type Default
-----------------------------------------------------
DwtNmapCallback DwtCallbackPtr NULL
DwtNunmapCallback DwtCallbackPtr NULL
-----------------------------------------------------
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 Values
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:
DwtCRActivate The user selected a menu
entry.
DwtCRMap The menu window is about
to be mapped.
DwtCRUnmap The menu window was just
unmapped.
DwtCRHelpRequested The user selected help.
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 sup-
plied by the application programmer when the subwidget callback function was specified. The s_callbackstruct member is set to the subwid-
get's callback structure.
See Also
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding
DwtMenu(3Dwt)