IMenuHandler

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:

true
The menu event requires no additional processing. Do not pass it to another handler.
false
The menu event may require additional processing. Pass the menu event to the next handler for additional processing, as follows:
  • If there is another handler for the frame window or control, pass the menu event to the next handler.
  • If this is the last handler for the frame window or control, call IWindow::defaultProcedure to process the menu event.


IMenuHandler - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IMenuHandler
public:
IMenuHandler()

Default constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Dispatching

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.


[view class]
dispatchHandlerEvent
protected:
virtual bool dispatchHandlerEvent(IEvent& event)

If a menu event is received, this function calls the appropriate virtual function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Processing

Event-processing members are called when an event occurs that may need to be processed by this handler.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

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.

OS/2 Considerations

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.


Menu Emphasis

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.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeSourceEmphasis
protected:
virtual void removeSourceEmphasis( const IMenuEvent& menuEvent )

Calls IWindow::hideSourceEmphasis.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IMenuHandler - Inherited Member Functions and Data

Inherited Public Functions

IHandler

Inherited Public Data

Inherited Protected Functions

IHandler

Inherited Protected Data