PMGuide - Resource Files
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
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