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:

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:


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.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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


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


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


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

Inherited Public Data

Inherited Protected Functions

IHandler

Inherited Protected Data