The IMenuItem class represents properties of a menu item. This class, which is a data class, provides the following:
You can construct an IMenuItem directly, set up the properties you want on it, and then place it in the menu using the IMenu or ISubmenu member functions. This is useful when you are creating new menu items.
Alternatively, you can use IMenu::menuItem to create an IMenuItem object. You can change this object as needed and then place it back into the menu using the IMenu or ISubmenu functions to have the changes take effect. This is useful when you want to change the properties of existing menu items.
You can use menu items to generate the following events:
All menu item IDs must be unique.
A menu item identifier does not have to be unique. However, if you call a function such as IMenu::checkItem using the identifier, the first menu item that has the identifier is acted upon.
You can construct and destruct objects of this class.
In most cases you need to call at least one of the set functions on the menu item before it can be added to a menu. For example, if you want a bitmap menu item, first construct the IMenuItem, and then call setBitmap to specify the bitmap to be used for display purposes.
After construction, you can add IMenuItems that have the styles IMenuItem::separator or IMenuItem::drawItem to a menu without having to call any of the set functions.
You can create IMenuItem objects from an existing menu item by calling IMenu::menuItem. This is useful if you want to modify a menu item that already exists in a menu.
![]() |
public:
~IMenuItem()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
Creates an IMenuItem object with the specified item identifier, styles, and attributes.
Note:
public:
IMenuItem(const IMenuItem& menuItem)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IMenuItem( unsigned long itemId, const Style& style = defaultStyle ( ), const Attribute& attribute = defaultAttribute ( ) )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuItem& operator =(const IMenuItem& menuItem)
Assigns the value of one menu item object to another.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
For a menu item, styles represent properties of the menu item that typically do not change during the life of the item. Attributes represent properties that are more likely to be changed by the application during the life of the menu item. All attributes are set independently of each other.
IMenuItem defines a set of objects of the nested class IMenuItem::Attribute. You can use these attributes with constructors for IMenuItem, and IMenuItem::setDefaultAttribute.
![]() |
public:
static Attribute defaultAttribute()
Returns the default attribute. The default attribute is classDefaultAttribute unless you have changed it using setDefaultAttribute.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static void setDefaultAttribute(const Attribute& attribute)
Sets the default attribute for all subsequent menu items.
This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default attribute on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.
When you create a window class that has attributes and do not specifically specify the attributes in the constructor, the Open Class Library queries the default attribute. Therefore, the only safe place to call this member function is when no other application threads that create windows with attributes are active.
Another way to avoid a conflict in a multithreaded application is to specifically specify window attributes on window construction, rather than calling this member function.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static const Attribute checked
Displays a state indicator to the left of the menu item when the user selects it. The state indicator is removed when the user deselects the item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The state indicator is a square-shaped object displayed to the left of the menu item.
The state indicator is a check mark displayed to the left of the menu item.
![]() |
public:
static const Attribute classDefaultAttribute
Specifies the default attribute for this class, which is IMenuItem::noAttribute.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static const Attribute disabled
Displays the menu item with unavailable-state emphasis, which means the user cannot select it.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static const Attribute framed
Encloses the menu item in a box.
Windows | OS/2 | AIX |
Ignored | Yes | Ignored |
This attribute is ignored in the Motif version.
![]() |
public:
static const Attribute highlighted
Displays the menu item with selected-state emphasis.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
This attribute is ignored in the Motif version.
![]() |
public:
static const Attribute noAttribute
Specifies that no attribute applies to the menu item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static const Attribute noDismiss
Specifies that a submenu remains displayed when a user chooses a menu item in the submenu.
Windows | OS/2 | AIX |
Ignored | Yes | Ignored |
This attribute is ignored in the Motif version.
You can specify the type of event that is generated when a menu item is selected. Use these members to query the event type that is generated by a menu item or to set a new type of event.
![]() |
public:
CommandType commandType() const
Returns the event the menu item generates when selected. The event can be a command, system command, or help command.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuItem& setCommand(CommandType value)
Specifies what event to generate when the user selects the menu item. The event can be a command, system command, or help command.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
These members provide utilities used to implement this class.
![]() |
protected:
unsigned long attribute() const
Returns an unsigned long representing the menu item's attributes.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
unsigned long extendedStyle() const
Returns an unsigned long value representing the menu item's extended style flags.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
![]() |
protected:
unsigned long helpId() const
Returns the identifier of the help panel that is to be displayed when help is requested for the menu item. To display the help panel, you must first associate the window owning the menu which contains this menu item with a help instance. See the IHelpWindow class for more information.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
IMenuItem& setAttribute(unsigned long newAttribute)
Sets the menu item's attributes from the specified unsigned long.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
IMenuItem& setExtendedStyle(unsigned long newExtendedStyle)
Sets the menu item's extended style to newExtendedStyle.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
![]() |
protected:
IMenuItem& setHelpId(unsigned long newHelpTopicId)
Stores the identifier of the help panel that is to be displayed when help is requested for the menu item. To display the help panel, you must first associate the window owning the menu which contains this menu item with a help instance. See the IHelpWindow class for more information.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
IMenuItem& setStyle(unsigned long newStyle)
Sets the menu item's style from the specified unsigned long.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
unsigned long style() const
Returns an unsigned long representing the menu item's style.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
You can use attribute functions to query or change menu item attributes.
![]() |
public:
bool isChecked() const
If the attribute checked is set, true is returned.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool isDisabled() const
If the attribute disabled is set, true is returned.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool isFramed() const
If the attribute framed is set, true is returned.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
Motif does not support the framed attribute. This member function always returns false.
![]() |
public:
bool isHighlighted() const
If the attribute highlighted is set, true is returned.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
Motif does not support the highlighted attribute. This member function always returns false.
![]() |
public:
bool isNoDismiss() const
If the attribute noDismiss is set, true is returned.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
Motif does not support the attribute noDismiss. This member function always returns false.
![]() |
public:
IMenuItem& setChecked(bool checked = true)
Displays a state indicator to the left of the menu item when the user selects it. The state indicator is removed when the user deselects the item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The state indicator is a square-shaped object displayed to the left of the menu item.
The state indicator is a check mark displayed to the left of the menu item.
![]() |
public:
IMenuItem& setDisabled(bool disabled = true)
Displays the menu item with unavailable-state emphasis, which means the user cannot select it.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuItem& setFramed(bool framed = true)
Draws a box to enclose the menu item.
Windows | OS/2 | AIX |
Ignored | Yes | Ignored |
Motif does not support the framed attribute.
![]() |
public:
IMenuItem& setHighlighted(bool highlighted = true)
Displays the menu item with selected-state emphasis.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
Motif does not support the highlighted attribute.
![]() |
public:
IMenuItem& setNoDismiss(bool noDismiss = true)
Forces the menu item to remain visible when selected.
Windows | OS/2 | AIX |
Ignored | Yes | Ignored |
Motif does not support the noDismiss attribute.
Use label members to set or query the label displayed on the menu item. The label can be either a bitmap or a text string.
![]() |
public:
IBitmapHandle bitmap() const
Returns the bitmap handle of the item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool isBitmap() const
Returns true if this is a bitmap menu item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool isText() const
Returns true if this is a menu item containing text.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
Sets the bitmap to be displayed.
public:
IMenuItem& setBitmap(unsigned long bitmapResId)
Use this version to load the bitmap from the default resource library.
Use the following parameter:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IMenuItem& setBitmap(const IResourceId& bitmapResId)
Use this version to load the bitmap from the resource library you specified on creation of the IResourceId object.
Use the following parameter:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IMenuItem& setBitmap(const IBitmapHandle& menuItem)
Use this version to use a bitmap that you already have loaded. Use the following parameter:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
Sets the text to be displayed. You can use either the resource identifier of the text or the actual text.
public:
IMenuItem& setText(const IResourceId& textResId)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IMenuItem& setText(const char* newText)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IString text() const
Returns an IString representing the text to be displayed.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Use menu item settings to control how the menu is laid out around the menu item.
![]() |
public:
unsigned long index() const
Returns the ordinal position of the menu item in its submenu. The first item in a menu or submenu has an index value of 0.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
LayoutType layoutType() const
Returns the menu item placement and layout.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuItem& setIndex(unsigned long index = atEnd)
Sets the menu item ordinal position in its submenu. With this member function, you can add a menu item anywhere in the order.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuItem& setLayout(LayoutType value)
Defines the menu item placement and layout. Use values from the enumeration IMenuItem::LayoutType to specify the layout type and placement.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static const unsigned long atEnd
Use this constant to place the menu item at the end of the menu.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Use properties functions to obtain general information about the menu item.
![]() |
public:
unsigned long id() const
Returns the item identifier associated with the menu item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool isDrawItem() const
If the style drawItem is set, returns true.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool isSelectable() const
If the menu item is selectable, returns true.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool isSeparator() const
If the style separator is set, returns true.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuItem& setDrawItem(bool drawItem = true)
Causes the system to generates a draw item event when the item needs drawing. This enables the application to draw the menu item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuItem& setSelectable(bool selectable = true)
Enables the menu item for selection.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuItem& setSeparator()
Makes the menu item a separator.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
For a menu item, styles represent properties of the menu item that typically do not change during the life of the item. Attributes represent properties that are more likely to be changed by the application during the life of the menu item.
IMenuItem defines a set of objects of the nested class IMenuItem::Style. You can use these styles with constructors for IMenuItem, and IMenuItem::setDefaultStyle.
![]() |
public:
virtual unsigned long convertToGUIStyle( const IBitFlag& style, bool extendedOnly = false ) const
Converts a style object into a value appropriate for the presentation system. The default action is to return the base GUI styles for the platform. Extended styles, those defined by the application and the Open Class Library, are returned if you set extendedOnly to true.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
static Style defaultStyle()
Returns the default style. The default style is IMenuItem::classDefaultStyle unless you have changed it using IMenuItem::setDefaultStyle.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static void setDefaultStyle(const Style& style)
Sets the default style for all subsequent menu items.
This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.
When you create a window class and do not specifically specify window styles in the constructor, the Open Class Library queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create windows are active.
Another way to avoid a conflict in a multithreaded application is to specifically specify window styles on window construction, rather than calling this member function.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static const Style buttonSeparator
Draws a line to separate the menu item.
The user cannot use cursor movement keys to get to it.
Note:
Windows | OS/2 | AIX |
Ignored | Yes | Ignored |
This style is ignored in the Motif version.
![]() |
public:
static const Style classDefaultStyle
Specifies the original default style for this class, which is IMenuItem::noStyle.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static const Style drawItem
Enables applications to draw the menu item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
This style is ignored in the Motif version.
![]() |
public:
static const Style noStyle
Specifies that no style applies to the menu item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static const Style postHelp
Specifies that the menu item is a help menu.
Windows | OS/2 | AIX |
Ignored | Yes | Yes |
When you use this style on a menu item that appears in the menu bar, the menu item appears to the far right of the menu bar.
When you use this style, the menu item generates a help message that is sent to the
previous focus window.
Therefore, the postHelp style works just like a Help push button.
Note:
![]() |
public:
static const Style postSystemCommand
Specifies that the menu item generate a system command message that can be
handled by
ICommandHandler::systemCommand.
Note:
Windows | OS/2 | AIX |
Ignored | Yes | Yes |
![]() |
public:
static const Style separator
Specifies that the menu item is a separator.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static const Style split
Starts the menu item in a new row or column.
Note:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
static const Style splitWithSeparator
Starts the menu item in a new row or column with a line drawn to separate it.
Note:
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
This style is ignored in the Motif version.
![]() |
public:
static const Style unavailable
Sets unavailable-state emphasis for a menu item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Use submenu members to control the submenu behavior of a menu item. If a menu item is a submenu, a cascaded submenu is displayed when the user selects the menu item. You can use an IMenuHandler to alter the submenu before it is displayed.
![]() |
public:
bool isSubmenu() const
Returns true if this item is a submenu.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuItem& setSubmenuHandle(const IMenuHandle& menuHandle)
Sets the menu handle which indicates this menu item's submenu. When the user selects the menu item, it displays the menu specified by menuHandle as a cascaded submenu.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuHandle submenuHandle() const
Returns the submenu window handle for the item. If the item does not have a submenu, 0 is returned.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
enum CommandType { command, systemCommand, helpCommand }
These enumerators specify the type of event generated when a user selects the menu item:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
These enumerators specify the placement and layout of the menu item:
Not all platforms support all the enumerations.
enum LayoutType { normalLayout, splitLayout, splitWithSeparatorLayout }
Windows | OS/2 | AIX |
Yes | No | No |
enum LayoutType { normalLayout, splitLayout, splitWithSeparatorLayout, buttonSeparatorLayout }
Windows | OS/2 | AIX |
No | Yes | No |
enum LayoutType { normalLayout, splitLayout }
Windows | OS/2 | AIX |
No | No | Yes |