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 elementsxCaption 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:
| 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:
| Constant |
Description |
| XBPMENUBAR_MIS_STATIC |
Caption is displayed as text, menu item cannot be selected |
| 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 |
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:
| 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() |
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.
