Converting Application Resources

Open Class Library provides tools to help you convert Windows, OS/2, and Motif resource files.

AIX does not support Windows and OS/2 Presentation Manager (PM) dialog templates. If you write portable applications, use canvases instead of dialog templates. The Hello World version 4 sample application shows you how to do this.

You define resources in a resource file. A resource file is a file that contains data that your application uses, such as text strings and icons. For example, you can define menus, menu items, strings, icons, bitmaps, accelerators, and help tables in the resource file. You also define the string ID, corresponding to each static string you use in a window in the resource file.

The resource compiler produces a binary version of the resources, which is then bound into the application's executable code or stored in a dynamic link library (DLL) for Intel or shared library for AIX.

A benefit of defining resources in a resource file is that you can make changes to resource definitions without affecting the application code itself.

You can also provide national language versions by storing the resources for each language in a separate resource file. You can then build your application as separate executable versions for each language (each with a different resource file bound to it) or as a single executable with a separate DLL or shared library for each language.

Defining Window Resources

Window resources are read-only data segments stored in an application's .exe file or in the dynamic link library's .dll file.

Predefined Open Class Library window resources include keyboard accelerator tables, icons, menus, and bitmaps.

Most window resources are stored in a format that is unique to each resource type. The system translates the formats, as necessary, for use in functions.

To access window resources, you must prepare a resource file (ASCII file with the extension .rcx). Then the ASCII resource file and any bitmap and icon files must be compiled into a single binary file using the resource compiler. The binary resource file is bound to your application's .exe file or to a dynamic link library's .dll file.

Understanding Dialog Templates

A dialog template is a data structure that describes a dialog window and its control windows. Windows and PM uses the data in the dialog template to create the dialog window and control windows. An application can create a dialog template at run time, or it can use the system resource compiler to create a dialog-template resource.

Motif does not support dialog templates. If you write portable applications, use canvases instead of dialog templates. The Hello World 4 sample application shows you how to do this.

Accessing Bitmap and Icon Resources

To convert bitmap and icon resources between the Windows and OS/2 operating systems, use the IBMPCNV tool provided with the VisualAge for C++ product.

The Motif resource compiler understands both OS/2 and Windows bitmap and icon formats.

The Open Class Library accesses bitmap and icon resources using an IResourceID (an unsigned long).

Adding Keyboard Accelerators

A keyboard accelerator is a keystroke or a series of combined keys that generate a command message for an application. Using a keyboard accelerator lets a user quickly access commands. It has the same effect as choosing a menu item.

Your application can load accelerators either statically or at runtime. The resource file is compiled and bound to the application. Then, the application frame window loads the accelerator table with the same resource ID, if found. The Open Class Library also provides IAccelerator, IAcceleratorKey, and IAcceleratorTable classes to add accelerators at runtime.

The following example shows how to define accelerators in a resource file:

ACCELTABLE ID_MAIN
{
    "I",  ID_ABOUT_ITEM, CONTROL, SHIFT, ALT
    "I",  ID_ADD_ITEM,   CONTROL, SHIFT
    "a",  ID_ASC-ITEM,   CONTROL
    "d",  ID_DESC_ITEM,  CONTROL
}

When a user presses a key sequence of Ctrl+Shift+Alt+I, this causes an ID_ABOUT_ITEM event. A Ctrl+Shift+I key sequence causes an ID_ADD_ITEM command event. Notice that the more restrictive accelerator is coded first in the previous example.

Without accelerators, a user might generate commands by pressing the Alt or F10 keys for OS/2 and Windows, or the F10 key for Motif. These keys access the menu bar where you can use the Arrow keys to select the item, and then press the Enter key to choose the item. In contrast, accelerators let users generate commands with fewer keystrokes.

Although accelerators are usually used to generate existing commands as menu items, they also can send commands that have no menu-item equivalent.

Understanding Accelerator Tables

An accelerator table contains an array of accelerators.

Accelerator tables exist at two levels within the operating system: a single accelerator table for the system queue and individual accelerator tables for application windows.

Accelerators in the system queue apply to all applications. For example, the F1 key always generates a help message.

Having accelerators for individual application windows ensures that an application can define its own accelerators without interfering with other applications. An accelerator for an application window can override the accelerator in the system queue.

An application can modify both its own accelerator table and the system's accelerator table.

Converting Resource Files

The CONVRC tool on OS/2 and Windows converts resource (.rc) files between the two operating system formats. The IRCCNV tool on Motif converts a Windows resource file to the OS/2 format. Open Class Library uses the OS/2 format on the Motif operating system.

To use the CONVRC on the Windows and OS/2 operating systems, use the following syntax:

CONVRC -option input output

To convert from Windows to OS/2, you need to specify the following option:

CONVRC -w input output

The current platform's resource files have the extension .rc and cross platform resource files have the extension .rcx.

The following example shows the CONVRC command to use to convert an OS/2 PM resource file, myapp.rc, to a Windows resource file:

CONVRC -o myapp.rcx myapp.rc

Note: The IBM VisualAge for C++ resource compiler uses extended menu support. To convert resource files to use native Windows menu support, use the option -n.

To use IRCCNV on Motif, use the following syntax:

irccnv -option input output

Since Motif's resource compiler understands the OS/2 format, no conversion is needed for OS/2 resource files.

To convert Windows to OS/2 format on Motif, use the following:

irccnv -o input output

Working with the Conversion Tool

The CONVRC and IRCCNV tools handle the following types of resources:

accelerator table (ACCELTABLE)

bitmap (BITMAP)

extended menus (MENUEX)

help tables (HELPTABLE)

help subtable (HELPSUBTABLE)

icon (ICON)

menu (MENU)

menu item (MENUITEM)

pointers(POINTER) This is OS/2 only

string table (STRINGTABLE)

submenu (SUBMENU)

Also keep in mind the following:

CONVRC and IRCCNV error checking do not flag the same errors as the resource compiler. For example, incomplete lines and missing commas produce erroneous output from IRCCNV but no error message. When you use these tools, check input files for errors using the resource compiler.
IRCCNV processes only a single input file. For this reason, do not use wildcard (*) characters in the input file name.
IRCCNV does not convert included files. Convert each included file individually.
IRCCNV does not convert dialog templates as they are not a portable solution. Use the ICanvas class instead.
IRCCNV does not change included headers.
The accelerator table, menu, menu item, string table, and submenu definitions cannot span multiple lines:
```
STRINGTABLE
BEGIN
  STR_HELLO,
    "Hello World"
END
```

Supporting Double-Byte Character Set and Multiple Languages

You can use one source file for your application code and then provide the double-byte character set (DBCS) and support multiple languages by using separate resource files for each of the languages you support. The Open Class Library approach includes either of the following:

Use a single executable file with a separate .DLL for each language.
Use separate executable files for each language (each with a separate resource file bound to it).

The following suggestions can assist you in creating DBCS-enabled applications:

Use the canvas classes to build dialogs because to another language without changing the source code.
Use the IString class, which is DBCS-enabled and supports mixed strings that contain both the single-byte character set (SBCS) and DBCS characters. Objects of the IString class are essentially arrays of characters. The IString class provides functions to test the characters that make up the string. These functions help users determine whether a character is single byte or multiple byte, and whether it is a valid DBCS first byte.

Use the IDBCSBuffer class, which ensures that the search functions do not inadvertently match the second byte of a DBCS character. The IDBCSBuffer class is derived from the IBuffer class, which holds the IString contents. The two bytes of a DBCS character will not be split.

Use the following member functions in a DBCS-enabled application:

	Member Function	Returns True If...
	isCharValid	The character at the given index is in the set of valid characters
	isDBCS1	The byte at the given offset is the first byte of DBCS
	isPrevDBCS	The character preceding the one at the given offset is a DBCS character

Specify one of the following data type styles when you create and manage the IEntryField and IComboBox classes:

	Data Type Styles	Allows the Following Input...
	anyData	A mixture of SBCS and DBCS characters.
	dbcsData	DBCS-only data.
	mixedData	A mixture of SBCS and DBCS characters. Use this style if you plan to convert data to an EBCDIC code page.
	sbcsData	SBCS-only data.

Specify the appDBCSStatus style when constructing an IFrameWindow to include a DBCS status area when the frame appears in a DBCS environment. The Open Class Library automatically shares DBCS status control between a parent and child frame window.

Resources

Hello World Version 4: Adding Dialogs and Push Buttons Creating Cross-Platform Applications

IAccelerator
IAccelTblHandle
IDBCSBuffer
IResourceID
IResourceLibrary
IString