### ISubmenu

  The ISubmenu class creates a submenu object from a menu handle. This class overrides functions of IMenu to provide menu item functions that can be restored. The menu item functions in this class act upon this ISubmenu object. Any changes are undone when the menu ends.

#### AIX Considerations

  The Open Class Library adds a Motif callback routine to all submenus to enable processing of the following menu events:

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

### ISubmenu - Member Functions and Data by Group

### Constructors & Destructor

You can construct and destruct objects of this class. You cannot copy or assign ISubmenu objects because both the copy constructor and assignment operator are private functions.

~ISubmenu

      public:
      virtual ~ISubmenu()

Supported Platforms

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

ISubmenu

      public:
      ISubmenu(const IMenuHandle& submenuHandle)

  Creates an ISubmenu object from the handle of an existing submenu. One of the primary uses of this constructor is in the implementation of the IMenuHandler class.

Supported Platforms

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

### Adding Items

You can add textual, graphical, submenu, or separator items to a submenu object. You can also construct an object of the IMenuItem class and add it to the submenu object. In these overridden versions, the item is always added to this ISubmenu object. You do not need to specify the intoSubmenuId parameter because it is always assumed to have the value of the identifier of this submenu.
Note: Use a value between 1 and 65565 for the item identifier in these functions. Values outside the recommended range can 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 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 ISubmenu&
        addBitmap( unsigned long newItemId,
                   const IResourceId& newItemBitmapResId,
                   unsigned long intoSubmenuId = 0 )

  Use this version to load a bitmap from the resource library that you specified when you created the IResourceId object. The parameters are the following:

  newItemId
    The identifier of the new menu item to add to a menu or submenu.
  newItemBitmapResId
    The resource identifier of the bitmap for the new menu item.
  intoSubmenuID
    Not used. It is only present to allow this function to override the function inherited from IMenu.

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets to use for specific purposes in menus. Pull-down menus can contain the following widgets and gadgets:

  - CascadeButton
  - ToggleButton
  - Label
  - Separator

  Overload 2

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

  Use this version to add a bitmap you already have loaded into a menu item. The parameters are the following:

  newItemId
    The identifier of the new menu item to add to a menu or submenu.
  itemBitmap
    The handle of the bitmap for the new menu item.
  intoSubmenuID
    Not used. It is only present to allow this function to override the function inherited from IMenu.

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets to use for specific purposes in menus. Pull-down menus can contain the following widgets and gadgets:

  - CascadeButton
  - ToggleButton
  - Label
  - Separator

  Overload 3

      public:
      virtual ISubmenu&
        addBitmap( unsigned long newItemId,
                   unsigned long newItemBitmapResId,
                   unsigned long intoSubmenuId = 0 )

  Use this version to load a bitmap from the default resource library. The parameters are the following:

  newItemId
    The identifier of the new menu item to add to a menu or submenu.
  newItemBitmapResId
    The identifier of the bitmap for the new menu item.
  intoSubmenuID
    Not used. It is only present to allow this function to override the function inherited from IMenu.

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets to use for specific purposes in menus. Pull-down menus can contain the following widgets and gadgets:

  - CascadeButton
  - ToggleButton
  - Label
  - Separator

addItem

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

  Adds a menu item represented by an IMenuItem object as the last item in a menu or submenu. The optional intoSubmenuId is ignored. It is only present to allow this function to override the function inherited from IMenu.

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets to use for specific purposes in menus. Pull-down menus can contain the following widgets and gadgets:

  - CascadeButton
  - ToggleButton
  - Label
  - Separator

addSeparator

  Adds a separator menu item with the specified identifier as the last item in a submenu.

  Overload 1

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

Supported Platforms

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

  Overload 2

      public:
      virtual ISubmenu& addSeparator(unsigned long newItemId = 0)

  Note: IMenu also has an addSeparator function that accepts a single parameter. But while the parameter for IMenu::addSeparator is intoSubmenuId, the parameter for this version of addSeparator is newItemId.

Supported Platforms

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

addText

  Adds a text menu item as the last item in a menu or submenu. The optional intoSubmenuId is ignored. It is only present to allow this function to override the function inherited from IMenu.

  Overload 1

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

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets to use for specific purposes in menus. Pull-down menus can contain the following widgets and gadgets:

  - CascadeButton
  - ToggleButton
  - Label
  - Separator

  Overload 2

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

Supported Platforms

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

AIX Considerations

  X-Motif provides specific widgets and gadgets to use for specific purposes in menus. Pull-down menus can contain the following widgets and gadgets:

  - CascadeButton
  - ToggleButton
  - Label
  - Separator

### Cursored Operations

Cursored operations use objects of the ISubmenu::Cursor nested class to designate which menu item is to be acted upon. You can use these members to access each item in the menu without knowing the menu item identifiers. In these overridden versions, information is stored about the change so that the change can be undone.

add

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

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

Supported Platforms

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

addAsNext

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

  Adds the specified menu item as the next item in the submenu and sets the specified cursor there.

Supported Platforms

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

cursor

      public:
      Cursor cursor(unsigned long itemId) const

  Returns an ISubmenu::Cursor object and sets the cursor to point to the specified menu item.

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 ISubmenu& deleteAt(Cursor& cursor)

  Deletes the menu item at the position of the specified cursor and sets the cursor to the menu item that precedes the deleted menu item.

Supported Platforms

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

elementAt

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

  Returns the menu item at the position of the specified cursor.

Supported Platforms

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

removeSubmenuAt

      public:
      virtual ISubmenu& removeSubmenuAt(Cursor& cursor)

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

Supported Platforms

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

### Properties

Use property members to obtain general information about the submenu.

handle

      public:
      virtual IMenuHandle handle() const

  Returns the submenu handle. This function is equivalent to menuHandle.

Supported Platforms

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

AIX Considerations

  The handle returned is the handle of the underlying window.

OS/2 Considerations

  The handle returned is the handle of the underlying window.

Windows Considerations

  The handle returned is the underlying HMENU.

menuHandle

      public:
      virtual IMenuHandle menuHandle() const

  Returns the submenu handle. This function is equivalent to handle.

Supported Platforms

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

AIX Considerations

  The handle returned is the handle of the underlying window.

OS/2 Considerations

  The handle returned is the handle of the underlying window.

### Removing Items

These members delete menu items and remove a submenu of the instances of this submenu class. In these overridden versions, information is stored about the change so that the change can be undone.

deleteItem

      public:
      virtual ISubmenu& deleteItem(unsigned long itemId)

  Removes the specified item from a 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 ISubmenu&
        removeSubmenu( unsigned long itemWithSubmenuId )

  Removes the menu item submenu indicator and destroys the submenu. Typically, you use this member function to remove cascading menus.

Supported Platforms

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

### Replacing Items

You replace a menu item to change the text or graphic displayed by the item or to create a submenu. You can also replace a menu item with an IMenuItem object. You can create an IMenuItem object using the menuItem function, make the appropriate changes to the IMenuItem object, and then replace the item in the menu object using the setItem function.

This class overrides inherited functions for replacing menu items. In these overridden versions, information is stored about the change so that the change can be undone. In addition, with these versions, the item is always added to this ISubmenu object. You do not need to specify the intoSubmenuId parameter because it is always assumed to have the value of the identifier of this submenu.

setBitmap

  Replaces a specified menu item with a bitmap.

  Overload 1

      public:
      virtual ISubmenu&
        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 bitmap in the default resource library.

Supported Platforms

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

  Overload 2

      public:
      virtual ISubmenu&
        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

  Overload 3

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

  Use this function when you 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

setItem

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

  Replaces a specified menu item's style and representation.

Supported Platforms

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

setText

  Replaces a specified menu item's text.

  Overload 1

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

Supported Platforms

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

  Overload 2

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

Supported Platforms

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

### Selection

Use selection members to determine if a menu item is selectable (enabled) or is displaying a selection state indicator. You can also change these properties. The ISubmenu class overrides these IMenu selection members so that information about how the menu was changed can be stored. The stored information allows the changes to be undone later.

checkItem

      public:
      virtual ISubmenu&
        checkItem( unsigned long itemId,
                   bool checked = true )

  Places a selection state indicator to the left of the item with the specified identifier.

Supported Platforms

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

AIX Considerations

  The selection state indicator is a square-shaped object to the left of the specified item.

OS/2 Considerations

  The selection state indicator is a check mark in front of the menu item.

Windows Considerations

  The selection state indicator is a check mark in front of the menu item.

disableItem

      public:
      virtual ISubmenu& disableItem(unsigned long itemId)

  Makes the menu item with the specified identifier unselectable.

Supported Platforms

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

enableItem

      public:
      virtual ISubmenu&
        enableItem( unsigned long itemId,
                    bool enabled = true )

  Makes the menu item with the specified identifier selectable.

Supported Platforms

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

uncheckItem

      public:
      virtual ISubmenu& uncheckItem(unsigned long itemId)

  Removes the selection state indicator from the left of the item with the specified identifier.

Supported Platforms

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

AIX Considerations

  The selection state indicator is a square-shaped object to the left of the specified item.

OS/2 Considerations

  The selection state indicator is a check mark in front of the menu item.

Windows Considerations

  The selection state indicator is a check mark in front of the menu item.

### Undo

Undo members support restoring the ISubmenu to the state that existed before the use of ISubmenu members. You usually do not have to call these functions because the IMenuHandler class calls them automatically.

undo

      public:
      virtual ISubmenu& undo()

  Reverses all the changes made to the menu using the ISubmenu member functions.

Supported Platforms

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

### ISubmenu - Inherited Member Functions and Data

#### Inherited Public Functions

  IMenu

  -     virtual ~IMenu()

  -     virtual IMenu& add(IMenuItem& menuItem, Cursor& cursor)

  -     virtual IMenu&
          addAsNext( IMenuItem& menuItem,
                     Cursor& cursor )

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

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

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

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

  -     virtual IMenu&
          addSeparator( unsigned long newItemId,
                        unsigned long intoSubmenuId )

  -     virtual IMenu&
          addSeparator( unsigned long intoSubmenuId = 0 )

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

  -     virtual IMenu& addSubmenu(unsigned long itemId)

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

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

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

  -     virtual unsigned long
          conditionalCascade( unsigned long itemWithSubmenuId )

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

  -     static Style defaultStyle()

  -     virtual IMenu& deleteAt(Cursor& cursor)

  -     virtual IMenu& deleteItem(unsigned long itemId)

  -     virtual IMenu& disableItem(unsigned long itemId)

  -     virtual IMenu& disableUpdate()

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

  -     virtual IMenu& enableUpdate(bool enableWindow = true)

  -     virtual IWindowHandle handle() const

  -     virtual IMenu& hide()

  -     virtual unsigned long id() const

  -     IMenu(const IMenuHandle& menuHandle)

  -     virtual bool isFrameWindow() const

  -     bool isItemChecked(unsigned long itemId) const

  -     bool isItemEnabled(unsigned long itemId) const

  -     bool isShowing() const

  -     virtual bool isValid() const

  -     bool isVisible() const

  -     unsigned long itemHelpId(unsigned long menuItemId) const

  -     IDMItemProvider* itemProvider() const

  -     IRectangle itemRect(unsigned long itemId) const

  -     IMenuItem menuItem(unsigned long itemId) const

  -     static IMenuHandle menuWithParent(IWindow& parent)

  -     unsigned long
          numberOfItems( unsigned long forSubmenuId = 0 ) const

  -     virtual IWindow* owner() const

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

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

  -     virtual IMenu&
          removeConditionalCascade( unsigned long itemWithSubmenuId )

  -     virtual IMenu&
          removeSubmenu( unsigned long itemWithSubmenuId )

  -     virtual IMenu& removeSubmenuAt(Cursor& cursor)

  -     virtual IMenu& selectItem(unsigned long itemId)

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

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

  -     virtual IMenu&
          setBitmap( unsigned long menuItemId,
                     unsigned long newBitmapResId )

  -     virtual IMenu&
          setConditionalCascade( unsigned long itemWithSubmenuId,
                                 unsigned long defaultItemId )

  -     static void setDefaultStyle(const Style& aStyle)

  -     virtual IMenu& setItem(const IMenuItem& menuItem)

  -     virtual IMenu&
          setItemHelpId( unsigned long menuItemId,
                         unsigned long helpTopicId )

  -     IMenu& setItemProvider(IDMItemProvider* dragProvider)

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

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

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

  -     virtual IMenu& show(bool showMenu = true)

  -     virtual IMenu& uncheckItem(unsigned long itemId)

  -     virtual IWindow* window() const

  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()

  -     IStandardNotifier(const IStandardNotifier& copy)

  -     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

  IMenu

  -     static const Style classDefaultStyle

  -     static const Style noStyle

  -     static const Style visible

#### Inherited Protected Functions

  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,
                          const IInterest& interest )

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

  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 )

  IMenu

  -     IMenu()

  -     void setWindow(IWindow* window)

#### Inherited Protected Data

  - None