PMGuide - Resource Files

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Presentation Manager Programming Guide and Reference

How to Use this Book Device Functions Direct Manipulation Functions Dynamic Data Formatting Functions Hooks and Procedures Profile Functions Spooler Functions Window Functions Message Processing Data Types Errors Atom Tables Button Controls Clipboards Combination Box Container Controls Control Windows Cursors Dialog Windows Direct Manipulation Drawing in Windows Dynamic Data Exchange Entry-Field Controls File Dialog Controls Font Dialog Controls Frame Windows Hooks Initialization Files Keyboard Accelerators List-Box Controls Menus Messages and Message Queues Multiple-Line Entry Field Controls Mouse and Keyboard Input Mouse Pointers and Icons Notebook Controls Painting and Drawing Presentation Parameters Resource Files Scroll-Bar Controls Slider Controls Spin Button Controls Static Controls Title-Bar Controls Value Set Controls Windows Window Classes Window Procedures Window Timers Appendices Notices Glossary

Resource files enable you to specify the resource information used in creating an application's window. Some examples of resources that can be defined in resource files are:

• Menus
• Accelerator tables
• Dialog and window templates
• Icons
• Fonts
• Bit maps
• Strings

To add resource information to an application, use a text editor to create a resource script file, and then compile it using the Resource Compiler, RC.EXE. The advantage of using resource files is that resource information can be maintained and updated separately in the resource script file and then linked to your application program's .EXE file. This greatly simplifies customizing an application because you can modify resource information without having to recompile the entire application.

This chapter describes the use of resource files in Presentation Manager (PM) programming.

About Resource Files

A resource script file is a text file that contains one or more resource statements that define the type, identifier, and data for each resource. Because some resources might contain binary data that cannot be created using a text editor, there are resource statements that let you specify additional files to include when compiling the resource script file. For example, you can use the Dialog Box Editor to design dialog boxes, the Font Editor to edit font files, and the Icon Editor to create customized icons, pointers, and bit maps. The definitions for these resources can be included with other resource definitions in the resource file.

Resource Statements

This section provides overview information on resource statements and directives. Resource statements consist of one or more keywords, numbers, character strings, constants, or file names. You combine these to define the resource type, identifier, and data. Directives are special types of resource statements that perform functions such as including header files, defining constants, and conditionally compiling portions of the file. Resource statements have three basic forms:

• Single-line statements
• Multiple-line statements
• Directives

Single-line Statements

Single-line statements consist of a keyword identifying the resource type, a constant or number specifying the resource identifier, and a file name specifying the file containing the resource data. For example, this ICON statement defines an icon resource:

ICON 1 myicon.ico

The icon resource has the icon identifier 1, and the file MYICON.ICO contains the icon data.

Multiple-line Statements

Multiple-line statements consist of a keyword identifying the resource type, a constant or number specifying the resource identifier, and, between the BEGIN and END keywords, additional resource statements that define the resource data. For example, this MENU statement defines a menu resource:

 MENU 1
 BEGIN
     MENUITEM "Alpha", 101
     MENUITEM "Beta",  102
 END

The menu identifier is 1. The menu contains two MENUITEM statements that define the contents of the menu.

In multiple-line statements such as DLGTEMPLATE and WINDOWTEMPLATE, any level of nested statements is allowed. For example, the DLGTEMPLATE and WINDOWTEMPLATE statements typically contain a single DIALOG or FRAME statement. These statements can contain any number of WINDOW and CONTROL statements; the WINDOW and CONTROL statements can contain additional WINDOW and CONTROL statements, and so forth. The nested statements let you define controls and other child windows for the dialog boxes and windows.

If a nested statement creates a child window or control, the parent and owner of the new window is the window created by the containing statement. (FRAME statements occasionally create frame controls whose parent and owner windows are not the same.)

Directives

Directives consist of the reserved character # in the first column of a line, followed by the directive keyword and any additional numbers, character strings, or file names.

Some examples of directives are:

• define
• if
• ifdef
• include

Descriptions of the individual directives follow the resource file statement descriptions.

Resource File Statement Descriptions

This section provides the syntax, description, and an example of each of the resource file statements.

The following table summarizes, at a general level, the most commonly used parameters on the statements.

┌────────────┬────────────────────────────────────────────────┐
│Parameter   │Description                                     │
├────────────┼────────────────────────────────────────────────┤
│id          │Control identifier.                             │
├────────────┼────────────────────────────────────────────────┤
│x           │X coordinate of the lower-left corner of the    │
│            │control.                                        │
├────────────┼────────────────────────────────────────────────┤
│y           │Y coordinate of the lower-left corner of the    │
│            │control.                                        │
├────────────┼────────────────────────────────────────────────┤
│height      │Height of the control ( in 1/8 character units).│
├────────────┼────────────────────────────────────────────────┤
│width       │Width of the control.                           │
├────────────┼────────────────────────────────────────────────┤
│style       │Predefined bit representation of a style or     │
│            │combination of styles.                          │
├────────────┼────────────────────────────────────────────────┤
│load option │Definition of when the system should load the   │
│            │resource into memory (for example, PRELOAD or   │
│            │LOADONCALL).                                    │
├────────────┼────────────────────────────────────────────────┤
│mem option  │Definition of how the system manages the        │
│            │resource when in memory (for example, FIXED,    │
│            │MOVABLE, or DISCARDABLE).                       │
├────────────┼────────────────────────────────────────────────┤
│text        │Text associated with a control.                 │
├────────────┼────────────────────────────────────────────────┤
│class       │Predefined class for a particular control.      │
└────────────┴────────────────────────────────────────────────┘

           ACCELTABLE Statement
           ASSOCTABLE Statement
           AUTOCHECKBOX Statement
           AUTORADIOBUTTON Statement
           BITMAP Statement
           CHECKBOX Statement
           CODEPAGE Statement
           COMBOBOX Statement
           CONTAINER Statement
           CONTROL Statement
           CTEXT Statement
           CTLDATA Statement
           DEFAULTICON Statement
           DEFPUSHBUTTON Statement
           DIALOG Statement
           DLGINCLUDE Statement
           DLGTEMPLATE Statement
           EDITTEXT Statement
           ENTRYFIELD Statement
           FONT Statement
           FRAME Statement
           GROUPBOX Statement
           HELPITEM Statement
           HELPSUBITEM Statement
           HELPSUBTABLE Statement
           HELPTABLE Statement
           ICON Statement (Resource)
           ICON Statement (Control)
           LISTBOX Statement
           LTEXT Statement
           MENU Statement
           MENUITEM Statement
           MESSAGETABLE Statement
           MLE Statement
           NOTEBOOK Statement
           POINTER Statement
           PRESPARAMS Statement
           PUSHBUTTON Statement
           RADIOBUTTON Statement
           RCDATA Statement
           RCINCLUDE Statement
           RESOURCE Statement
           RTEXT Statement
           SLIDER Statement
           SPINBUTTON Statement
           STRINGTABLE Statement
           SUBITEMSIZE Statement
           SUBMENU Statement
           VALUESET Statement
           WINDOW Statement
           WINDOWTEMPLATE Statement

Directive Descriptions

This section provides the syntax, a description, and an example of each of the directives.

       #define Directive
       #elif Directive
       #else Directive
       #endif directive
       #if Directive
       #ifdef Directive
       #ifndef Directive
       #include Directive
       #undef Directive

Using Resource Files

This section explains how to create a resource script file, compile it using the Resource Compiler (RC.EXE), and optionally add the resources to your executable file. Resource script files have a default file-name extension of .RC.

For resource information on the individual controls, see the chapter on the specific control. For example, an example of a resource script file for frame windows is in Frame Windows.

Creating and Compiling a Resource File

The resource compiler (RC) compiles a resource script file to create a new file, called a binary resource file, which has a .RES file-name extension. The binary resource file can be added to the executable file of the application, thereby replacing any existing resources in that file.

The RC command line has the following three basic forms:

 rc resource-script-file [executable-file]

 rc binary-resource-file [executable-file]

 rc -r  resource-script-file [binary-resource-file]

Note: The third option does not add to the executable file.

The resource-script-file parameter is the file name of the resource script file to be compiled.

The executable-file parameter must be the name of the executable file to receive the compiled resources. This is a file having a file-name extension of either .EXE or .DLL. If you omit the executable-file field, RC adds the compiled resources to the executable file that has the same name as the resource script file but which has the .EXE file-name extension.

The binary-resource-file parameter is the name of the binary resource file to be added to the executable file.

The -r option directs RC to compile the resource script file without adding it to an executable file.

Compiling and Adding Resources to the .EXE File

To compile the resource script file EXAMPLE.RC and add the result to the executable file EXAMPLE.EXE, use the following command:

 rc example

You do not need to specify the .RC extension. RC creates the binary resource file EXAMPLE.RES and adds the compiled resource to the executable file EXAMPLE.EXE.

Compiling without Adding Resources to the .EXE File

To compile the resource script file EXAMPLE.RC into a binary resource file without adding the resources to an executable file, use the following command:

 rc -r example

The compiler creates the binary resource file EXAMPLE.RES. To create a binary resource file that has a name different from the resource script file, use the following command:

 rc -r example newfile.res

Adding the Compiled Resources to the .EXE File

To add the compiled resources in the binary resource file EXAMPLE.RES to an executable file, use the following command:

 rc example.res

To specify the name of the executable file, if the name is different from the resource file, use the following command:

 rc example.res newfile.exe

Adding the Compiled Resources to a DLL

To add the compiled resources to a dynamic-link-library (DLL) file, use the following command:

 rc example.res dynalink.dll