### Hello World Version 2: Adding Resource Files and Frame Extensions

Version 2 of the Hello World application shows you how to use a resource file and how to add frame extensions to the application window.

A resource file is a file that contains data used by an application, such as text strings and icons. This data is often easier to maintain in a resource file than in the source code of an application because the resource file keeps all of the application's data together in one place.

Frame extensions are controls that you can add to a frame window in addition to those that are provided for you by basic frame windows. For example, in version 2, an information area is added below the client area.

Version 2 of the Hello World application extends version 1 by showing you how to:

- Get the "Hello, World!!!" text string and text for an information area
- Construct the main window and set the title and system menu icon
- Create and set the information area below the client window

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

#### Listing the Hello World Version 2 Files

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

File | Type of Code
--- | ---
ahellow2.cpp | Source code for the main procedure and window constructor
ahellow2.hpp | Header file for the AHelloWindow class
ahellow2.h | Symbolic definitions file for the hello2 executable file
ahellow2.rc | Resource file for the hello2 executable file
ahellow2.ico | Icon file for the hello2 executable file

#### The Primary Source Code File

The ahellow2.cpp file contains the source code for the main procedure and the window constructor. The tasks performed by this code are described in the following sections.

#### The AHelloWindow Class Header File

The ahellow2.hpp contains the class definition and interface specifications for the AHelloWindow class, an IFrameWindow derived class, which was created specifically for this application. It is similar to an Open Class Library header file.

#### The Symbolic Definitions File

The ahellow2.h file contains the symbolic definitions for this application. These definitions provide the IDs for the application main window, controls, and text strings. They are required in this version of the Hello World application, because the text strings are pulled in from a resource file.

#### The Resource File

The ahellow2.rc file is the resource file for version 2 of the Hello World application. This resource file assigns an icon and three text strings to the constants defined in the ahellow2.h file. The ahellow2.h file is included in this resource file so the icon and text strings can be associated with the appropriate IDs.

Open Class Library for AIX supports the OS/2 Presentation Manager (PM) format for .rc files. This format provides a tag language for describing the following:

- String values
- Menu layout
- Accelerator key definitions
- Bit-map and icon associations to files

Note: | Dialog templates are not supported in Motif.

The Open Class Library provides tools for converting Windows, Motif, and OS/2-style resources.

See Converting Application Resources for more information about the resource file conversion tools.

#### The Icon File

The ahellow2.ico file is used as both the title bar icon and the icon that displays when the application is minimized.

The Open Class Library provides tools for converting Windows, Motif, and OS/2 bitmaps and icons.

Here is how the icon appears when minimized:

#### Discussing the Advantages of the C++ File Structure

In version 1, all of the source code was intentionally put in the ahellow1.cpp file to make that version of the application simple. However, for version 2, the source code has been distributed among a variety of files to show that you can structure your applications this way.

First, the AHelloWindow class, the IFrameWindow derived class, is defined in the header file (ahellow2.hpp). Putting the class definition and interface specifications in the header file separates them from their implementation in the source code (ahellow2.cpp). This allows the class and its specifications to be used again with other applications and to be implemented in different ways. If the class definition or interface specifications change, for translation, for example, they change in only one place, the header file.

Similarly, the constant definitions file (ahellow2.h) assigns IDs to the windows and text strings in one place. Defining the constants this way allows you to use constants in a variety of places, such as the source code and the resource file, while keeping their definitions in one place. Then, if you need to change the constant definitions, you only modify the ahellow2.h file.

The advantage of placing the application's data in a resource file (ahellow2.rc) is that all of the resources are specified in one place. For example, finding and modifying text strings is easier when they are all grouped in one place, rather than searching through the source code for each one.

#### Exploring Hello World Version 2

The following sections describe each of the tasks performed by version 2 of the Hello World application. Some of the tasks are the same as those performed by version 1, but they are described again because they are performed differently in version 2.

#### Creating the Main Window

One of the major differences between version 1 and version 2 is the manner in which you create the main window. Version 1 simply creates an IFrameWindow object. However, version 2 provides its own class, AHelloWindow, to create the main window.

The AHelloWindow class is defined in the ahellow2.hpp header file and is derived from the IFrameWindow class. The IFrameWindow class is defined in the iframe.hpp library header file. Therefore, the ahellow2.hpp header file contains the following lines to make the derivation of the AHelloWindow class from the IFrameWindow class possible:

    #ifndef _AHELLOW2_
    #define _AHELLOW2_

    #include <iframe.hpp>                //Include the IFrameWindow class header
    #include <istattxt.hpp>
    #include <iinfoa.hpp>

Hello World version 2 uses the compiler directive, ifndef, to prevent the ahellow2.hpp file from being included again, if it has already been included. This works, because by convention, the _AHELLOW2_ symbolic is defined in the ahellow2.hpp file as well. Both the Open Class Library and Hello World sample application use this convention in the header files.

The ahellow2.cpp file, which contains most of the source code for the application, includes the ahellow2.hpp header file to have access to the AHelloWindow class as follows:

    #include "ahellow2.hpp"                 //Include AHelloWindow class headers

The following lines in the ahellow2.cpp file create the main window by using the AHelloWindow class constructor:

    AHelloWindow mainWindow (WND_MAIN);

The main window is given a value of 1000 as its window ID when the main window was created. However, instead of specifying that value in the primary source code file, we use a constant, WND_MAIN, which is defined in the ahellow2.h file, as follows:

    #define WND_MAIN         1000         //Main Window ID

To have access to this definition, the primary source code file, ahellow2.cpp, must include the ahellow2.h file, as follows:

    #include "ahellow2.h"                   //Include symbolic definitions

#### Starting Event Processing

When the main window is constructed, the following line in the ahellow2.cpp file gets the current application and runs it:

    IApplication::current().run();

See Starting Event Processing for a more detailed explanation.

#### Constructing the AHelloWindow Object

Version 2 constructs the main window using the AHelloWindow class. Here is the class constructor as it is defined in the ahellow2.hpp header file:

    class AHelloWindow : public IFrameWindow
    {

    /*---------------------------  Constructor  ------------------------------|
    | Construct the object with:                                              |
    | 1)  with the WindowID                                                   |
    -------------------------------------------------------------------------*/
      public:
        AHelloWindow (const unsigned long windowId);

In the primary source code file, ahellow2.cpp, version 2 uses the following lines to construct the main window:

    AHelloWindow :: AHelloWindow(const unsigned long windowId)
      : IFrameWindow(IFrameWindow::defaultStyle() |
                     IFrameWindow::minimizedIcon,
                     windowId)
       ,hello(WND_HELLO, this, this)
       ,infoArea(this)
    {

Two capabilities provided by the IFrameWindow class used here were not used in version 1:

- Setting the main window to the default style.

  Use the defaultStyle member function from the IFrameWindow class. It returns the current default style that all applications use for frame windows. The current default style is either the original default style that is provided by the Open Class Library for frame windows or a new default style that you establish by using the setDefaultStyle member function.

  In this case, because the setDefaultStyle member function has not been used, the current default style is the same as the original default style, which provides a title bar, title bar icon, minimize button, maximize button, window border, window list, and an initial shell position for the window.

  In this application, the title bar text and the application icon are specified in the resource file, ahellow2. The text string for the window title is included in the resource file, and the icon, ahellow2.ico, is specified.

- Displaying an icon when the main window is minimized.

  The minimizedIcon style also inherits from the IFrameWindow class. This member function allows an application to use an icon to represent the application when it is minimized on the desktop. The Hello World application provides the ahellow2.ico icon file for this purpose.

#### Creating a Static Text Control

You can create a static text control to display a text string by setting hello equal to a new instance of the IStaticText class, associating an ID with the control window (0x1010), and making the main window the parent and owner of the control.

In our Hello World samples, however, this code is divided into separate parts and placed in different files. As shown in the following lines, hello declared in the AHelloWindow class as an IStaticText object in the ahellow2.hpp file:

    private:
      IStaticText
        hello;

In the ahellow2.cpp file, hello points to a new instance of a static text control as follows:

    ,hello(WND_HELLO, this, this)

The WND_HELLO constant provides the ID for the static text control. All windows must have a unique ID, including controls. Therefore, the ahellow2.cpp file must include ahellow2.h, because that is where this constant is defined:

    #include "ahellow2.h"                   //Include symbolic definitions

With the ahellow2.h included, the ID is associated with the WND_HELLO constant. The following code is from the ahellow2.h file:

    #define WND_HELLO        1010         //Hello World Window ID

The other two arguments (this, this) pass in the main window (this instance of the AHelloWindow class) as the parent and owner of the static text control.

See Creating a Static Text Control for information about parent and owner windows.

#### Setting Static Text Control as the Client Window

Next, set the static text control as the client window. The following code is from the ahellow2.cpp file:

    setClient(&hello);

See Creating a Static Text Control for an explanation of static text controls and client windows.

#### Setting a Text String for the Static Text Control

After the static text control is created, the next task is to set text in it. Version 2 gets the text string from a resource file. To do this, it uses the setText member function, which it inherits from the ITextControl class. The following code is in the ahellow2.cpp file:

    hello.setText(STR_HELLO);

The setText member function finds this constant string in the ahellow2.rc file and puts it into the static text control:

    STR_HELLO,  "Hello, World!!!"               //Hello World String

As noted earlier, each window, even a control, must have a numeric value assigned as its ID. The resource file includes the constant definition file, so this constant definition is available. The following code is from the ahellow2.h file.

    #define STR_HELLO        1200         //Hello World String ID

#### Creating an Information Area

The following code, from the ahellow2.cpp file, creates a new instance of an information area using the IInfoArea class. This class provides a frame extension below the client window that shows information about the application.

    ,infoArea(this)

#### Setting the Information Area Text

Typically, the information shown in the information area pertains to the frame menu item at which the selection cursor is currently positioned. The information is loaded from a resource file string table. A different text string displays for each menu item, changing dynamically in the information area as the cursor moves from item to item. The information area also has a special string (called "inactive text") that displays whenever no menu item is selected.

Version 2 uses setInactiveText to set the information area's inactive text to the same string placed in the static text control in version 1. As a result, this text appears whenever the menu is inactive. The following code is from the ahellow2.cpp file:

    infoArea.setDefaultText(STR_INFO);

The setInactiveText member function finds the STR_INFO constant in the ahellow2.rc file and puts it into the information area as follows:

    STR_INFO,   "Use Alt-F4 to Close Window"    //Information Area String

The STR_INFO constant is associated with a string ID, hexadecimal value 0x1220, in the ahellow2.h constant definition file. The resource file includes the constant definition file, so this constant definition is available as follows:

    #define STR_INFO         1220         //Info String ID

#### Aligning the Static Text Control

As in version 1, the static text control for the client area is centered both horizontally and vertically in the static text control. The following code is from the ahellow2.cpp file:

    hello.setAlignment(IStaticText::centerCenter);

Resources
Events and Event Handlers
Controls

Hello World Version 1: Creating a Main Window
Adding Events and Event Handlers
Using List and Slider Controls
Creating and Using Text Controls

IFrameWindow
IInfoArea
IResource
IStaticText
IClass3