IMenu

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

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

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

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

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

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