The IMenuHandler class processes all types of menu events except menu command events, which are handled by the class ICommandHandler. You can override IMenuHandler::menuShowing to make changes via the ISubmenu object that is passed as a parameter. You can also use this class to display a pop-up menu. If you want to display pop-up menus for IContainerObject or IContainerControl objects, use the ICnrMenuHandler-derived class.
Create a handler derived from IMenuHandler and attach it to a frame window for a regular menu or to a control for a pop-up menu. You can do this by calling IHandler::handleEventsFor to pass the appropriate frame window or control to the menu handler.
When the menu handler receives a menu event, it creates an IMenuEvent object and routes that object to the appropriate IMenuHandler virtual functions. Override these virtual functions to supply your own specialized processing of a menu event.
The return value from the virtual functions specifies whether the menu event is passed on for additional processing, as follows:
You can construct and destruct objects of this class.
![]() |
public:
virtual ~IMenuHandler()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMenuHandler()
Default constructor.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The Open Class Library dispatches events that have been sent or posted to a window to the handlers attached to that window. It does this by calling the event-dispatching function of the handler objects. An IMenuHandler object processes only menu-related events.
![]() |
protected:
virtual bool dispatchHandlerEvent(IEvent& event)
If a menu event is received, this function calls the appropriate virtual function.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Event-processing members are called when an event occurs that may need to be processed by this handler.
![]() |
protected:
virtual bool makePopUpMenu(IMenuEvent& menuEvent)
Shows a pop-up menu. It is called when the user causes a context menu event to occur while the cursor is on top of a control associated with the IMenuHandler. A context menu event is associated with a context or pop-up menu. Within makePopUpMenu, you can do either of the following:
You can override this function to create and show a pop-up menu by using the class IPopUpMenu. Code your override function to return true if your program shows an IPopUpMenu; otherwise, code it to return false.
The user has dismissed the pop-up menu when IMenuHandler::menuEnded is called.
The storage for the IPopUpMenu object menu can be allocated from the following:
If you allocate the IPopUpMenu using the global operator new, you can create the menu object within makePopUpMenu and request that the Open Class Library delete your IPopUpMenu object automatically when the menu ends. To do this, call IWindow::setAutoDeleteObject for the IPopUpMenu after creating it. Your implementation of makePopUpMenu should then call IPopUpMenu::show and return true.
If you allocate the IPopUpMenu on the stack or statically, the allocation should be done outside of makePopUpMenu. In this case, makePopUpMenu only needs to show the menu and return true.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool menuEnded(IMenuEvent& menuEvent)
Processes a menu end event. It is called when a submenu, such as a pull-down menu, cascading menu, or pop-up menu ends.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool menuSelected(IMenuEvent& menuEvent)
Called when a menu item is selected.
This function or, if you have one, a derived implementation of this function, is called when a menu item (menu bar, pull-down menu, or cascade menu) is highlighted. A user can highlight a menu item by doing any of the following:
The class IInfoArea uses this function to determine the information text to display based on the highlighted menu item.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool menuShowing( IMenuEvent& menuEvent, ISubmenu& submenuAboutToShow )
Called before a submenu, such as a pull-down, cascading, or pop-up menu is shown the first time in a navigation sequence. If you navigate from one submenu to another and then return to the first submenu, menuShowing may not be called a second time for the same submenu. Making a selection ends the navigation sequence.
Overriding this method allows you to dynamically alter the contents of a submenu based on the state of your system at the moment the user goes to the menu. An example of this is disabling menu items that cannot be selected at this time.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
On Motif systems, menuShowing is called each time a submenu is shown. If you navigate from one submenu to another and then return to the first submenu, menuShowing will be called a second time for the same submenu. This is non-portable behavior; it is not true for Windows systems.
On OS/2 systems, menuShowing is called each time a submenu is shown. If you navigate from one submenu to another and then return to the first submenu, menuShowing will be called a second time for the same submenu. This is non-portable behavior; it is not true for Windows systems.
You may find it useful to give a special display emphasis to the user-interface element to which a menu applies. For example, if the user displays a pop-up menu for a list box, you could change the look of the list box items that would be affected by a selection from the pop-up.
![]() |
protected:
virtual void addSourceEmphasis(const IMenuEvent& menuEvent)
Calls IWindow::showSourceEmphasis. Although the IWindow implementation of showSourceEmphasis does nothing, some derived classes, such as IContainerControl, perform specialized processing for source emphasis.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual void removeSourceEmphasis( const IMenuEvent& menuEvent )
Calls IWindow::hideSourceEmphasis.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
virtual ~IHandler()
virtual IString asDebugInfo() const
virtual IString asString() const
virtual IHandler& disable()
virtual IHandler& enable(bool enable = true)
virtual IHandler& handleEventsFor(IWindow* window)
IHandler()
bool isEnabled() const
virtual IHandler& stopHandlingEventsFor(IWindow* window)
virtual IEventResult defaultProcedure(IEvent& event)
virtual bool dispatchHandlerEvent(IEvent& event) = 0