### Hello World Version 3: Adding Command Handlers and Menu Bars

Version 3 provides a menu bar with an Alignment choice. A menu bar is the area near the top of a window, below the title bar and above the client area of the window, which contains a list of choices. By selecting the Alignment choice, the user can display a pull-down menu and align the "Hello, World!!!" text string to the left, right, or center. In addition, this version adds a status area to show the status of the text string and an event handler for the menu bar and the pull-down menu.

In covering these topics, this chapter shows you how to:

- Create a status line to show the status of the text string alignment
- Use an event handler
- Add a menu bar
- Set an initial check mark in the pull-down menu
- Add command processing (event handling) to align a text string

The main window for version 3 of the Hello World application looks like this:

#### Listing the Hello World Version 3 Files

The following files contain the code used to create version 3:

File | Type of Code
--- | ---
ahellow3.cpp | Source code for the main procedure, main window constructor, and command processing
ahellow3.hpp | Header file for the AHelloWindow and ACommandHandler classes
ahellow3.h | Symbolic definitions file for the hello3.exe file
ahellow3.rc | Resource file for the hello3.exe file
ahellow3.ico | Icon file for the hello3.exe file

#### The Primary Source Code File

The ahellow3.cpp file contains the source code for the main procedure and the AHelloWindow and ACommandHandler classes. The tasks performed by this code are described in the following sections.

#### The AHelloWindow Class Header File

The ahellow3.hpp file, like the ahellow2.hpp file, contains the class definitions and interface specifications for the AHelloWindow anACommandHandler classes, with a few modifications for version 3.

#### The Symbolic Definitions File

The ahellow3.h file contains the definitions for this application. These definitions provide the IDs for the application window components.

For version 3, the symbolic definition file contains a new window ID (WND_STATUS) for the status area and three new string IDs (STR_CENTER, STR_LEFT, and STR_RIGHT) for the text strings used in the status area. In addition, menu IDs (MI_ALIGNMENT, MI_CENTER, MI_LEFT, and MI_RIGHT) have been added for the menu bar Alignment choice and the Center, Left, and Right choices in the pull-down menu.

#### The Resource File

Version 3 provides a resource file, ahellow3.rc. This resource file assigns an icon and several text strings with the constants defined in the ahellow3.h file. It also contains the text strings for the menu bar. The ahellow3.h file is included in this resource file so the icon and text strings can be associated with the appropriate IDs.

The resource file for version 3 contains two primary additions. The first is the text strings that are assigned to the new string constants that were defined in ahellow3.h. These text strings are used in the status area to show the state of the static "Hello, World!!!" text string in the client area. For example, when the main window is first displayed, the "Center Alignment" text string is shown in the status area.

The second addition provides the text that appears on the menu bar (Alignment) and pull-down menu (Left, Center, and Right), indicating which choices are available. Each text string is assigned to a constant, also defined in ahellow3.h.

In an AIX or OS/2 resource file, the tilde (~) to the left of a letter in each text string indicates that the user can select those letters to select a menu item. This is an ampersand (&) in the Windows .rc file. In addition, the Windows .rc file uses the extended menu as follows:

    WND_MAIN  MENUEX
      BEGIN
        POPUP     "&Alignment"               ,  MI_ALIGNMENT
          BEGIN
            MENUITEM  "&Left"                    ,  MI_LEFT
            MENUITEM  "&Center"                  ,  MI_CENTER
            MENUITEM  "&Right"                   ,  MI_RIGHT
          END
      END

These are shortcut keys for the application. For example, pressing R aligns the "Hello, World!!!" text string on the right side of the main window, just as if the Right choice had been selected from the pull-down menu.

Open Class Library provides tools for converting OS/2, Windows, and AIX resources.

See Converting Resource Files for more information about the resource file conversion tool.

#### The Icon File

The ahellow3.ico file is used as both the title bar icon and the icon that displays when the application is minimized. This icon is the same as for version 2.

The Open Class Library provides tools to convert bitmaps and icons for the various platforms.

#### Exploring Hello World Version 3

The following sections describe each of the tasks performed by version 3 of the Hello World application that have not been described for previous versions.

#### Constructing the AHelloWindow Object

Version 3 has made the following additions to the main window:

- Creating a status line
- Creating a menu bar
- Setting an initial check mark in the pull-down menu
- Aligning a text string
- Setting AHelloWindow as the event handler
- Destructing the main window

The following sections describe these additions.

#### Creating a Status Line

The status line shows the text string alignment status. Use the IStaticText class to create the static text control to display a text string in a status area. The status area is a small rectangular area that is usually located at the top of a window, below the menu bar.

In the ahellow3.cpp file, an IStaticText object, called statusLine, is created with this instance of the AHelloWindow class as the parent and owner as follows:

    ,statusLine(WND_STATUS, this, this)

The WND_STATUS constant provides the window ID for this static text control. This constant is defined in ahellow3.h.

##### Specifying the Location and Height of the Status Area

Use the IFrameWindow member function addExtension in the ahellow3.cpp file to specify where the status area is positioned and how high it is. For example:

    addExtension(&statusLine,
                   IFrameWindow::aboveClient,
                   IFont(&statusLine).maxCharHeight());

The aboveClient argument of the Location enumeration specifies that the static text control displays the status area above the client window.

The maxCharHeight member function returns the status area's maximum height, based on the current font.

#### Creating a Menu Bar

Now you can create the Alignment menu bar to display the Left, Center, and Right choices. In the header file, ahellow3.hpp, menuBar is defined as an instance of the IMenuBar class as follows:

    private:
      IMenuBar
        menuBar;

The ahellow3.cpp file uses menuBar to create a new instance of that class in the main window, as follows:

    ,menuBar(windowId, this)

The WND_MAIN argument identifies the following menu in the ahellow3.rc resource file:

    MENU WND_MAIN                                         //Main Window Menu (WND_MAIN)
      BEGIN
            SUBMENU "~Alignment", MI_ALIGNMENT      //Alignment Submenu
              BEGIN
                MENUITEM "~Left",       MI_LEFT     //Left Menu Item - F7 Key
                MENUITEM "~Center",     MI_CENTER   //Center Menu Item - F8 Key
                MENUITEM "~Right",      MI_RIGHT    //Right Menu Item - F9 Key
              END
      END

The window ID for the menu must match the window ID of the frame window.

This menu puts one choice, Alignment, on the menu bar, and provides a pull-down menu with three choices: Left, Center, and Right.

In addition, the MI_ALIGNMENT, MI_LEFT, MI_CENTER, and MI_RIGHT menu item attributes correspond to those in the resource file's string table:

    MI_ALIGNMENT,"Alignment Menu"               //InfoArea - Alignment Menu
    MI_CENTER,  "Set Center Alignment"          //InfoArea - Center Menu
    MI_LEFT,    "Set Left Alignment"            //InfoArea - Left Menu
    MI_RIGHT,   "Set Right Alignment"           //InfoArea - Right Menu

When the user moves the selection cursor over each menu item, the text string associated with that menu item displays in the information area below the client window. For example, when the cursor is on the Right menu item, the text string "Set Right Alignment" appears in the information area. For this to work, the string ID must match the corresponding menu item ID.

#### Setting an Initial Check Mark in the Pull-Down Menu

The pull-down menu that displays when the Alignment choice is selected on the menu bar contains three choices for aligning the "Hello, World!!!" text string: Left, Center, and Right. Because this text string is aligned in the center of the client area when the application is created, a check mark should display next to the Center choice the first time the pull-down menu displays.

The checkItem member function of the IMenuBar class lets you place a check mark on a pull-down menu choice. The following line, from ahellow3.cpp, places a check mark on the Center choice:

    menuBar.checkItem(MI_CENTER);

The MI_CENTER constant is defined in the ahellow3.rc resource file as the "Center" text string for the menu. Do not confuse this with the MI_CENTER menu item attribute defined in the string table, which is used only by the information area.

#### Destructing the AHelloWindow Object

After your application runs, you need to stop handling command events for the frame window and delete the objects you created using the new operator. The following lines in the ahellow3.cpp file do this:

    AHelloWindow :: ~AHelloWindow()
    {
      commandHandler.stopHandlingEventsFor(this);

#### Aligning a Text String

This section shows you how to associate commands with the menu items to align the text string.

This sample shows command processing for one of the menu items. This code, from ahellow3.cpp, calls the AHelloWindow setAlignment function to center-align the "Hello, World!!!" text string in the client window:

    bool
      ACommandHandler :: command(ICommandEvent & cmdEvent)
    {
      bool eventProcessed(true);         //Assume event will be processed

      switch (cmdEvent.commandId()) {
        case MI_CENTER:
          frame->setAlignment(AHelloWindow::center);
          break;

The following code shows the setAlignment function from the AHelloWindow class:

    AHelloWindow &
      AHelloWindow :: setTextAlignment(Alignment alignment)
    {

      switch(alignment)
      {

      case center:
        hello.setAlignment(IStaticText::centerCenter);
        statusLine.setText(STR_CENTER);
        menuBar.checkItem(MI_CENTER);
        menuBar.uncheckItem(MI_LEFT);
        menuBar.uncheckItem(MI_RIGHT);
        break;

The preceding code does the following:

- Uses the IStaticText setAlignment member function to center the static text control vertically and align it on the left horizontally
- Sets the appropriate text string in the status area (left alignment)
- Uses the uncheckItem member function to remove any existing check marks from the Center and Right menu items
- Uses the checkItem member function to set a check mark on the Left
- Returns true and ends

#### Adding Text for a Status Line

The status area text strings are specified in the resource file, as shown in the following code:

    MI_CENTER,  "Set Center Alignment"          //InfoArea - Center Menu
    MI_LEFT,    "Set Left Alignment"            //InfoArea - Left Menu
    MI_RIGHT,   "Set Right Alignment"           //InfoArea - Right Menu

The following code, from ahellow3.cpp, gets the "Center Alignment" text string from the resource file and puts it in the static text control for the status area:

    setTextAlignment(center);

#### Setting ACommandHandler as the Command Handler

In version 3, the AHelloWindow class contains an ICommandHandler derived class, called ACommandHandler. This is necessary because, for the first time, this application handles events. In this case, the events are the commands that align the "Hello, World!!!" text string.

The following code in ahellow3.cpp creates a command handler from the ACommandHandler class:

    ,commandHandler(this)

    commandHandler.handleEventsFor(this);

The second line of code, shown in the preceding example, contains the handleEventsFor member function inherited from the ICommandHandler class. Use this member function to set the event handler for the application. In this case, the this argument is specified.

This member function is available because the header file ahellow3.hpp includes the icmdhdr.hpp library header file, which contains the ICommandHandler class as follows:

    #ifndef _AHELLOW3_

    #define _AHELLOW3_

    #include <icmdhdr.hpp> //Include ICommandEvent &
    ICommandHandler

#### Adding Command Processing

The next statements construct the command handler from a pointer to the AHelloWindow that events will be handled for. The ahellow3.cpp file uses the ACommandHandler to create a command handler, as follows:

    ACommandHandler :: ACommandHandler(AHelloWindow *helloFrame)
       :frame(helloFrame)                     //Save frame to be handled;
    {
    } /* end ACommandHandler :: ACommandHandler(...) */

Depending on the command event ID, you need to call the AHelloWindow::setAlignment function with the appropriate AHelloWorld::Alignment enumerator, as shown in the following sample from ahellow3.cpp. The AHelloWorld::Alignment enumerator is defined in the ahellow3.hpp file.

    bool
      ACommandHandler :: command(ICommandEvent & cmdEvent)
    {
      bool eventProcessed(true);         //Assume event will be processed

      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:                            //Otherwise,
          eventProcessed=false;             //  the event wasn't processed
      } /* end switch */

      return(eventProcessed);
    } /* end ACommandHandler :: command(...) */

Events and Event Handlers
Resources

Converting Application Resources
Adding Menus to your Application
Adding a Menu Bar

IEvent
ICommandHandler
IHandler
IMenu
IMenuBar