IMenuItem

The IMenuItem class represents properties of a menu item. This class, which is a data class, provides the following:

These functions do not affect the menu unless you call IMenu::addItem, IMenu::setItem, ISubmenu::addItem, or ISubmenu::setItem to place the menu item object into the menu.

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:


Note: ICommandEvents do not specify whether they are for a menu bar or pop-up menu. If you need to tell the difference, you must use different IDs for the menu items to distinguish whether they are on the menu bar or the pop-up menu. For example, you might need to apply different actions to a menu item object when the user selects it from the menu bar as opposed to the pop-up menu.

AIX Considerations

All menu item IDs must be unique.

OS/2 Considerations

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.


IMenuItem - Member Functions and Data by Group

Constructors & Destructor

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.


[view class]
~IMenuItem
public:
~IMenuItem()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IMenuItem

Creates an IMenuItem object with the specified item identifier, styles, and attributes.
Note: Use a value between 1 and 65565 for the item identifier. Values outside the recommended range may be truncated by the underlying GUI or result in portability problems. In addition, use a unique value for each menu item within a particular menu or submenu. You need unique menu item identifiers if you want to access items using the IMenu or ISubmenu classes and to identify events resulting from user selection of menu items.


Overload 1
public:
IMenuItem(const IMenuItem& menuItem)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IMenuItem( unsigned long itemId, const Style& style = defaultStyle ( ), const Attribute& attribute = defaultAttribute ( ) )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =
public:
IMenuItem& operator =(const IMenuItem& menuItem)

Assigns the value of one menu item object to another.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Attributes

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.


[view class]
defaultAttribute
public:
static Attribute defaultAttribute()

Returns the default attribute. The default attribute is classDefaultAttribute unless you have changed it using setDefaultAttribute.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultAttribute
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
checked
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The state indicator is a square-shaped object displayed to the left of the menu item.

OS/2 Considerations

The state indicator is a check mark displayed to the left of the menu item.


[view class]
classDefaultAttribute
public:
static const Attribute classDefaultAttribute

Specifies the default attribute for this class, which is IMenuItem::noAttribute.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
disabled
public:
static const Attribute disabled

Displays the menu item with unavailable-state emphasis, which means the user cannot select it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
framed
public:
static const Attribute framed

Encloses the menu item in a box.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

AIX Considerations

This attribute is ignored in the Motif version.


[view class]
highlighted
public:
static const Attribute highlighted

Displays the menu item with selected-state emphasis.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This attribute is ignored in the Motif version.


[view class]
noAttribute
public:
static const Attribute noAttribute

Specifies that no attribute applies to the menu item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noDismiss
public:
static const Attribute noDismiss

Specifies that a submenu remains displayed when a user chooses a menu item in the submenu.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

AIX Considerations

This attribute is ignored in the Motif version.


Command Type

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.


[view class]
commandType
public:
CommandType commandType() const

Returns the event the menu item generates when selected. The event can be a command, system command, or help command.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setCommand
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Implementation

These members provide utilities used to implement this class.


[view class]
attribute
protected:
unsigned long attribute() const

Returns an unsigned long representing the menu item's attributes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
extendedStyle
protected:
unsigned long extendedStyle() const

Returns an unsigned long value representing the menu item's extended style flags.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
helpId
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAttribute
protected:
IMenuItem& setAttribute(unsigned long newAttribute)

Sets the menu item's attributes from the specified unsigned long.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setExtendedStyle
protected:
IMenuItem& setExtendedStyle(unsigned long newExtendedStyle)

Sets the menu item's extended style to newExtendedStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
setHelpId
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setStyle
protected:
IMenuItem& setStyle(unsigned long newStyle)

Sets the menu item's style from the specified unsigned long.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
style
protected:
unsigned long style() const

Returns an unsigned long representing the menu item's style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Item State

You can use attribute functions to query or change menu item attributes.


[view class]
isChecked
public:
bool isChecked() const

If the attribute checked is set, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isDisabled
public:
bool isDisabled() const

If the attribute disabled is set, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isFramed
public:
bool isFramed() const

If the attribute framed is set, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

Motif does not support the framed attribute. This member function always returns false.


[view class]
isHighlighted
public:
bool isHighlighted() const

If the attribute highlighted is set, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

Motif does not support the highlighted attribute. This member function always returns false.


[view class]
isNoDismiss
public:
bool isNoDismiss() const

If the attribute noDismiss is set, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

Motif does not support the attribute noDismiss. This member function always returns false.


[view class]
setChecked
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The state indicator is a square-shaped object displayed to the left of the menu item.

OS/2 Considerations

The state indicator is a check mark displayed to the left of the menu item.


[view class]
setDisabled
public:
IMenuItem& setDisabled(bool disabled = true)

Displays the menu item with unavailable-state emphasis, which means the user cannot select it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setFramed
public:
IMenuItem& setFramed(bool framed = true)

Draws a box to enclose the menu item.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

AIX Considerations

Motif does not support the framed attribute.


[view class]
setHighlighted
public:
IMenuItem& setHighlighted(bool highlighted = true)

Displays the menu item with selected-state emphasis.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

Motif does not support the highlighted attribute.


[view class]
setNoDismiss
public:
IMenuItem& setNoDismiss(bool noDismiss = true)

Forces the menu item to remain visible when selected.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

AIX Considerations

Motif does not support the noDismiss attribute.


Label

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.


[view class]
bitmap
public:
IBitmapHandle bitmap() const

Returns the bitmap handle of the item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isBitmap
public:
bool isBitmap() const

Returns true if this is a bitmap menu item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isText
public:
bool isText() const

Returns true if this is a menu item containing text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setBitmap

Sets the bitmap to be displayed.


Overload 1
public:
IMenuItem& setBitmap(unsigned long bitmapResId)

Use this version to load the bitmap from the default resource library.

Use the following parameter:

bitmapResId
Resource identifier of the bitmap to display as a menu item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
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:

bitmapResId
Resource identifier of the bitmap to display as a menu item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IMenuItem& setBitmap(const IBitmapHandle& menuItem)

Use this version to use a bitmap that you already have loaded. Use the following parameter:

menuItem
Handle of the bitmap to display as a menu item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setText

Sets the text to be displayed. You can use either the resource identifier of the text or the actual text.


Overload 1
public:
IMenuItem& setText(const IResourceId& textResId)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IMenuItem& setText(const char* newText)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
text
public:
IString text() const

Returns an IString representing the text to be displayed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Menu Layout

Use menu item settings to control how the menu is laid out around the menu item.


[view class]
index
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
layoutType
public:
LayoutType layoutType() const

Returns the menu item placement and layout.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setIndex
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setLayout
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
atEnd
public:
static const unsigned long atEnd

Use this constant to place the menu item at the end of the menu.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Properties

Use properties functions to obtain general information about the menu item.


[view class]
id
public:
unsigned long id() const

Returns the item identifier associated with the menu item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isDrawItem
public:
bool isDrawItem() const

If the style drawItem is set, returns true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isSelectable
public:
bool isSelectable() const

If the menu item is selectable, returns true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isSeparator
public:
bool isSeparator() const

If the style separator is set, returns true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDrawItem
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setSelectable
public:
IMenuItem& setSelectable(bool selectable = true)

Enables the menu item for selection.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setSeparator
public:
IMenuItem& setSeparator()

Makes the menu item a separator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

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.


[view class]
convertToGUIStyle
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the default style. The default style is IMenuItem::classDefaultStyle unless you have changed it using IMenuItem::setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultStyle
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
buttonSeparator
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: You cannot use this style with the IMenuItem::split or IMenuItem::splitWithSeparator styles.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

AIX Considerations

This style is ignored in the Motif version.


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Specifies the original default style for this class, which is IMenuItem::noStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
drawItem
public:
static const Style drawItem

Enables applications to draw the menu item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This style is ignored in the Motif version.


[view class]
noStyle
public:
static const Style noStyle

Specifies that no style applies to the menu item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
postHelp
public:
static const Style postHelp

Specifies that the menu item is a help menu.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

AIX Considerations

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.

OS/2 Considerations

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: You cannot use this style with the IMenuItem::postSystemCommand style.


[view class]
postSystemCommand
public:
static const Style postSystemCommand

Specifies that the menu item generate a system command message that can be handled by ICommandHandler::systemCommand.
Note: You cannot use this style with the IMenuItem::postHelp style.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
separator
public:
static const Style separator

Specifies that the menu item is a separator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
split
public:
static const Style split

Starts the menu item in a new row or column.
Note: You cannot use this style with the IMenuItem::splitWithSeparator or IMenuItem::buttonSeparator styles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
splitWithSeparator
public:
static const Style splitWithSeparator

Starts the menu item in a new row or column with a line drawn to separate it.
Note: You cannot use this style with the IMenuItem::split or IMenuItem::buttonSeparator styles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This style is ignored in the Motif version.


[view class]
unavailable
public:
static const Style unavailable

Sets unavailable-state emphasis for a menu item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Submenu

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.


[view class]
isSubmenu
public:
bool isSubmenu() const

Returns true if this item is a submenu.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setSubmenuHandle
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
submenuHandle
public:
IMenuHandle submenuHandle() const

Returns the submenu window handle for the item. If the item does not have a submenu, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IMenuItem - Enumerations


[view class]
CommandType
enum CommandType { command, 
                   systemCommand, 
                   helpCommand }

These enumerators specify the type of event generated when a user selects the menu item:

command
Generates an ICommandHandler::command event.
systemCommand
Generates an ICommandHandler::systemCommand event.
helpCommand
Generates a help message.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
LayoutType

These enumerators specify the placement and layout of the menu item:

normalLayout
Specifies that no style applies.
splitLayout
Starts the menu item in a new row or column.
splitWithSeparatorLayout
Starts the menu item in a new row or column with a line drawn to separate it.
buttonSeparatorLayout
Separates the menu item and does not allow cursor movement to it.

Not all platforms support all the enumerations.

Variation 1
enum LayoutType { normalLayout, 
                  splitLayout, 
                  splitWithSeparatorLayout }

Supported Platforms

Windows OS/2 AIX
Yes No No

Variation 2
enum LayoutType { normalLayout, 
                  splitLayout, 
                  splitWithSeparatorLayout, 
                  buttonSeparatorLayout }

Supported Platforms

Windows OS/2 AIX
No Yes No

Variation 3
enum LayoutType { normalLayout, 
                  splitLayout }

Supported Platforms

Windows OS/2 AIX
No No Yes


IMenuItem - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data