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:


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.


[view class]
~ISubmenu
public:
virtual ~ISubmenu()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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


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

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

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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


[view class]
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
INotifier
IStandardNotifier

Inherited Public Data

INotifier
IMenu

Inherited Protected Functions

INotifier
IStandardNotifier
IMenu

Inherited Protected Data