### 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.

~IMenuHandler

      public:
      virtual ~IMenuHandler()

Supported Platforms

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

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.

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.

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:

  - Create and show a pop-up menu
  - Show an existing pop-up menu

  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:

  - Available free storage, if you use the global operator new
  - The stack
  - Statically

  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

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

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:

  - Using arrow keys
  - Moving the mouse pointer over the menu item while pressing the select button (typically, mouse button 1)
  - Using the Alt or F10 keys
    Note: These keys only highlight the first item on your menu bar and cause this function to be called.

  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

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.

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

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

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

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IHandler

  -     virtual IEventResult defaultProcedure(IEvent& event)

  -     virtual bool dispatchHandlerEvent(IEvent& event) = 0

#### Inherited Protected Data

  - None