### IMenu

  The IMenu class is a base class for all menu classes, including the following:

  - IMenuBar
  - IPopUpMenu
  - ISubMenu
  - ISystemMenu

  It provides functions to add, replace, remove, select, and disable menu items in the menu. This class also provides functions to access properties such as the following:

  - The number of menu items in the menu
  - The bounding rectangle for menu items in the menu

#### AIX Considerations

  IMenu does not support conditional cascading behavior or the drawItem style (drawn buttons) in menus.

  You can gain access to the window which underlies an IMenu by calling the IMenu::window method.

  The Open Class Library provides a Motif callback routine to process the following menu events:

  - Showing a menu on the display
  - Selecting a menu item in a menu
  - Removing a menu from the display

#### OS/2 Considerations

  The bounding rectangle is returned after sending the message MM_QUERYITEMRECT. You can use the bounding rectangle if you need to draw menu items yourself.

  You can gain access to the window which underlies an IMenu by calling the IMenu::window method.

#### Windows Considerations

  To support menus loaded from a resource file, IMenu classes have the following requirements:

  - Menu resources must be defined using the MENUEX keyword.
  - Unique IDs must be provided for all pop-up menu items, indicated by the POPUP keyword.

  On Windows platforms, objects of the IMenu (and derived) classes do not have an underlying window. This is due to the implementation of menus in the Windows operating system as nonclient areas of the frame. Application code which relies on the fact that an IMenu has a window in the OS/2 or UNIX operating systems may not be portable to the Windows operating system.

### IMenu - Member Functions and Data by Group

### Constructors & Destructor

Use these functions to construct and delete objects of the IMenu class. You cannot copy or assign IMenu objects because both the copy constructor and the assignment operator are private functions.

Protected constructors are provided for the use of derived classes to create objects of this class.

~IMenu

      public:
      virtual ~IMenu()

Supported Platforms

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

IMenu

  Construct an IMenu object.

  Overload 1

      public:
      IMenu(const IMenuHandle& menuHandle)

  Constructs an IMenu object for an existing menu handle. The menu refered to by the specified handle is not automatically destroyed when the IMenu object is destroyed; you can change this by using setAutoDestroyWindow(true).

Supported Platforms

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

AIX Considerations

  On X-Motif systems, the specified handle (actually an IWindowHandle) is wrappered in an IWindow object, available to you by calling IMenu::window.

OS/2 Considerations

  On OS/2 systems, the specified handle (actually an IWindowHandle) is wrappered in an IWindow object, available to you by calling IMenu::window.

  Overload 2

      protected:
      IMenu()

  Provided for derived classes to call.

Supported Platforms

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

### Adding Items

You can add textual, graphical, submenu, or separator items to a menu object. You can also construct an object of the IMenuItem class and add it to the menu object.
Note: Use a value between 1 and 65535 for the item identifier in these functions. Values outside the recommended range can be truncated by the underlying GUI or can result in portability problems. In addition, you need to use a unique value for each menu item within a particular menu or submenu if you want to access items using this class and to identify events resulting from user selection of menu items.

addBitmap

  Adds a bitmap menu item as the last item in a menu or submenu.

  Overload 1

      public:
      virtual IMenu&
        addBitmap( unsigned long newItemId,
                   const IResourceId& bitmapResId,
                   unsigned long intoSubmenuId = 0 )

  Use this version to load a bitmap from the resource library you specified when you created the IResourceId object.

  newItemId
    The identifier of the new menu item to add to a menu or submenu.
  bitmapResId
    The resource identifier of the bitmap to load for the button face of the new menu item.
  intoSubmenuId
    The identifier of the submenu to add the new menu item to. If you specify 0, the new item is added to the menu bar.

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets for menus. A menu bar must contain only CascadeButton widgets or gadgets because they display a pull-down menu with additional choices. The pull-down menus can contain the following:

  - CascadeButton widgets or gadgets
  - ToggleButton widgets or gadgets
  - Label widgets or gadgets
  - Separator widgets or gadgets

  Overload 2

      public:
      virtual IMenu&
        addBitmap( unsigned long newItemId,
                   const IBitmapHandle& itemBitmap,
                   unsigned long intoSubmenuId = 0 )

  Use this version to add a bitmap that you already have loaded into a menu item.

  newItemId
    The identifier of the new menu item to add to a menu or submenu.
  itemBitmap
    The bitmap to load for the button face of the new menu item. This parameter accepts a currently available bitmap handle.
  intoSubmenuId
    The identifier of the submenu to add the new menu item to. If you specify 0, the new item is added to the menu bar.

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets for menus. A menu bar must contain only CascadeButton widgets or gadgets because they display a pull-down menu with additional choices. The pull-down menus can contain the following:

  - CascadeButton widgets or gadgets
  - ToggleButton widgets or gadgets
  - Label widgets or gadgets
  - Separator widgets or gadgets

  Overload 3

      public:
      virtual IMenu&
        addBitmap( unsigned long newItemId,
                   unsigned long bitmapResId,
                   unsigned long intoSubmenuId = 0 )

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

  newItemId
    The identifier of the new menu item to add to a menu or submenu.
  bitmapResId
    The resource identifier of the bitmap to load from the default resource library for the button face of the new menu item.
  intoSubmenuId
    The identifier of the submenu to add the new menu item to. If you specify 0, the new item is added to the menu bar.

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets for menus. A menu bar must contain only CascadeButton widgets or gadgets because they display a pull-down menu with additional choices. The pull-down menus can contain the following:

  - CascadeButton widgets or gadgets
  - ToggleButton widgets or gadgets
  - Label widgets or gadgets
  - Separator widgets or gadgets

addItem

      public:
      virtual IMenu&
        addItem( IMenuItem& menuItem,
                 unsigned long intoSubmenuId = 0 )

  Adds a menu item, represented by an IMenuItem, as the last item in a menu or submenu.

  menuItem
    A new menu item to add to a menu or submenu.
  intoSubmenuId
    The identifier of a submenu to add the new menu item to. If you specify 0, the new item is added to the menu bar.

Exception

  IAccessError | The system could not insert the menu item. This may be due to lack of system resources.
  IInvalidRequest | The menu item could not be updated with the bitmap.
  IInvalidRequest | The bitmap handle is invalid or missing. Verify that the bitmap handle is valid or that the bitmap resource exists.

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets for menus. A menu bar can contain only CascadeButton widgets or gadgets because they display a pull-down menu with additional choices. The pull-down menus can contain the following:

  - CascadeButton widgets or gadgets
  - ToggleButton widgets or gadgets
  - Label widgets or gadgets
  - Separator widgets or gadgets

addSeparator

  Adds a separator menu item as the last item in a menu or submenu. Use this function to add items to your menu without creating a menu item object first.

  Overload 1

      public:
      virtual IMenu&
        addSeparator( unsigned long newItemId,
                      unsigned long intoSubmenuId )

  Use this version of the function if you need to be able to access the separator item later. Use newItemId to specify the identifier you want to use to access the separator.

  newItemId
    Item identifier of the new menu item to add to a menu or submenu.
  intoSubmenuId
    Identifier of the submenu to add the new menu item to.

Supported Platforms

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

  Overload 2

      public:
      virtual IMenu&
        addSeparator( unsigned long intoSubmenuId = 0 )

  Use this version to add a separator with an unspecified item identifier.

  intoSubmenuId
    Identifier of the submenu to add the new menu item to.

Supported Platforms

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

addSubmenu

  Creates a submenu and adds it to the menu item.

  Overload 1

      public:
      virtual IMenu& addSubmenu(unsigned long itemId)

  itemId
    The identifier of the menu item to add the submenu to. The menu item must already be in the menu. The submenu has no entries.

Exception

  IInvalidRequest | An attempt was made to add the menu bar as a submenu. The menu bar cannot be added as a submenu.
  IInvalidRequest | A submenu already exists for the menu item. Only one submenu can be added to a menu item.

Supported Platforms

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

  Overload 2

      public:
      virtual IMenu&
        addSubmenu( unsigned long itemId,
                    const IResourceId& submenuResId )

  itemId
    The identifier of the menu item to add the submenu to. The menu item must already be in the menu.
  submenuResId
    The resource identifier of the submenu to add to the menu item. If you do not specify this parameter, you add a submenu with no entries to the specified menu item.

Exception

  IInvalidRequest | An attempt was made to add the menu bar as a submenu. The menu bar cannot be added as a submenu.
  IInvalidRequest | A submenu already exists for the menu item. Only one submenu can be added to a menu item.

Supported Platforms

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

Windows Considerations

  To support menus loaded from a resource file, IMenu classes have the following requirements:

  - Menu resources must be defined using the MENUEX keyword.
  - Unique IDs must be provided for all pop-up menu items, indicated by the POPUP keyword.

addText

  Adds a text menu item as the last item in a menu or submenu. You can use this function to add items to your menu without creating a menu item object first.

  Overload 1

      public:
      virtual IMenu&
        addText( unsigned long newItemId,
                 const char* itemText,
                 unsigned long intoSubmenuId = 0 )

  Use this version to specify a character string for the menu item text.

  newItemId
    The identifier of the new menu item to add to a menu or submenu.
  itemText
    The text to load for the button face of the new menu item. This parameter accepts a currently available text string.
  intoSubmenuID
    The identifier of the submenu to add the new menu item to. If you specify 0, the new item is added to the menu bar.

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets for menus. A menu bar must contain only CascadeButton widgets or gadgets because they display a pull-down menu with additional choices. The pull-down menus can contain the following:

  - CascadeButton widgets or gadgets
  - ToggleButton widgets or gadgets
  - Label widgets or gadgets
  - Separator widgets or gadgets

  Overload 2

      public:
      virtual IMenu&
        addText( unsigned long newItemId,
                 const IResourceId& textResId,
                 unsigned long intoSubmenuId = 0 )

  Use this version to load the menu item text from a resource library.

  newItemId
    The identifier of the new menu item to add to a menu or submenu.
  textResId
    The text to load for the button face of the new menu item. This parameter accepts the resource ID of a text string to load.
  intoSubmenuID
    The identifier of the submenu to add the new menu item to. If you specify 0, the new item is added to the menu bar.

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets for menus. A menu bar must contain only CascadeButton widgets or gadgets because they display a pull-down menu with additional choices. The pull-down menus can contain the following:

  - CascadeButton widgets or gadgets
  - ToggleButton widgets or gadgets
  - Label widgets or gadgets
  - Separator widgets or gadgets

### Cursored Operations

Cursored operations use objects of the IMenu::Cursor nested class to designate which menu item is to be acted upon. You can use these functions to access each item in the menu without knowing the menu item identifiers.

add

      public:
      virtual IMenu& add(IMenuItem& menuItem, Cursor& cursor)

  Adds the specified menu item at the specified cursor position by pushing down everything after the cursor.

Supported Platforms

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

addAsNext

      public:
      virtual IMenu&
        addAsNext( IMenuItem& menuItem,
                   Cursor& cursor )

  Adds the specified menu item as the next item and sets the specified cursor on it.

Supported Platforms

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

cursor

      public:
      Cursor
        cursor( unsigned long itemId,
                unsigned long inSubmenuId = 0 ) const

  Returns an object of the nested class IMenu::Cursor and sets the cursor to point to the specified menu item.

  itemID
    The menu item the cursor is set to point to.
  inSubmenuId
    The menu or submenu in which the cursor is manipulated. If you specify 0, itemId refers to an IMenu object. If you specify a nonzero itemId, the cursor is manipulated in the menu or submenu specified by the nonzero inSubmenuId.

Exception

  IInvalidRequest | The menu item identifier is invalid. Verify that the identifier represents an item in the menu.

Supported Platforms

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

deleteAt

      public:
      virtual IMenu& deleteAt(Cursor& cursor)

  Deletes the menu item at the position of the specified cursor and sets the cursor to the previous menu item.

Supported Platforms

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

elementAt

      public:
      virtual IMenuItem elementAt(const Cursor& cursor) const

  Returns an IMenuItem that describes the menu item at the cursor position.

Supported Platforms

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

removeSubmenuAt

      public:
      virtual IMenu& removeSubmenuAt(Cursor& cursor)

  Removes the menu item and submenu indicator at the specified cursor position. Typically, you use this function to remove a cascading menu.

Supported Platforms

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

### Direct Manipulation

Use these members to query and set the drag-item provider for objects of this class. Note that the drag-item provider for an IMenu object (such as an IMenuBar) is different from the drag-item provider for an IWindow object (such as an IEntryField).

itemProvider

      public:
      IDMItemProvider* itemProvider() const

  Returns a pointer to the drag-item provider (IDMItemProvider) for this menu.

Supported Platforms

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

setItemProvider

      public:
      IMenu& setItemProvider(IDMItemProvider* dragProvider)

  Sets a pointer to the drag-item provider (IDMItemProvider) for this menu.

Supported Platforms

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

### Implementation

These members provide utilities used to implement this class.

disableUpdate

      public:
      virtual IMenu& disableUpdate()

  Disables drawing changes to a menu on the screen.

Supported Platforms

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

handle

      public:
      virtual IWindowHandle handle() const

  Returns the menu handle.

Supported Platforms

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

Portability Considerations

  The returned handle is a unique 32-bit identifier for this menu in the same way a window handle is a unique identifier for IWindow-derived classes. However, this handle is not a window handle on all platforms; on the Windows operating system, it is a menu handle.

hide

      public:
      virtual IMenu& hide()

  Hide this menu so it cannot be seen on screen.

Supported Platforms

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

id

      public:
      virtual unsigned long id() const

  Returns the menu identifier of the menu.

Supported Platforms

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

isFrameWindow

      public:
      virtual bool isFrameWindow() const

  If this object represents a frame window, true is returned. Otherwise, false is returned. Because menus are not frame windows, false is always returned.

Supported Platforms

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

isValid

      public:
      virtual bool isValid() const

  If this object represents a valid menu, true is returned. If the menu does not exist, or has already been destroyed, false is returned.

Supported Platforms

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

menuWithParent

      public:
      static IMenuHandle menuWithParent(IWindow& parent)

  Returns the menu handle of the menu associated with the given parent window. If the given window has no menu, 0 is returned. This method is one way to obtain the menubar associated with an IFrameWindow.

Supported Platforms

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

owner

      public:
      virtual IWindow* owner() const

  Returns the menu's owner. This function may return 0 if either of the following occurs:

  - The menu was created without an owner
  - The owner window is not represented by an IWindow object
  Because a pointer value of 0 can cause unpredictable behavior, check the value of the returned pointer before using it.

Supported Platforms

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

show

      public:
      virtual IMenu& show(bool showMenu = true)

  Makes the menu visible.
  Note: Another window occurring earlier in the Z-order might still obscure this menu.

Supported Platforms

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

window

      public:
      virtual IWindow* window() const

  Returns the IWindow object which underlies this menu (for those platforms where menus have underlying windows).

Supported Platforms

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

setWindow

      protected:
      void setWindow(IWindow* window)

  Sets the IWindow object which underlies this menu (for those platforms where menus have underlying windows). This method must be called in the constructor(s) of any IMenu-derived class. If an IMenu-derived class constructor constructs an IWindow to pass in this call, that class's destructor is also responsible for deleting it and then calling this method with a 0 pointer. This insures that the parent class destructor does not also try to destroy the underlying IWindow.

  It is not necessary for classes derived from IMenuBar, IPopUpMenu, ISubMenu or ISystemMenu to call this method; those classes take care of it.

Supported Platforms

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

### Item Properties

Menu item properties are general characteristics of a menu item. You can create an IMenuItem object for an item in the menu to manipulate properties of the item. You can also directly obtain certain properties of the menu, such as the number of items contained in it or the rectangle of a particular item.

conditionalCascade

      public:
      virtual unsigned long
        conditionalCascade( unsigned long itemWithSubmenuId )

  Returns the default item for a conditionally cascading menu. You can use this function to retrieve the default item previously set by IMenu::setConditionalCascade. An exception is thrown if either of the following conditions exist:

  - The specified item for itemWithSubmenuId does not exist.
  - The specified item for itemWithSubmenuId does not have a submenu attached.
  itemWithSubmenuId
    The identifier of the conditionally cascading menu item whose default selection identifier you want.

Supported Platforms

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

enableUpdate

      public:
      virtual IMenu& enableUpdate(bool enableWindow = true)

  Enables or disables drawing changes to a menu on the screen.

Supported Platforms

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

isShowing

      public:
      bool isShowing() const

  If any part of the menu is showing, true is returned. Otherwise, false is returned.
  Note: A menu can be visible and yet not be showing if it is covered by another window.

Supported Platforms

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

Windows Considerations

  On Windows platforms, this method behaves the same as isVisible; that is, it returns true if the menu is marked visible even if it is obscured by another window.

isVisible

      public:
      bool isVisible() const

  If the menu's style is set to visible, true is returned. Otherwise, false is returned.
  Note: A menu can have the style visible and yet not be showing if it is covered by another window.

Supported Platforms

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

itemHelpId

      public:
      unsigned long itemHelpId(unsigned long menuItemId) 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 this menu with a help instance. See the IHelpWindow class for more information.

Supported Platforms

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

itemRect

      public:
      IRectangle itemRect(unsigned long itemId) const

  Returns the bounding rectangle of a menu item.

Supported Platforms

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

OS/2 Considerations

  The bounding rectangle is the rectangle returned by sending the message MM_QUERYITEMRECT.

menuHandle

      public:
      virtual IMenuHandle menuHandle() const

  Returns the handle object for the menu.

Supported Platforms

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

menuItem

      public:
      IMenuItem menuItem(unsigned long itemId) const

  Returns an IMenuItem object. If the menu does not have a menu item with an ID equal to itemId, an exception is thrown.

Exception

  IInvalidRequest | The menu item identifier is invalid. Verify that the identifier represents an item in the menu.

Supported Platforms

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

numberOfItems

      public:
      unsigned long
        numberOfItems( unsigned long forSubmenuId = 0 ) const

  Returns the number of menu items for the specified submenu. If you specify 0, the count is returned for the IMenu object.

Supported Platforms

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

AIX Considerations

  In X-Motif, the library queries the resource XmNnumChildren to determine the number of items in a menu or submenu.

refresh

  Invalidates or updates all or part of the menu.

  Overload 1

      public:
      virtual IMenu&
        refresh( IWindow::RefreshType type = IWindow::paintAll )

  This method invalidates the entire window according to the specified type of refresh protocol.

Supported Platforms

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

  Overload 2

      public:
      virtual IMenu&
        refresh( const IRectangle& invalidRectangle,
                 bool immediate = false )

  This method invalidates the area specified by the given rectangle.

Supported Platforms

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

removeConditionalCascade

      public:
      virtual IMenu&
        removeConditionalCascade( unsigned long itemWithSubmenuId )

  Removes conditional cascade behavior from the specified menu item.

  itemWithSubmenuId
    The identifier of the menu item from which to remove conditional cascade behavior. If you specify an itemWithSubmenuId that does not exist or does not have an associated submenu, an exception is thrown.

Exception

  IInvalidRequest | The menu item identifier is invalid. Verify that the identifier represents an item in the menu.

Supported Platforms

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

AIX Considerations

  X-Motif does not support conditionally cascading menus.

setConditionalCascade

      public:
      virtual IMenu&
        setConditionalCascade( unsigned long itemWithSubmenuId,
                               unsigned long defaultItemId )

  Enables conditionally cascading menus. You can use this function to change the default item on a menu that is already a conditionally cascaded menu. An exception is thrown if either of the following conditions exist:

  - The specified items for itemWithSubmenuId or defaultItemId do not exist.
  - The specified item for itemWithSubmenuId does not have a submenu attached.
  itemWithSubmenuId
    The identifier of the menu item to have its submenu set as a conditionally cascading menu.
  defaultItemId
    The identifier of the default selection.

Exception

  IInvalidRequest | The menu item identifier is invalid. Verify that the identifier represents an item in the menu.

Supported Platforms

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

AIX Considerations

  X-Motif does not support conditionally cascading menus.

setItemHelpId

      public:
      virtual IMenu&
        setItemHelpId( unsigned long menuItemId,
                       unsigned long helpTopicId )

  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 this menu with a help instance. See the IHelpWindow class for more information.

Supported Platforms

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

### Removing Items

You can remove menu items or submenus by providing the item identifier of the item to remove.

deleteItem

      public:
      virtual IMenu& deleteItem(unsigned long itemId)

  Deletes the item with the specified identifier from the menu.

Exception

  IInvalidRequest | The menu item identifier is invalid. Verify that the identifier represents an item in the menu.

Supported Platforms

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

removeSubmenu

      public:
      virtual IMenu&
        removeSubmenu( unsigned long itemWithSubmenuId )

  Removes the menu item's submenu indicator and destroys the submenu.

  itemWithSubmenuId
    The identifier of the item whose submenu is to be removed.

Supported Platforms

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

### Replacing Items

You replace a menu item to change the text or graphic displayed on the button face or to create a submenu. You can also replace a menu item with an IMenuItem object. It is often convenient to create an IMenuItem object using menuItem, make the appropriate changes to the IMenuItem object, and then replace the item in the menu object using setItem.

setBitmap

  Causes a menu item to display a bitmap.

  Overload 1

      public:
      virtual IMenu&
        setBitmap( unsigned long menuItemId,
                   unsigned long newBitmapResId )

  Use this function when you want Open Class Library to load the bitmap from the default resource library.

  menuItemId
    The identifier of the menu item to add the bitmap to.
  newBitmapResId
    The bitmap to display. This parameter accepts the resource identifier of a bit map in the default resource library.

Supported Platforms

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

  Overload 2

      public:
      virtual IMenu&
        setBitmap( unsigned long menuItemId,
                   const IBitmapHandle& bitmapHandle )

  Use this function when you already have the bitmap loaded.

  menuItemId
    The identifier of the menu item to add the bitmap to.
  bitmapHandle
    The handle of the bitmap to display.

Supported Platforms

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

  Overload 3

      public:
      virtual IMenu&
        setBitmap( unsigned long menuItemId,
                   const IResourceId& newBitmapResId )

  Use this function when you want Open Class Library to load the bitmap from the resource library you specified when you created the IResourceId object.

  menuItemId
    The identifier of the menu item to add the bitmap to.
  newBitmapResId
    The bitmap to display. This parameter accepts the resource identifier of a bitmap.

Supported Platforms

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

setItem

      public:
      virtual IMenu& setItem(const IMenuItem& menuItem)

  Replaces a specified menu item's style and representation.

Exception

  IInvalidRequest | The system could not insert the menu item. This may be due to lack of system resources.
  IInvalidRequest | The menu item could not be updated with the bitmap.
  IInvalidRequest | The bitmap handle is invalid or missing. Verify that the bitmap handle is valid or that the bitmap resource exists.

Supported Platforms

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

setSubmenu

      public:
      virtual IMenu&
        setSubmenu( unsigned long itemId,
                    const IResourceId& submenuResId )

  Creates a menu and sets it as the menu item's submenu.

  itemId
    The menu item ID that causes a submenu to be displayed when it is selected. The menu item must already exist.
  submenuResId
    The resource ID of the submenu to be set.

Exception

  IInvalidRequest | An attempt was made to add the menu bar as a submenu. The menu bar cannot be added as a submenu.

Supported Platforms

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

Windows Considerations

  To support menus loaded from a resource file, IMenu classes have the following requirements:

  - Menu resources must be defined using the MENUEX keyword.
  - Unique IDs must be provided for all pop-up menu items, indicated by the POPUP keyword.

setText

  Replaces a specified menu item's text.

  menuItemId
    ID of the menu item whose text will be set.
  newText
    New text for the menu item.
  newTextResId
    Resource ID of the new text for the menu item.

  Overload 1

      public:
      virtual IMenu&
        setText( unsigned long menuItemId,
                 const char* newText )

Exception

  IInvalidRequest | The system could not insert the menu item. This may be due to lack of system resources.

Supported Platforms

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

  Overload 2

      public:
      virtual IMenu&
        setText( unsigned long menuItemId,
                 const IResourceId& newTextResId )

Supported Platforms

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

### Selection

Selection functions allow you to determine if a menu item is selectable (enabled) or is displaying a selection state indicator. You can also change these properties.

checkItem

      public:
      virtual IMenu&
        checkItem( unsigned long itemId,
                   bool check = true )

  Places a select state indicator to the left of the specified item. The default visual of this indicator is a check mark.

  itemId
    The identifier of the menu item to add or remove the indicator from.
  check
    An optional boolean parameter that specifies whether the menu item indicator should be added or removed.
  Note: You cannot use this function on the menu bar.

Exception

  IInvalidRequest | The menu item identifier is invalid. Verify that the identifier represents an item in the menu.
  IInvalidRequest | The system could not insert the menu item. This may be due to lack of system resources.

Supported Platforms

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

AIX Considerations

  The select state indicator is a square object to the left of the specified item.

  In Motif, the resources XmNset and XmNindicatorOn are set to check or uncheck a menu item.

OS/2 Considerations

  The select state indicator is a check mark to the left of the specified item.

disableItem

      public:
      virtual IMenu& disableItem(unsigned long itemId)

  Prevents the menu item with the specified identifier from being selected.

Supported Platforms

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

AIX Considerations

  In X-Motif, the resource XmNsensitive is set by invoking XtSetSensitive to enable or disable a menu item.

enableItem

      public:
      virtual IMenu&
        enableItem( unsigned long itemId,
                    bool enable = true )

  Makes a menu item selectable.

  itemId
    The identifier of the menu item to be enabled or disabled.
  enable
    Specifies whether the menu item should be enabled. Optional.

Exception

  IInvalidRequest | The menu item identifier is invalid. Verify that the identifier represents an item in the menu.
  IInvalidRequest | The system could not insert the menu item. This may be due to lack of system resources.

Supported Platforms

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

AIX Considerations

  In X-Motif, the resource XmNsensitive is set by invoking XtSetSensitive to enable or disable a menu item.

isItemChecked

      public:
      bool isItemChecked(unsigned long itemId) const

  If the menu item with the specified identifier is checked, true is returned. Otherwise, false is returned.

Exception

  IInvalidRequest | The menu item identifier is invalid. Verify that the identifier represents an item in the menu.

Supported Platforms

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

AIX Considerations

  In X-Motif, the resources XmNset and XmNindicatorOn are queried to determine if a menu item is checked.

isItemEnabled

      public:
      bool isItemEnabled(unsigned long itemId) const

  If the menu item with the specified identifier is selectable, true is returned. Otherwise, false is returned.

Exception

  IInvalidRequest | The menu item identifier is invalid. Verify that the identifier represents an item in the menu.

Supported Platforms

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

selectItem

      public:
      virtual IMenu& selectItem(unsigned long itemId)

  Selects the menu item with the specified identifier.

Exception

  IInvalidRequest | The menu item identifier is invalid. Verify that the identifier represents an item in the menu.

Supported Platforms

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

AIX Considerations

  In X-Motif, the resource XmNset is set to select a menu item.

uncheckItem

      public:
      virtual IMenu& uncheckItem(unsigned long itemId)

  Removes the select state indicator from the menu item with the specified identifier.

Supported Platforms

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

AIX Considerations

  In X-Motif, the resources XmNset and XmNindicatorOn are set to check or uncheck a menu item.

### Styles

IMenu defines objects of the nested class IMenu::Style. You can use these styles with the function IMenu::setDefaultStyle.

defaultStyle

      public:
      static Style defaultStyle()

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

Supported Platforms

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

setDefaultStyle

      public:
      static void setDefaultStyle(const Style& aStyle)

  Sets the default style for all subsequent menus.

  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 menu class and do not specifically specify menu 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 menus 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

classDefaultStyle

      public:
      static const Style classDefaultStyle

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

Supported Platforms

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

noStyle

      public:
      static const Style noStyle

  Specifies that no style applies to the menu.

Supported Platforms

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

visible

      public:
      static const Style visible

  Serves the same purpose as IWindow::visible.

Supported Platforms

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

### IMenu - Inherited Member Functions and Data

#### Inherited Public Functions

  INotifier

  -     virtual ~INotifier()

  -     virtual INotifier& disableNotification() = 0

  -     virtual INotifier&
          enableNotification( bool enable = true ) = 0

  -     INotifier()

  -     virtual bool isEnabledForNotification() const = 0

  -     virtual INotifier&
          notifyObservers( const INotificationEvent& event ) = 0

  -     virtual INotifier&
          notifyObserversAsync( const INotificationEvent& event )

  -     const IThreadId& threadId() const

  IStandardNotifier

  -     virtual ~IStandardNotifier()

  -     virtual IStandardNotifier& disableNotification()

  -     virtual IStandardNotifier&
          enableNotification( bool enable = true )

  -     virtual bool isEnabledForNotification() const

  -     IStandardNotifier(const IStandardNotifier& copy)

  -     IStandardNotifier()

  -     virtual INotifierAddress notifierAddress() const

  -     virtual IStandardNotifier&
          notifyObservers( const INotificationEvent& anEvent )

  -     virtual IStandardNotifier&
          notifyObserversAsync( const INotificationEvent& anEvent )

  -     IStandardNotifier&
          operator =( const IStandardNotifier& aStandardNotifier )

#### Inherited Public Data

  INotifier

  -     static INotificationId const allChangesId

  -     static INotificationId const deleteId

#### Inherited Protected Functions

  IStandardNotifier

  -     virtual IStandardNotifier&
          addObserver( IObserver& observer,
                       const IInterest& interest )

  -     virtual IStandardNotifier&
          notifyObservers( const INotificationId& nId )

  -     virtual IObserverList&
          observerList( const IInterest* anInterest = 0 ) const

  -     virtual IStandardNotifier& removeAllObservers()

  -     virtual IStandardNotifier&
          removeObserver( IObserver& observer,
                          const IInterest& interest )

  -     virtual IStandardNotifier&
          removeObserver( IObserver& observer )

  INotifier

  -     virtual INotifier&
          addObserver( IObserver& observer,
                       const IInterest& interest )

  -     virtual INotifier&
          notifyObservers( const INotificationId& id ) = 0

  -     virtual IObserverList&
          observerList( const IInterest* anInterest = 0 ) const = 0

  -     virtual INotifier& removeAllObservers() = 0

  -     virtual INotifier& removeObserver(IObserver& observer) = 0

  -     virtual INotifier&
          removeObserver( IObserver& observer,
                          const IInterest& interest )

#### Inherited Protected Data

  - None