Write an Event Handler

In general, writing an event handler can be divided into the following steps:

1. Determine which handler class processes the event.
2. Create a class derived from that handler class and override the event-handling functions.
3. Create an instance of your derived class.
4. Attach event handlers to the window.
5. Stop handling events for the window.

The Hello World application has several event handlers. The following example illustrates how to use the above steps to process user menu selections. The code shown is from Hello World version 3.

1. Determine which handler class processes the event.

   When you select a menu item, an ICommandEvent is generated. The handler class for this type of event is ICommandHandler.

2. Create a class derived from that handler class and override the event-handling functions.

   The Hello World application creates a new class called ACommandHandler that is derived from the ICommandHandler class. The virtual function, ICommandHandler::command processes command events. The class ACommandHandler overrides this function to provide its own command event handling.

   The following sample, taken from the ahellow3.hpp, file, shows the class declaration of ACommandHandler:

   class ACommandHandler : public ICommandHandler
   {
     public:
       ACommandHandler(AHelloWindow *helloFrame);
       virtual
        ~ACommandHandler() { };
   
     protected:
       virtual bool
         command(ICommandEvent& cmdEvent);
   
     private:
       AHelloWindow
        *frame;
   };

   The public constructor and private data member frame save a pointer to the frame window for which commands will be processed.

   The ACommandHandler command function provides command processing for AHelloWindow class objects. The definition of the command function is taken from ahellow3.cpp. The ID of the menu item is extracted from the command event object using the commandId member function, as follows:

   bool ACommandHandler :: command(ICommandEvent & cmdEvent)
   {
     bool eventProcessed(true);
   
     switch (cmdEvent.commandId())
     {
       case MI_CENTER:
         frame->setTextAlignment(AHelloWindow::center);
         break;
       case MI_LEFT:
         frame->setTextAlignment(AHelloWindow::left);
         break;
       case MI_RIGHT:
         frame->setTextAlignment(AHelloWindow::right);
         break;
       default:
         eventProcessed=false;
     } 
     return(eventProcessed);
   }

3. Create an instance of your derived class.

   Define a data member from your new handler class in your application window. The following code comes from the ahellow3.hpp file:

     ACommandHandler commandHandler;

   Construct the ACommandHandler object in the initializer of the constructor for the application window. This is shown in the ahellow3.cpp file:

   AHelloWindow :: AHelloWindow(unsigned long windowId)           
     : IFrameWindow(IFrameWindow::defaultStyle() |                
                    IFrameWindow::minimizedIcon,                  
                    windowId)                                                 
      ,menuBar(WND_MAIN, this)                                                
      ,statusLine(WND_STATUS, this, this)                                     
      ,hello(WND_HELLO, this, this)                                           
      ,infoArea(this)                                                         
      ,commandHandler(this)

4. Attach event handlers to the window.

   The base class IHandler provides a member function handleEventsFor to attach a handler to a window. In the Hello World application, ahellow3.cpp, the ACommandHandler begins processing command events for the AHelloWindow in its constructor with the following statement:

     commandHandler.handleEventsFor(this);

5. Stop handling events for the window.

   The base class IHandler provides a member function stopHandlingEventsFor to stop event processing for the window. In the Hello World application, ahellow3.cpp, the ACommandHandler stops processing command events for the AHelloWindow in its destructor with the following statement:

     commandHandler.stopHandlingEventsFor(this);

Windows
Events and Event Handlers

Hello World Version 3: Add Command Handlers and Menu Bars
Task and Samples Cross-Reference Table