Method XbpMenuBar():addItem() Foundation

Adds a menu item to the menu.

:addItem( <aItem> ) --> nItemIndex
<aItem> := { xCaption [, bAction, nStyle, nAttribute] }
<aItem> is an array containing between one and four elements that defines the menu item.
xCaption is the caption of the menu item. This can be NIL, a character string, the resource ID of a BITMAP resource, or an object of the XbpMenu class. Furthermore, a XbpBitmap object can be passed to define the image to be displayed by the menu item. This allows to use images defined in various image file formats. Furthermore, if a transparent color has been defined for the bitmap object, transparent areas in the image are automatically replaced with the background color used by the menubar object.
Using XbpIcon objects together with :addItem() is not supported. Use method XbpIcon:getBitmap() to extract a bitmap from an icon object.
bAction is an optional code block that is executed after the menu item is selected by the user. If the menu item is not to cause an action, the value NIL must be specified for bAction.
The value of nStyle must be a constant defined in the XBP.CH file. Valid constants begin with the prefix XBPMENUBAR_MIS_ and define the style used when displaying the menu item (MIS stands for: Menu Item Style).
The value of nAttribute must also be a constant defined in XBP.CH. Valid constants start with the prefix XBPMENUBAR_MIA_ and define the attribute used for the menu item (MIA stands for: Menu Item Attribute).

This method returns a numeric value that is an index to the ordinal position of the new menu item in the menu item list. Since new items are always added to the end of the menu item list, this value also corresponds to the current count of menu items.

The return value is zero if the menu item could not be added to the menu.


The method :addItem() installs a menu item by adding the new menu item to the end of the menu item list. The menu item is specified using the array <aItem> that must contain between one and four elements. These array elements provide a flexible way to organize a menu or a menu system. The first two elements xCaption and bAction are the most important and are usually included. They determine how the menu item appears on the screen and what action is performed when the menu item is selected.

Caption ( aItem[1] )

The first element of the menu item array contains the caption for the menu item. Values for this parameter can be any one of four different data types:

Caption for menu items
Value Data type Description
"~Save" C Character string (the tilde (~) defines the shortcut key)
1003 N Resource ID of a bitmap
oXbpBitmap O Bitmap object that defines the caption image
oXbpMenu O XbpMenu object that defines a submenu oXbpMenu:title is displayed as the caption
NIL U Menu item without caption must be specified by style and attribute (for example: a separating line)

An XbpMenu object is generally specified for the caption of menu items in XbpMenuBar objects. This is because the menu bar generally has a submenu for each menu item. The character string contained in the oXbpMenu:title instance variable of the XbpMenu object is displayed as the caption.

Within each XbpMenu object, however, a character string is generally used as the caption and is displayed on the screen. Any one letter of each caption can be marked by placing a tilde (~) in front of it. When the menu is displayed, this letter appears underscored and acts as a "shortcut key". This means that the menu bar item can be activated by pressing the Alt key plus the defined shortcut key. When a menu bar is installed in an XbpCrt window, the instance variable oXbpCrt:useShortCuts must be set to .T. (true) for the shortcut keys of the menu to be recognized.

In many cases an additional shortcut key is offered for the direct selection of a menu item (for example, "~Copy Ctrl+Insert" for copying to the clipboard). These shortcut keys are generally displayed within the caption of a menu item. To evenly align these additional shortcut keys, the Tab character (Chr(9)) must be inserted in front of the shortcut key characters.

If a numeric value is specified for the caption, it must be the resource ID of a bitmap that has been linked to the EXE file using the resource compiler. In this case, the bitmap is displayed as the caption instead of a character string.

Another way to define a bitmap to be displayed as the caption of a menu item is to pass an object of the XbpBitmap class instead of a resource id. This allows to load images from disk from a variety of image formats, for example. Furthermore, if a transparent color has been defined for the image, transparent areas within the image are automatically replaced with the background color used by the menu(bar) object.

If the caption is NIL, the third element of <aItems> must be included (the fourth element is optional). This allows menu features to be defined that visually organize the menu but cause no action. Generally this is only used with XbpMenu objects and can be used to display a separating line between menu items.

Action code block ( aItem[2] )

The second element of <aItems> contains either NIL or a code block that is automatically executed after the corresponding menu item is selected. This code block performs an action that controls the program. The code block functions like the callback code block :itemSelectedand is executed after the menu item is selected instead of :itemSelected. Three parameters are passed to this code block. The first two parameters are the first two message parameters of AppEvent(). The first message parameter contains a numeric value identifying the ordinal position of the selected menu item in the menu object. The second message parameter is not significant. The third parameter is the menu object containing the menu item.

Style of caption ( aItem[3] )

The third element of <aItems> defines the style of the caption. Valid #define constants from the XBP.CH file are listed in the following tables:

Style constant when Caption is a character string
Constant Description
XBPMENUBAR_MIS_STATIC Caption is displayed as text, menu item cannot be selected

Style constant when Caption is NIL
Constant Description
XBPMENUBAR_MIS_SEPARATOR Horizontal separating line
XBPMENUBAR_MIS_BUTTONSEPARATOR Display empty menu item as separator between two menu items
XBPMENUBAR_MIS_BREAK *) Begin new row or column and draw a single separating line between two columns
XBPMENUBAR_MIS_BREAKSEPARATOR *) Begin new row or column and draw highlighted separating line between two columns
  1. indows: *) no separator lines in menu bar

The style of a menu item can only be defined when the caption contains either a character string or the value NIL. If the caption is NIL, a separator definition must be included as the third element of <aItems>. The separator can be a separating line, a new row in the XbpMenubar object, or a new column in a XbpMenu object. This allows a horizontal menu (XbpMenuBar) to be organized into multiple rows or a vertical menu (XbpMenu) to be organized into multiple columns.

A separating line is a valid menu item. It is displayed but cannot be selected. It has an ordinal position which must be considered when calling methods that change the number of menu items, like :delItem()or :insItem().

The XBPMENUBAR_MIS_BREAK* styles do not necessarily cause a separator line to be displayed in a menu (bar) on Windows platforms. Instead, they may be interpreted as layout rules when there is insufficient space in the menu (bar) to display all menu items. For example, if a menu (bar) has 100 menu items, it would be truncated, unless the operating system is instructed how to format the menu (bar) using one of the "break" styles. Note that not all Windows versions support defining XBPMENUBAR_MIS_BREAK* styles for separator items. Therefore, it is recommended that these styles only be used with menu items that define either a textual caption or a caption image.

Attribute of the caption ( aItem[4] )

The fourth element of <aItems> defines attributes for the menu item caption. Valid #define constants from the XBP.CH file are listed in the following table:

Attributes for the caption
Menu Item Attribute Description Corresponding Methods
XBPMENUBAR_MIA_NODISMISS *) Menu is not closed after selection
XBPMENUBAR_MIA_FRAMED *) Menu item is framed
XBPMENUBAR_MIA_CHECKED Menu item has a check mark :checkItem()
XBPMENUBAR_MIA_DISABLED Menu item is not available :disableItem(), :enableItem()
XBPMENUBAR_MIA_HILITED *) Menu item is displayed highlighted
XBPMENUBAR_MIA_DEFAULT Menu item is the default item of the menu
XBPMENUBAR_MIA_OWNERDRAW Menu item is to be drawn by the application :drawItem()
  1. Unsupported on Windows platforms

If the XBPMENUBAR_MIA_OWNERDRAW menu item attribute is specified, the corresponding menu item is drawn by the Xbase++ application. For every menu item with this attribute, the system sends an xbeP_DrawItem event when the item must be redrawn. See :measureItem() and :drawItem() for further information.

Default items created using the XBPMENUBAR_MIA_DEFAULT menu item attribute are displayed in bold type. There may be only one default item per menu. Default menu items are normally used to denote the default operation in a given context. In Windows Explorer, for example, a default menu item in an object's context menu usually denotes the operation equivalent to the user double-clicking that object.

If an XbpBitmap object is used to define the caption image of a menu item, one of the methods :load(), :loadFile() or :make() must have previously been called. Moreover, it is discouraged to use the bitmap object to load or define a different image as long as it is assigned to the menu item. Instead, a new bitmap object should be created for that purpose.


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.