### IMenuItem

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

  - Style and attribute objects to manipulate the menu item's appearance or behavior
  - Functions to set the label text or bitmap
  - Functions to query the label text or bitmap
  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:

  - command
  - systemCommand
  - helpCommand
  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.

~IMenuItem

      public:
      ~IMenuItem()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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.

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

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

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.

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

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

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.

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.

noAttribute

      public:
      static const Attribute noAttribute

  Specifies that no attribute applies to the menu item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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

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.

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

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

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

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

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

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

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

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.

isChecked

      public:
      bool isChecked() const

  If the attribute checked is set, true is returned.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isDisabled

      public:
      bool isDisabled() const

  If the attribute disabled is set, true is returned.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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.

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.

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.

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

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.

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.

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.

bitmap

      public:
      IBitmapHandle bitmap() const

  Returns the bitmap handle of the item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isBitmap

      public:
      bool isBitmap() const

  Returns true if this is a bitmap menu item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isText

      public:
      bool isText() const

  Returns true if this is a menu item containing text.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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.

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

layoutType

      public:
      LayoutType layoutType() const

  Returns the menu item placement and layout.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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.

id

      public:
      unsigned long id() const

  Returns the item identifier associated with the menu item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isDrawItem

      public:
      bool isDrawItem() const

  If the style drawItem is set, returns true.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isSelectable

      public:
      bool isSelectable() const

  If the menu item is selectable, returns true.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isSeparator

      public:
      bool isSeparator() const

  If the style separator is set, returns true.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

setSelectable

      public:
      IMenuItem& setSelectable(bool selectable = true)

  Enables the menu item for selection.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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

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

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

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.

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

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.

noStyle

      public:
      static const Style noStyle

  Specifies that no style applies to the menu item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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

separator

      public:
      static const Style separator

  Specifies that the menu item is a separator.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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.

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.

isSubmenu

      public:
      bool isSubmenu() const

  Returns true if this item is a submenu.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None