### ICommandHandler

  The ICommandHandler class processes application command and system command events.

  Create a handler derived from ICommandHandler and attach it to the following, as needed:

  - The client window
  - The frame window
  - Another appropriate window, such as the owner window of a push button

  You can attach a command handler by using IHandler::handleEventsFor to pass the appropriate window to the command handler.

  When the command handler receives a command event, it creates an ICommandEvent object and routes that object to the appropriate ICommandHandler virtual function. You must override these "Event Processing" virtual functions to supply your own specialized processing of a command event.

  Push buttons and menu items (including pop-up menu items) send a command event to their owner window. Accelerators send a command event to their frame window. Only frames, canvases, and containers have support to pass on an unprocessed command event. Canvases and containers forward events to their owner window. A frame window passes application commands and the SC_CLOSE system command to its client window.

  The return value from the virtual functions specifies whether the command event is passed on for additional processing, as follows:

  true
    The command event requires no additional processing. Do not pass it to another handler.
  false
    Pass on the command event for additional processing, as follows:
    - If there is another handler for the window, pass the command event to the next handler.
    - If this is the last handler for the window, call IWindow::defaultProcedure to process the command event.

  You can attach an ICommandHandler directly to a control, but the control must be its own owner in this case. However, an owner window is also used for passing on unprocessed keyboard and mouse events. As a result, if you choose to have a control own itself, you lose substantial support for that control. For example, if you have a push button own itself, you lose all dialog-box support for the push button, such as Tab-key support and default push button support.

  You can attach the following:

  - The same handler to more than one window
  - More than one handler, of either the same or different types, to the same window
  Note: Because IFrameHandler and ICnrMenuHandler also processes ICommandEvents, think of them as if you had more than one ICommandHandler attached to a window. If you attach an IFrameHandler or ICnrMenuHandler to the same window as an ICommandHandler, your ICommandHandler might not be called, depending on the order in which you attached these handlers.

#### AIX Considerations

  Motif has no concept of command events. However, an event that is a logical abstraction above button press, menu selection, and accelerator-key press is a useful construct. Therefore, the Open Class Library provides a Motif implementation that supports ICommandEvents, their creation, propagation, and handling.

  These events are implemented as true X events. The library uses an unmaskable client message event with event data that not only identifies it as a command event, but also provides all other information needed to construct an ICommandEvent. The control classes derived from IWindow, which in Presentation Manager produce WM_COMMAND messages, are responsible for generating this X client message event. The Open Class Library uses IWindowHandle::sendEvent to send the event to X. The control sends the event to its owner widget, which matches Presentation Manager's system behavior for routing WM_COMMAND messages.

#### OS/2 Considerations

  If the frame window is a page window of a notebook, the notebook does not use the accelerators of that frame. Only the accelerators of the frame window above the notebook in the parent chain are used.

### ICommandHandler - Member Functions and Data by Group

### Constructors & Destructor

You can construct and destruct objects of this class.

~ICommandHandler

      public:
      virtual ~ICommandHandler()

Supported Platforms

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

ICommandHandler

      public:
      ICommandHandler()

  Constructs the default command handler.

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 ICommandHandler object processes only command events.

dispatchHandlerEvent

      protected:
      virtual bool dispatchHandlerEvent(IEvent& event)

  Calls the appropriate virtual function if a command event is received.

Supported Platforms

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

### Event Processing

A command handler contains event-processing members that you can use to process either an application or system command event. Override at least one of these virtual functions in a derived class.

command

      protected:
      virtual bool command(ICommandEvent& event)

  Implemented by derived classes to handle application command events. You can use the function IEvent::window to reference the window to which the event is dispatched. Also, consider having your derived ICommandHandler class contain a data member that is a pointer to the window being handled.

Supported Platforms

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

systemCommand

      protected:
      virtual bool systemCommand(ICommandEvent& event)

  Implemented by derived classes to handle the system command events.

  You can check if the command is a predefined system command by comparing the value returned by ICommandEvent::commandId against the ISystemMenu item identifiers.

Supported Platforms

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

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