Jump to content

PMGuide - Resource Files: Difference between revisions

From EDM2
← Older edit
No edit summary
 
(5 intermediate revisions by 2 users not shown)
Line 8: Line 8:
* Fonts
* Fonts
* Bit maps
* Bit maps
* Strings  
* 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.
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.  
This chapter describes the use of resource files in Presentation Manager (PM) programming.
 
==About Resource Files==
==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.  
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===
===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:
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:
Line 20: Line 22:
*Multiple-line statements
*Multiple-line statements
*Directives
*Directives
====Single-line Statements====
====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:
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.


  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====
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:
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
   MENU 1
   BEGIN
   BEGIN
Line 34: Line 35:
       MENUITEM "Beta",  102
       MENUITEM "Beta",  102
   END
   END
The menu identifier is 1. The menu contains two MENUITEM statements that define the contents of the menu.
The menu identifier is 1. The menu contains two MENUITEM statements that define the contents of the menu.


Line 40: Line 40:


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.)
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====
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.
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.
Line 47: Line 48:
* if
* if
* ifdef
* ifdef
* include  
* include
Descriptions of the individual directives follow the resource file statement descriptions.
Descriptions of the individual directives follow the resource file statement descriptions.
===Resource File Statement Descriptions===
===Resource File Statement Descriptions===
This section provides the syntax, description, and an example of each of the resource file statements.
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.
The following table summarizes, at a general level, the most commonly used parameters on the statements.
<PRE>
{| class="wikitable"
┌────────────┬────────────────────────────────────────────────┐
|+
│Parameter  │Description                                    │
|-
├────────────┼────────────────────────────────────────────────┤
! Parameter !! Description
│id          │Control identifier.                             │
|-
├────────────┼────────────────────────────────────────────────┤
| id || Control identifier.
│x          │X coordinate of the lower-left corner of the   │
|-
│            │control.                                       │
| x || X coordinate of the lower-left corner of the control.
├────────────┼────────────────────────────────────────────────┤
|-
│y          │Y coordinate of the lower-left corner of the   │
| y || Y coordinate of the lower-left corner of the control.
│            │control.                                       │
|-
├────────────┼────────────────────────────────────────────────┤
| height || Height of the control (in 1/8 character units).
│height      │Height of the control ( in 1/8 character units).│
|-
├────────────┼────────────────────────────────────────────────┤
| width || Width of the control.
│width      │Width of the control.                           │
|-
├────────────┼────────────────────────────────────────────────┤
| style || Predefined bit representation of a style or combination of styles.
│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).
├────────────┼────────────────────────────────────────────────┤
|-
│load option │Definition of when the system should load the   │
| mem option || Definition of how the system manages the resource when in memory (for example, FIXED, MOVABLE, or DISCARDABLE).
│            │resource into memory (for example, PRELOAD or   │
|-
│            │LOADONCALL).                                   │
| text || Text associated with a control.
├────────────┼────────────────────────────────────────────────┤
|-
│mem option │Definition of how the system manages the       │
| class || Predefined class for a particular control.
│            │resource when in memory (for example, FIXED,   │
|}
│            │MOVABLE, or DISCARDABLE).                       │
├────────────┼────────────────────────────────────────────────┤
│text        │Text associated with a control.                 │
├────────────┼────────────────────────────────────────────────┤
│class      │Predefined class for a particular control.     │
└────────────┴────────────────────────────────────────────────┘
</PRE>


             ACCELTABLE Statement
             ACCELTABLE Statement
Line 91: Line 86:
             AUTORADIOBUTTON Statement
             AUTORADIOBUTTON Statement
             BITMAP Statement
             BITMAP Statement
             CHECKBOX Statement  
             CHECKBOX Statement
             CODEPAGE Statement
             CODEPAGE Statement
             COMBOBOX Statement
             COMBOBOX Statement
Line 137: Line 132:
             WINDOW Statement
             WINDOW Statement
             WINDOWTEMPLATE Statement
             WINDOWTEMPLATE Statement
== ACCELTABLE Statement ==
The `ACCELTABLE` statement creates a table of accelerators for an application.
=== Syntax ===
<pre>
ACCELTABLE acceltable-id [mem-option][load-option]
BEGIN
    key-value, command[, accelerator-options]
    ...
END
</pre>
=== Description ===
An accelerator is a keystroke that provides a quick way to choose a command from a menu or perform another task. An accelerator table can be loaded from the executable file using the `WinLoadAccelTable` function.
=== Example ===
This example creates an accelerator table with identifier `1`, containing two accelerators: `Ctrl+S` and `Ctrl+G`. These generate `WM_COMMAND` messages with values `101` and `102`, respectively.
<pre>
ACCELTABLE 1
BEGIN
    "S", 101, CONTROL
    "G", 102, CONTROL
END
</pre>
== ASSOCTABLE Statement ==
The `ASSOCTABLE` statement defines a file-association table for an application.
=== Syntax ===
<pre>
ASSOCTABLE assoctable-id [load-option][mem-option]
BEGIN
    association-name, file-match-string[, extended-attribute-flag][, icon-filename]
    ...
END
</pre>
=== Description ===
This table associates data files created by an application with its executable file, launching the application when a data file is selected. It can also associate icons with data files by file type. Multiple `ASSOCTABLE` statements can be provided, but each must have a unique `assoctable-id`. Only the last file-association table is written to the `.ASSOC` extended attribute.
== AUTOCHECKBOX Statement ==
The `AUTOCHECKBOX` statement creates an automatic-check-box control.
=== Syntax ===
<pre>
AUTOCHECKBOX text, id, x, y, width [, style]
</pre>
=== Description ===
This control is a small rectangle (check box) displaying an `X` when selected, with text to its right. The `X` toggles on and off with each selection. Used only in `DIALOG` or `WINDOW` statements, it defines the text, identifier, dimensions, and attributes. The predefined class is `WC_BUTTON`. Default style: `BS_AUTOCHECKBOX` and `WS_TABSTOP`.
=== Example ===
This example creates an automatic-check-box control labeled `Italic`.
<pre>
AUTOCHECKBOX "Italic", 101, 10, 10, 100, 100
</pre>
== AUTORADIOBUTTON Statement ==
The `AUTORADIOBUTTON` statement creates an automatic-radio-button control.
=== Syntax ===
<pre>
AUTORADIOBUTTON text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control is a small circle with text to its right, highlighting when selected and sending a message to its parent window. It deselects other radio buttons in the same group. Used only in `DIALOG` or `WINDOW` statements, it defines the text, identifier, dimensions, and attributes. The predefined class is `WC_BUTTON`. Default style: `BS_AUTORADIOBUTTON`.
=== Example ===
This example creates an automatic-radio-button control labeled `Italic`.
<pre>
AUTORADIOBUTTON "Italic", 101, 10, 10, 24, 50
</pre>
== BITMAP Statement ==
The `BITMAP` statement defines a bitmap resource for an application.
=== Syntax ===
<pre>
BITMAP bitmap-id [load-option] [mem-option] filename
</pre>
=== Description ===
A bitmap resource, typically created with the Icon Editor, is a custom bitmap used in displays or menus. The statement copies the bitmap from the specified file and adds it to the application’s resources. It can be loaded using `GpiLoadBitmap`. Each `BITMAP` statement must have a unique `bitmap-id`.
=== Example ===
This example defines a bitmap with identifier `12`, copied from `custom.bmp`.
<pre>
BITMAP 12 custom.bmp
</pre>
== CHECKBOX Statement ==
The `CHECKBOX` statement creates a check-box control.
=== Syntax ===
<pre>
CHECKBOX text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control is a small rectangle with text to its right, highlighting when selected and sending a message to its parent window. Used only in `DIALOG` or `WINDOW` statements, it defines the text, identifier, dimensions, and attributes. The predefined class is `WC_BUTTON`. Default style: `BS_CHECKBOX` and `WS_TABSTOP`.
=== Example ===
This example creates a check-box control labeled `Italic`.
<pre>
CHECKBOX "Italic", 101, 10, 10, 100, 100
</pre>
== CODEPAGE Statement ==
The `CODEPAGE` statement sets the code page for subsequent resources.
=== Syntax ===
<pre>
CODEPAGE codepage-id
</pre>
=== Description ===
The code page specifies the character set used for resources. If not specified, the system’s code page is used. Multiple `CODEPAGE` statements can apply to resources between them.
=== Example ===
This example sets the code page to Portuguese (860) for string resources.
<pre>
CODEPAGE 860
STRINGTABLE
BEGIN
    1 "Filename not found"
    2 "Cannot open file for reading"
END
</pre>
== COMBOBOX Statement ==
The `COMBOBOX` statement creates a combination-box control.
=== Syntax ===
<pre>
COMBOBOX text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control combines a list box with an entry field, allowing users to select or enter text. Used only in `DIALOG` or `WINDOW` statements, it defines the text, identifier, dimensions, and attributes. The predefined class is `WC_COMBOBOX`. Default style: `CBS_SIMPLE`, `WS_GROUP`, `WS_TABSTOP`, `WS_VISIBLE`.
=== Example ===
This example creates a combination-box control.
<pre>
COMBOBOX "", 101, 10, 10, 24, 50
</pre>
== CONTAINER Statement ==
The `CONTAINER` statement creates a container control within a dialog window.
=== Syntax ===
<pre>
CONTAINER id, x, y, width, height [, style]
</pre>
=== Description ===
This control holds objects and is defined by its identifier, position, dimensions, and attributes. The predefined class is `WC_CONTAINER`. Default style: `WS_TABSTOP`, `WS_VISIBLE`, `CCS_SINGLESEL`. Used only in `DIALOG` or `WINDOW` statements.
=== Example ===
This example creates a container control with multiple selection.
<pre>
#define IDC_CONTAINER    301
#define IDD_CONTAINERDLG 504
DIALOG "Container", IDD_CONTAINERDLG, 23, 6, 120, 280, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
BEGIN
    CONTAINER IDC_CONTAINER, 30, 30, 70, 200, CCS_MULTIPLESEL | WS_GROUP
END
</pre>
== CONTROL Statement ==
The `CONTROL` statement defines a control belonging to a specified class.
=== Syntax ===
<pre>
CONTROL text, id, x, y, width, height, class [, style]
[ data-definitions ]
[ BEGIN
    control-definition
    ...
END ]
</pre>
=== Description ===
This statement defines the position, dimensions, and style of a control within its parent window. Used primarily in `DIALOG` or `WINDOW` statements, each control must have a unique `id`. Optional `BEGIN` and `END` enclose child control statements.
=== Example ===
This example creates a push-button control.
<pre>
CONTROL "OK", 101, 10, 10, 20, 50, WC_BUTTON, BS_PUSHBUTTON | WS_TABSTOP | WS_VISIBLE
</pre>
== CTEXT Statement ==
The `CTEXT` statement creates a centered-text control.
=== Syntax ===
<pre>
CTEXT text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control displays centered text in a rectangle, wrapping words to the next line as needed. Used only in `DIALOG` or `WINDOW` statements, it defines the text, identifier, dimensions, and attributes. The predefined class is `WC_STATIC`. Default style: `SS_TEXT`, `DT_CENTER`, `WS_GROUP`.
=== Example ===
This example creates a centered-text control labeled `Filename`.
<pre>
CTEXT "Filename", 101, 10, 10, 100, 100
</pre>
== CTLDATA Statement ==
The `CTLDATA` statement defines control data for a custom dialog box, window, or control.
=== Syntax ===
<pre>
CTLDATA word-value [, word-value]
CTLDATA string
CTLDATA MENU
BEGIN
    menuitem-definition
    ...
END
</pre>
=== Description ===
This statement supports three forms: menu, word values, or strings, allowing custom data for window procedures. It is typically used for custom window classes to control their operation, such as extended style bits.
=== Example ===
This example creates a menu for a window.
<pre>
WINDOWTEMPLATE 1
BEGIN
    WINDOW "Sample", 1, 0, 0, 100, 100, "MYCLASS", 0, FCF_STANDARD
    CTLDATA MENU
    BEGIN
        MENUITEM "Exit", 101
    END
END
</pre>
== DEFAULTICON Statement ==
The `DEFAULTICON` statement installs an icon file as the default icon under the `ICON` extended attribute.
=== Syntax ===
<pre>
DEFAULTICON filename
</pre>
=== Description ===
An icon with `icon-id` of `1` is the default unless another is specified.
=== Example ===
<pre>
DEFAULTICON filename.ico
</pre>
== DEFPUSHBUTTON Statement ==
The `DEFPUSHBUTTON` statement creates a default push-button control.
=== Syntax ===
<pre>
DEFPUSHBUTTON text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control is a round-cornered rectangle with bold text, acting as the default response. It sends a message to its parent when selected. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_BUTTON`. Default style: `BS_PUSHBUTTON`, `BS_DEFAULT`, `WS_TABSTOP`.
=== Example ===
This example creates a default push-button labeled `Cancel`.
<pre>
DEFPUSHBUTTON "Cancel", 101, 10, 10, 24, 50
</pre>
== DIALOG Statement ==
The `DIALOG` statement defines a dialog box window.
=== Syntax ===
<pre>
DIALOG text, id, x, y, width, height [, [style] [,framectl]] [data-definitions]
BEGIN
    control-definition
    ...
END
</pre>
=== Description ===
This statement defines the position, dimensions, and style of a dialog box, typically used in `DLGTEMPLATE` statements. Coordinates depend on the style (`FS_SCREENALIGN`, `FS_MOUSEALIGN`, or parent window origin). It can contain `CONTROL`, `DIALOG`, or `WINDOW` statements.
=== Example ===
This example creates a dialog box labeled `Disk Error`.
<pre>
DLGTEMPLATE 1
BEGIN
    DIALOG "Disk Error", 100, 10, 10, 300, 110
    BEGIN
        CTEXT "Select One:", 1, 10, 80, 280, 12
        RADIOBUTTON "Retry", 2, 75, 50, 60, 12
        RADIOBUTTON "Abort", 3, 75, 30, 60, 12
        RADIOBUTTON "Ignore", 4, 75, 10, 60, 12
    END
END
</pre>
== DLGINCLUDE Statement ==
The `DLGINCLUDE` statement adds a specified file to the resource file.
=== Syntax ===
<pre>
DLGINCLUDE id filename
</pre>
=== Description ===
This statement allows access to a definitions file for a dialog box with the corresponding identifier. Each `DLGINCLUDE` statement must have a unique `id`.
=== Example ===
This example includes the file `dlgdef.h` for dialog-box identifier `5`.
<pre>
DLGINCLUDE 5 "\\INCLUDE\\DLGDEF.H"
</pre>
== DLGTEMPLATE Statement ==
The `DLGTEMPLATE` statement creates a dialog-box template.
=== Syntax ===
<pre>
DLGTEMPLATE dialog-id [load-option] [mem-option]
BEGIN
    dialog-definition
    ...
END
</pre>
=== Description ===
A dialog-box template defines the identifier, load/memory options, dimensions, and controls. It can be loaded using `WinLoadDlg`. Each template must have a unique `dialog-id`.
=== Example ===
This example creates a dialog box for a timer.
<pre>
DLGTEMPLATE ID_GETTIMER
BEGIN
    DIALOG "Timer", 1, 10, 10, 100, 40
    BEGIN
        LTEXT "Time (0 - 15):", 4, 8, 24, 72, 12
        ENTRYFIELD "0", ID_TIME, 80, 28, 16, 8, ES_MARGIN
        DEFPUSHBUTTON "Enter", ID_TIMEOK, 10, 6, 36, 12
        PUSHBUTTON "Cancel", ID_TIMECANCEL, 52, 6, 40, 12
    END
END
</pre>
== EDITTEXT Statement ==
The `EDITTEXT` statement creates an entry-field control.
=== Syntax ===
<pre>
EDITTEXT text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control is a rectangle for typing and editing text, supporting keyboard and mouse interactions. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_ENTRYFIELD`. Default style: `ES_AUTOSCROLL`, `WS_TABSTOP`. Identical to `ENTRYFIELD`.
=== Example ===
This example creates an unlabeled entry-field control.
<pre>
EDITTEXT "", 101, 10, 10, 24, 50
</pre>
== ENTRYFIELD Statement ==
The `ENTRYFIELD` statement creates an entry-field control.
=== Syntax ===
<pre>
ENTRYFIELD text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control is a rectangle for typing and editing text, identical to `EDITTEXT`. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_ENTRYFIELD`. Default style: `ES_AUTOSCROLL`, `WS_TABSTOP`.
=== Example ===
This example creates an unlabeled entry-field control.
<pre>
ENTRYFIELD "", 101, 10, 10, 24, 50
</pre>
== FONT Statement ==
The `FONT` statement defines a font resource for an application.
=== Syntax ===
<pre>
FONT font-id [load-option] [mem-option] filename
</pre>
=== Description ===
A font resource, created using the OS/2 Font Editor, defines character shapes. The statement copies the font from the specified file and can be loaded using `GpiLoadFonts`. Each `FONT` statement must have a unique `font-id`.
=== Example ===
This example defines a font with identifier `5`, copied from `cmroman.fon`.
<pre>
FONT 5 cmroman.fon
</pre>
== FRAME Statement ==
The `FRAME` statement defines a frame window.
=== Syntax ===
<pre>
FRAME text, id, x, y, width, height, style [, framectl]
data-definitions
[ BEGIN
    window-definition
    ...
END ]
</pre>
=== Description ===
This statement defines the title, identifier, position, dimensions, and style of a frame window, typically used in `WINDOWTEMPLATE` statements. It usually contains a `WINDOW` statement for the client window. Frame controls (e.g., title bar) are defined via `framectl`.
=== Example ===
This example creates a frame window with a client window.
<pre>
WINDOWTEMPLATE 1
BEGIN
    FRAME "My Window", 1, 10, 10, 320, 130, 0, FCF_STANDARD | FCF_VERTSCROLL
    BEGIN
        WINDOW "", FID_CLIENT, 0, 0, 0, 0, "MyClientClass"
    END
END
</pre>
== GROUPBOX Statement ==
The `GROUPBOX` statement creates a group-box control.
=== Syntax ===
<pre>
GROUPBOX text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control groups other controls with a border and text in the upper-left corner. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_STATIC`. Default style: `SS_GROUPBOX`, `WS_TABSTOP`.
=== Example ===
This example creates a group-box control labeled `Options`.
<pre>
GROUPBOX "Options", 101, 10, 10, 100, 100
</pre>
== HELPITEM Statement ==
The `HELPITEM` statement defines help items in a help table.
=== Syntax ===
<pre>
HELPITEM application-window-id, help-subtable-id, extended-helppanel-id
</pre>
=== Description ===
This statement specifies identifiers for an application window, its help subtable, and extended help panel. Used only in `HELPTABLE` statements, one `HELPITEM` is needed per application window with help.
=== Example ===
This example associates a help subtable and panel with an application window.
<pre>
HELPITEM IDWIN_FILEMENU, IDSUB_FILEMENU, IDEXT_APPHLP
</pre>
== HELPSUBITEM Statement ==
The `HELPSUBITEM` statement defines help subitems in a help subtable.
=== Syntax ===
<pre>
HELPSUBITEM child-window-id, helppanel-id [, integer]
</pre>
=== Description ===
This statement specifies a child window’s identifier, its help panel, and optional integers. Used only in `HELPSUBTABLE` statements, one `HELPSUBITEM` is needed per child window with help.
=== Example ===
This example associates a child window with a help panel.
<pre>
HELPSUBITEM IDCLD_FILEMENU, IDHP_FILEMENU
</pre>
== HELPSUBTABLE Statement ==
The `HELPSUBTABLE` statement defines a help-subtable resource.
=== Syntax ===
<pre>
HELPSUBTABLE helpsubtable-id [SUBITEMSIZE size]
BEGIN
    helpsubitem-definition
    ...
END
</pre>
=== Description ===
A help subtable contains a help subitem for each selectable item in an application window. Each `HELPSUBTABLE` must have a unique `helpsubtable-id`. The `SUBITEMSIZE` statement is required if optional integers are included.
=== Example ===
This example creates a help subtable with two subitems.
<pre>
HELPSUBTABLE IDSUB_FILEMENU
BEGIN
    HELPSUBITEM IDCLD_OPEN, IDPNL_OPEN
    HELPSUBITEM IDCLD_SAVE, IDPNL_SAVE
END
</pre>
== HELPTABLE Statement ==
The `HELPTABLE` statement defines a help-table resource.
=== Syntax ===
<pre>
HELPTABLE helptable-id
BEGIN
    helpitem-definition
    ...
END
</pre>
=== Description ===
A help table contains a help item for each application window, dialog box, or message box with help. Each `HELPTABLE` must have a unique `helptable-id`.
=== Example ===
This example creates a help table with two help items.
<pre>
HELPTABLE 1
BEGIN
    HELPITEM IDWIN_FILEMENU, IDSUB_FILEMENU, IDEXT_APPHLP
    HELPITEM IDWIN_EDITMENU, IDSUB_EDITMENU, IDEXT_APPHLP
END
</pre>
== ICON Statement (Resource) ==
The `ICON` statement defines an icon resource for an application.
=== Syntax ===
<pre>
ICON icon-id [load-option] [mem-option] filename
</pre>
=== Description ===
An icon resource, created with the Icon Editor, defines an application’s icon. It is copied from the specified file and can be loaded using `WinCreateStdWindow` with `FS_ICON`. Each `ICON` statement must have a unique `icon-id`. An `icon-id` of `1` is the default and written to the `.ICON` extended attribute.
=== Example ===
This example defines an icon with identifier `11`, copied from `custom.ico`.
<pre>
ICON 11 custom.ico
</pre>
== ICON Statement (Control) ==
The `ICON` statement creates an icon control.
=== Syntax ===
<pre>
ICON icon-id, id, x, y, width, height [, style]
</pre>
=== Description ===
This control displays an icon in a dialog box. The width and height fields are ignored as the icon sizes itself. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_STATIC`. Default style: `SS_ICON`.
=== Example ===
This example creates an icon control with icon identifier `99`.
<pre>
ICON 99, 101, 10, 10, 0, 0
</pre>
== LISTBOX Statement ==
The `LISTBOX` statement creates a list-box control.
=== Syntax ===
<pre>
LISTBOX id, x, y, width, height [, style]
</pre>
=== Description ===
This control displays a list of user-selectable strings. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_LISTBOX`. Default style: `WS_TABSTOP`.
=== Example ===
This example creates a list-box control with identifier `101`.
<pre>
LISTBOX 101, 10, 10, 100, 100
</pre>
== LTEXT Statement ==
The `LTEXT` statement creates a left-aligned text control.
=== Syntax ===
<pre>
LTEXT text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control displays left-aligned text, wrapping words to the next line. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_STATIC`. Default style: `SS_TEXT`, `DT_LEFT`, `WS_GROUP`.
=== Example ===
This example creates a left-aligned text control labeled `Filename`.
<pre>
LTEXT "Filename", 101, 10, 10, 100, 100
</pre>
== MENU Statement ==
The `MENU` statement defines a menu resource.
=== Syntax ===
<pre>
MENU menu-id [load-option] [mem-option]
BEGIN
    menuitem-definition
    ...
END
</pre>
=== Description ===
A menu resource defines an application’s menu appearance and function, loadable via `WinLoadMenu`. Each `MENU` statement must have a unique `menu-id`. Menu items are defined in the order specified.
=== Example ===
This example creates a menu with a menu item and a submenu.
<pre>
MENU 1
BEGIN
    MENUITEM "Alpha", 100
    SUBMENU "Beta", 101
    BEGIN
        MENUITEM "Item 1", 200
        MENUITEM "Item 2", 201, , MIA_CHECKED
    END
END
</pre>
== MENUITEM Statement ==
The `MENUITEM` statement creates a menu item.
=== Syntax ===
<pre>
MENUITEM text, menu-id [, menuitem-style [, menuitem-attribute]]
</pre>
=== Description ===
This statement defines a menu item’s text, identifier, and attributes, used only in `MENU` or `SUBMENU` statements. A `WM_COMMAND` message is sent when selected. The `MENUITEM SEPARATOR` form creates a horizontal divider. Special characters like `\t`, `\a`, and `~` control formatting and mnemonics.
=== Example ===
This example creates various menu items.
<pre>
MENUITEM "Alpha", 101
MENUITEM "Beta", 102, MIS_TEXT, MIA_CHECKED
MENUITEM "Gamma", 103
MENUITEM SEPARATOR
MENUITEM "Delta", 104
BITMAP 1 mybitmap.bmp
MENUITEM "#1", 301, MIS_BITMAP
</pre>
== MESSAGETABLE Statement ==
The `MESSAGETABLE` statement creates string resources.
=== Syntax ===
<pre>
MESSAGETABLE [load-option] [mem-option]
BEGIN
    string-id string-definition
    ...
END
</pre>
=== Description ===
String resources are null-terminated with unique identifiers, loadable via `DosGetResource` with `RT_MESSAGE`. Strings are bundled in groups of 16, with bundle ID calculated as `(id / 16) + 1` and string index as `id % 16`. Most applications prefer `STRINGTABLE`.
=== Example ===
This example creates two string resources.
<pre>
MESSAGETABLE
BEGIN
    1 "Filename not found"
    2 "Cannot open file for reading"
END
</pre>
== MLE Statement ==
The `MLE` statement creates a multiple-line entry-field control.
=== Syntax ===
<pre>
MLE text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control allows typing and editing multiple lines of text. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_MLE`. Default style: `MLS_BORDER`, `WS_GROUP`, `WS_TABSTOP`.
=== Example ===
This example creates an unlabeled multiple-line entry-field control.
<pre>
MLE "", 101, 10, 10, 50, 100
</pre>
== NOTEBOOK Statement ==
The `NOTEBOOK` statement creates a notebook control.
=== Syntax ===
<pre>
NOTEBOOK id, x, y, width, height [, style]
</pre>
=== Description ===
This control organizes information on pages. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_NOTEBOOK`. Default style: `WS_TABSTOP`, `WS_VISIBLE`.
=== Example ===
This example creates a notebook control with rounded tabs.
<pre>
#define IDC_NOTEBOOK 201
#define IDD_NOTEBOOKDLG 503
DIALOG "Notebook", IDD_NOTEBOOKDLG, 11, 11, 420, 420, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
BEGIN
    NOTEBOOK IDC_NOTEBOOK, 20, 20, 200, 400, BKS_ROUNDEDTABS | WS_GROUP
END
</pre>
== POINTER Statement ==
The `POINTER` statement defines a pointer resource.
=== Syntax ===
<pre>
POINTER pointer-id [load-option] [mem-option] filename
</pre>
=== Description ===
A pointer resource, created with the OS/2 Icon Editor, defines the mouse pointer shape. It is copied from the specified file and loadable via `WinLoadPointer`. Each `POINTER` statement must have a unique `pointer-id`.
=== Example ===
This example defines a pointer with identifier `10`, copied from `custom.cur`.
<pre>
POINTER 10 custom.cur
</pre>
== PRESPARAMS Statement ==
The `PRESPARAMS` statement defines presentation fields for customization.
=== Syntax ===
<pre>
PRESPARAMS presparam, value [, value]
</pre>
=== Description ===
This statement provides data to control the appearance of dialog boxes, menus, windows, or controls, processed by their window procedures. It is often used for custom controls, e.g., specifying colors or fonts.
=== Example ===
This example sets a menu’s font to 12-point Helvetica.
<pre>
MENU 1
BEGIN
    PRESPARAMS PP_FONTNAMESIZE, "12.Helv"
    MENUITEM "New", 100
    MENUITEM "Open", 101
    MENUITEM "Save", 102
END
</pre>
== PUSHBUTTON Statement ==
The `PUSHBUTTON` statement creates a push-button control.
=== Syntax ===
<pre>
PUSHBUTTON text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control is a round-cornered rectangle with text, sending a message to its parent when selected. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_BUTTON`. Default style: `BS_PUSHBUTTON`, `WS_TABSTOP`.
=== Example ===
This example creates a push-button control labeled `OK`.
<pre>
PUSHBUTTON "OK", 101, 10, 10, 100, 100
</pre>
== RADIOBUTTON Statement ==
The `RADIOBUTTON` statement creates a radio-button control.
=== Syntax ===
<pre>
RADIOBUTTON text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control is a small circle with text, highlighting when selected and sending a message to its parent. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_BUTTON`. Default style: `BS_RADIOBUTTON`.
=== Example ===
This example creates a radio-button control labeled `Italic`.
<pre>
RADIOBUTTON "Italic", 101, 10, 10, 24, 50
</pre>
== RCDATA Statement ==
The `RCDATA` statement defines a custom-data resource.
=== Syntax ===
<pre>
RCDATA resource-id
BEGIN
    data-definition [, data-definition]
    ...
END
</pre>
=== Description ===
Custom data can be in any format, loadable via `DosGetResource` or `DosGetResource2` with `RT_RCDATA`. Each `RCDATA` statement must have a unique `resource-id`.
=== Example ===
This example defines custom data with identifier `5`.
<pre>
RCDATA 5
BEGIN
    "E. A. Poe", 1849, -32, 3L, 0x8000000l, 3+4+5
END
</pre>
== RCINCLUDE Statement ==
The `RCINCLUDE` statement includes another resource script file.
=== Syntax ===
<pre>
RCINCLUDE filename
</pre>
=== Description ===
The specified file is processed alongside the current script, with results compiled into one binary resource file. For HPFS filenames with spaces, use double quotes.
=== Example ===
This example includes `dialogs.rc`.
<pre>
RCINCLUDE dialogs.rc
</pre>
== RESOURCE Statement ==
The `RESOURCE` statement defines a custom resource.
=== Syntax ===
<pre>
RESOURCE type-id resource-id [load-option] [mem-option] filename
</pre>
=== Description ===
Custom resources can be any data, copied from the specified file and loadable via `DosGetResource` or `DosGetResource2`. Each statement must have a unique `type-id` and `resource-id` combination.
=== Example ===
This example defines a custom resource with type `300` and identifier `14`.
<pre>
RESOURCE 300 14 custom.res
</pre>
== RTEXT Statement ==
The `RTEXT` statement creates a right-aligned text control.
=== Syntax ===
<pre>
RTEXT text, id, x, y, width, height [, style]
</pre>
=== Description ===
This control displays right-aligned text, wrapping words to the next line. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_STATIC`. Default style: `SS_TEXT`, `DT_RIGHT`, `WS_GROUP`.
=== Example ===
This example creates a right-aligned text control labeled `Filename`.
<pre>
RTEXT "Filename", 101, 10, 10, 100, 100
</pre>
== SLIDER Statement ==
The `SLIDER` statement creates a slider control.
=== Syntax ===
<pre>
SLIDER id, x, y, width, height [, style]
</pre>
=== Description ===
This control allows users to set or modify a value by moving a slider arm. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_SLIDER`. Default style: `WS_TABSTOP`, `WS_VISIBLE`.
=== Example ===
This example creates a slider control with buttons on the left.
<pre>
#define IDC_SLIDER 101
#define IDD_SLIDERDLG 502
DIALOG "Slider", IDD_SLIDERDLG, 11, 11, 200, 240, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
BEGIN
    SLIDER IDC_SLIDER, 40, 30, 120, 16, SLS_BUTTONSLEFT | WS_VISIBLE
END
</pre>
== SPINBUTTON Statement ==
The `SPINBUTTON` statement creates a spin-button control.
=== Syntax ===
<pre>
SPINBUTTON id, x, y, width, height [, style]
</pre>
=== Description ===
This control provides access to a finite set of data. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_SPINBUTTON`. Default style: `WS_TABSTOP`, `WS_VISIBLE`, `SPBS_MASTER`.
=== Example ===
This example creates a numeric-only spin-button control.
<pre>
#define IDC_SPINBUTTON 302
#define IDD_SPINDLG 502
DIALOG "Spin button", IDD_SPINDLG, 11, 11, 200, 240, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
BEGIN
    SPINBUTTON IDC_SPINBUTTON, 80, 20, 60, 24, SPBS_NUMERICONLY | WS_TABSTOP
END
</pre>
== STRINGTABLE Statement ==
The `STRINGTABLE` statement creates string resources.
=== Syntax ===
<pre>
STRINGTABLE [load-option] [mem-option]
BEGIN
    string-id string-definition
    ...
END
</pre>
=== Description ===
String resources are null-terminated with unique identifiers, loadable via `WinLoadString` or `DosGetResource` with `RT_STRING`. Strings are bundled in groups of 16, with bundle ID calculated as `(id / 16) + 1` and string index as `id % 16`.
=== Example ===
This example creates two string resources.
<pre>
#define IDS_HELLO 1
#define IDS_GOODBYE 2
STRINGTABLE
BEGIN
    IDS_HELLO "Hello"
    IDS_GOODBYE "Goodbye"
END
</pre>
== SUBITEMSIZE Statement ==
The `SUBITEMSIZE` statement specifies the size of help subitems.
=== Syntax ===
<pre>
SUBITEMSIZE size
</pre>
=== Description ===
This statement sets the size (in words) of each help subitem in a help subtable, with a minimum of two words. It must appear after `HELPSUBTABLE` and before `BEGIN`.
=== Example ===
This example specifies three-word help subitems.
<pre>
HELPSUBTABLE 1
SUBITEMSIZE 3
BEGIN
    HELPSUBITEM IDCLD_FILEMENU, IDHP_FILEMENU, 5
    HELPSUBITEM IDCLD_HELPMENU, IDHP_HELPMENU, 6
END
</pre>
== SUBMENU Statement ==
The `SUBMENU` statement creates a submenu.
=== Syntax ===
<pre>
SUBMENU text, submenu-id [, menuitem-style[, menuitem-attribute]]
BEGIN
    menuitem-definition
    ...
END
</pre>
=== Description ===
A submenu is a vertical list of menu items. Each `SUBMENU` statement must have a unique `submenu-id`. Menu items are defined in the order specified.
=== Example ===
This example creates a submenu with three menu items.
<pre>
SUBMENU "Elements", 2
BEGIN
    MENUITEM "Oxygen", 200
    MENUITEM "Carbon", 201, , MIA_CHECKED
    MENUITEM "Hydrogen", 202
END
</pre>
== VALUESET Statement ==
The `VALUESET` statement creates a value set control.
=== Syntax ===
<pre>
VALUESET id, x, y, width, height [, style]
</pre>
=== Description ===
This control allows selection from mutually exclusive choices. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_VALUESET`. Default style: `WS_TABSTOP`, `WS_VISIBLE`.
=== Example ===
This example creates a value set control with icons.
<pre>
#define IDC_VALUESET 302
#define IDD_VALUESETDLG 501
DIALOG "Value set", IDD_VALUESETDLG, 11, 11, 260, 240, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
BEGIN
    VALUESET IDC_VALUESET, 40, 40, 220, 160, VS_ICON | WS_TABSTOP
END
</pre>
== WINDOW Statement ==
The `WINDOW` statement creates a window of a specified class.
=== Syntax ===
<pre>
WINDOW text, id, x, y, width, height, class [, style [, framect]]
data-definitions
[ BEGIN
    control-definition
    ...
END ]
</pre>
=== Description ===
This statement defines the window’s position, dimensions, and style, typically used in `WINDOWTEMPLATE` or `FRAME` statements. It usually defines a client window in a `FRAME` statement.
=== Example ===
This example creates a client window.
<pre>
WINDOWTEMPLATE 1
BEGIN
    FRAME "My Window", 1, 10, 10, 320, 130, 0, FCF_STANDARD | FCF_VERTSCROLL
    BEGIN
        WINDOW "", FID_CLIENT, 0, 0, 0, 0, "MyClientClass"
    END
END
</pre>
== WINDOWTEMPLATE Statement ==
The `WINDOWTEMPLATE` statement creates a window template.
=== Syntax ===
<pre>
WINDOWTEMPLATE window-id [load-option] [mem-option]
BEGIN
    window-definition
    ...
END
</pre>
=== Description ===
A window template defines the window identifier, load/memory options, dimensions, and controls, loadable via `WinLoadDlg`. Each template must have a unique `window-id`.
=== Description ===
A window template defines the window identifier, load/memory options, dimensions, and controls, loadable via `WinLoadDlg`. Each template must have a unique `window-id`.
==Directive Descriptions==
==Directive Descriptions==
This section provides the syntax, a description, and an example of each of the directives.  
This section provides the syntax, a description, and an example of each of the directives.
 
         #define Directive
         #define Directive
         #elif Directive
         #elif Directive
Line 149: Line 1,243:
         #include Directive
         #include Directive
         #undef Directive
         #undef Directive
== #define Directive ==
The #define directive assigns the given value to the specified name. All subsequent occurrences of the name are replaced by the value.
=== Syntax ===
<pre>
#define name value
</pre>
=== Example ===
This example assigns values to the names `NONZERO` and `USERCLASS`.
<pre>
#define NONZERO 1
#define USERCLASS "MyControlClass"
</pre>
== #elif Directive ==
The #elif directive marks an optional clause of a conditional-compilation block defined by a #ifdef, #ifndef, or #if directive. The directive controls conditional compilation of the resource file by checking the specified constant expression. If the constant expression is nonzero, #elif directs the compiler to continue processing statements up to the next #endif, #else, or #elif directive and then skip to the statement after #endif. If the constant expression is zero, #elif directs the compiler to skip to the next #endif, #else, or #elif directive. You can use any number of #elif directives in a conditional block.
=== Syntax ===
<pre>
#elif constant-expression
</pre>
=== Example ===
In this example, #elif directs the compiler to process the second BITMAP statement only if the value assigned to the name `Version` is less than 7. The #elif directive itself is processed only if Version is greater than or equal to 3.
<pre>
#if Version < 3
BITMAP 1 errbox.bmp
#elif Version < 7
BITMAP 1 userbox.bmp
#endif
</pre>
== #else Directive ==
The #else directive marks an optional clause of a conditional-compilation block defined by a #ifdef, #ifndef, or #if directive. The #else directive must be the last directive before the #endif directive. This directive has no arguments.
=== Syntax ===
<pre>
#else
</pre>
=== Example ===
This example compiles the second BITMAP statement only if the name `DEBUG` is not defined.
<pre>
#ifdef DEBUG
BITMAP 1 errbox.bmp
#else
BITMAP 1 userbox.bmp
#endif
</pre>
== #endif Directive ==
The #endif directive marks the end of a conditional-compilation block defined by a #ifdef directive. One #endif is required for each #if, #ifdef, or #ifndef directive. This directive has no arguments.
=== Syntax ===
<pre>
#endif
</pre>
== #if Directive ==
The #if directive controls conditional compilation of the resource file by checking the specified constant expression. If the constant expression is nonzero, #if directs the compiler to continue processing statements up to the next #endif, #else, or #elif directive and then skip to the statement after the #endif directive. If the constant expression is zero, it directs the compiler to skip to the next #endif, #else, or #elif directive.
=== Syntax ===
<pre>
#if constant-expression
</pre>
=== Example ===
This example compiles the BITMAP statement only if the value assigned to the name `Version` is less than 3.
<pre>
#if Version < 3
BITMAP 1 errbox.bmp
#endif
</pre>
== #ifdef Directive ==
The #ifdef directive controls conditional compilation of the resource file by checking the specified name. If the name has been defined by using a define directive or by using the -d command-line option of rc, #ifdef directs the compiler to continue with the statement immediately after the #ifdef directive. If the name has not been defined, #ifdef directs the compiler to skip all statements up to the next #endif directive.
=== Syntax ===
<pre>
#ifdef name
</pre>
=== Example ===
This example compiles the BITMAP statement only if the name `Debug` is defined.
<pre>
#ifdef Debug
BITMAP 1 errbox.bmp
#endif
</pre>
== #ifndef Directive ==
The #ifndef directive controls conditional compilation of the resource file by checking the specified name. If the name has not been defined or if its definition has been removed by using the #undef directive, #ifndef directs the compiler to continue processing statements up to the next #endif, #else, or #elif directive and then skip to the statement after the #endif directive. If the name is defined, #ifndef directs the compiler to skip to the next #endif, #else, or #elif directive.
=== Syntax ===
<pre>
#ifndef name
</pre>
=== Example ===
This example compiles the BITMAP statement only if the name `Optimize` is not defined.
<pre>
#ifndef Optimize
BITMAP 1 errbox.bmp
#endif
</pre>
== #include Directive ==
The #include directive causes RC to process the file specified in the filename field. This file should be a header file that defines the constants used in the resource script file. Only the define directives in the specified file are processed. All other statements are ignored. The filename field is handled as a C string. Therefore, you must include two backslashes (\\) wherever one is required in the path. (As an alternative, you can use a single forward slash (/) instead of two backslashes.)
=== Syntax ===
<pre>
#include filename
</pre>
=== Example ===
This example processes the header files OS2.H and HEADERS\MYDEFS.H while compiling the resource script file.
<pre>
#include <os2.h>
#include "headers\\mydefs.h"
</pre>
== #undef Directive ==
The #undef directive removes the current definition of the specified name. All subsequent occurrences of the name are processed without replacement.
=== Syntax ===
<pre>
#undef name
</pre>
=== Example ===
This example removes the definitions for the names `nonzero` and `USERCLASS`.
<pre>
#undef nonzero
#undef USERCLASS
</pre>
==Using Resource Files==
==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.
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.  
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===
===Creating and Compiling a Resource File===
Line 158: Line 1,398:


The RC command line has the following three basic forms:
The RC command line has the following three basic forms:
   rc resource-script-file [executable-file]
   rc resource-script-file [executable-file]
   
   
Line 173: Line 1,412:
The binary-resource-file parameter is the name of the binary resource file to be added to the executable file.
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.  
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====
====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:
To compile the resource script file EXAMPLE.RC and add the result to the executable file EXAMPLE.EXE, use the following command:
  rc example


  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.


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====
====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:
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
   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:
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
   rc -r example newfile.res


====Adding the Compiled Resources to the .EXE File====
====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:
To add the compiled resources in the binary resource file EXAMPLE.RES to an executable file, use the following command:
   rc example.res
   rc example.res


To specify the name of the executable file, if the name is different from the resource file, use the following command:
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
   rc example.res newfile.exe


====Adding the Compiled Resources to a DLL====
====Adding the Compiled Resources to a DLL====
To add the compiled resources to a dynamic-link-library (DLL) file, use the following command:
To add the compiled resources to a dynamic-link-library (DLL) file, use the following command:
   rc example.res dynalink.dll
   rc example.res dynalink.dll


[[Category:PM Guide]]
[[Category:PM Guide]]

Latest revision as of 04:22, 6 May 2025

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

Presentation Manager Programming Guide and Reference
  1. How to Use this Book
  2. Device Functions
  3. Direct Manipulation Functions
  4. Dynamic Data Formatting Functions
  5. Hooks and Procedures
  6. Profile Functions
  7. Spooler Functions
  8. Window Functions
  9. Message Processing
  10. Data Types
  11. Errors
  12. Atom Tables
  13. Button Controls
  14. Clipboards
  15. Combination Box
  16. Container Controls
  17. Control Windows
  18. Cursors
  19. Dialog Windows
  20. Direct Manipulation
  21. Drawing in Windows
  22. Dynamic Data Exchange
  23. Entry-Field Controls
  24. File Dialog Controls
  25. Font Dialog Controls
  26. Frame Windows
  27. Hooks
  28. Initialization Files
  29. Keyboard Accelerators
  30. List-Box Controls
  31. Menus
  32. Messages and Message Queues
  33. Multiple-Line Entry Field Controls
  34. Mouse and Keyboard Input
  35. Mouse Pointers and Icons
  36. Notebook Controls
  37. Painting and Drawing
  38. Presentation Parameters
  39. Resource Files
  40. Scroll-Bar Controls
  41. Slider Controls
  42. Spin Button Controls
  43. Static Controls
  44. Title-Bar Controls
  45. Value Set Controls
  46. Windows
  47. Window Classes
  48. Window Procedures
  49. Window Timers
  50. Appendices
  51. Notices
  52. 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

ACCELTABLE Statement

The `ACCELTABLE` statement creates a table of accelerators for an application.

Syntax

ACCELTABLE acceltable-id [mem-option][load-option]
BEGIN
    key-value, command[, accelerator-options]
    ...
END

Description

An accelerator is a keystroke that provides a quick way to choose a command from a menu or perform another task. An accelerator table can be loaded from the executable file using the `WinLoadAccelTable` function.

Example

This example creates an accelerator table with identifier `1`, containing two accelerators: `Ctrl+S` and `Ctrl+G`. These generate `WM_COMMAND` messages with values `101` and `102`, respectively. 

ACCELTABLE 1
BEGIN
    "S", 101, CONTROL
    "G", 102, CONTROL
END

ASSOCTABLE Statement

The `ASSOCTABLE` statement defines a file-association table for an application.

Syntax

ASSOCTABLE assoctable-id [load-option][mem-option]
BEGIN
    association-name, file-match-string[, extended-attribute-flag][, icon-filename]
    ...
END

Description

This table associates data files created by an application with its executable file, launching the application when a data file is selected. It can also associate icons with data files by file type. Multiple `ASSOCTABLE` statements can be provided, but each must have a unique `assoctable-id`. Only the last file-association table is written to the `.ASSOC` extended attribute.

AUTOCHECKBOX Statement

The `AUTOCHECKBOX` statement creates an automatic-check-box control.

Syntax

AUTOCHECKBOX text, id, x, y, width [, style]

Description

This control is a small rectangle (check box) displaying an `X` when selected, with text to its right. The `X` toggles on and off with each selection. Used only in `DIALOG` or `WINDOW` statements, it defines the text, identifier, dimensions, and attributes. The predefined class is `WC_BUTTON`. Default style: `BS_AUTOCHECKBOX` and `WS_TABSTOP`.

Example

This example creates an automatic-check-box control labeled `Italic`. 

AUTOCHECKBOX "Italic", 101, 10, 10, 100, 100

AUTORADIOBUTTON Statement

The `AUTORADIOBUTTON` statement creates an automatic-radio-button control.

Syntax

AUTORADIOBUTTON text, id, x, y, width, height [, style]

Description

This control is a small circle with text to its right, highlighting when selected and sending a message to its parent window. It deselects other radio buttons in the same group. Used only in `DIALOG` or `WINDOW` statements, it defines the text, identifier, dimensions, and attributes. The predefined class is `WC_BUTTON`. Default style: `BS_AUTORADIOBUTTON`.

Example

This example creates an automatic-radio-button control labeled `Italic`. 

AUTORADIOBUTTON "Italic", 101, 10, 10, 24, 50

BITMAP Statement

The `BITMAP` statement defines a bitmap resource for an application.

Syntax

BITMAP bitmap-id [load-option] [mem-option] filename

Description

A bitmap resource, typically created with the Icon Editor, is a custom bitmap used in displays or menus. The statement copies the bitmap from the specified file and adds it to the application’s resources. It can be loaded using `GpiLoadBitmap`. Each `BITMAP` statement must have a unique `bitmap-id`.

Example

This example defines a bitmap with identifier `12`, copied from `custom.bmp`. 

BITMAP 12 custom.bmp

CHECKBOX Statement

The `CHECKBOX` statement creates a check-box control.

Syntax

CHECKBOX text, id, x, y, width, height [, style]

Description

This control is a small rectangle with text to its right, highlighting when selected and sending a message to its parent window. Used only in `DIALOG` or `WINDOW` statements, it defines the text, identifier, dimensions, and attributes. The predefined class is `WC_BUTTON`. Default style: `BS_CHECKBOX` and `WS_TABSTOP`.

Example

This example creates a check-box control labeled `Italic`. 

CHECKBOX "Italic", 101, 10, 10, 100, 100

CODEPAGE Statement

The `CODEPAGE` statement sets the code page for subsequent resources.

Syntax

CODEPAGE codepage-id

Description

The code page specifies the character set used for resources. If not specified, the system’s code page is used. Multiple `CODEPAGE` statements can apply to resources between them.

Example

This example sets the code page to Portuguese (860) for string resources. 

CODEPAGE 860
STRINGTABLE
BEGIN
    1 "Filename not found"
    2 "Cannot open file for reading"
END

COMBOBOX Statement

The `COMBOBOX` statement creates a combination-box control.

Syntax

COMBOBOX text, id, x, y, width, height [, style]

Description

This control combines a list box with an entry field, allowing users to select or enter text. Used only in `DIALOG` or `WINDOW` statements, it defines the text, identifier, dimensions, and attributes. The predefined class is `WC_COMBOBOX`. Default style: `CBS_SIMPLE`, `WS_GROUP`, `WS_TABSTOP`, `WS_VISIBLE`.

Example

This example creates a combination-box control. 

COMBOBOX "", 101, 10, 10, 24, 50

CONTAINER Statement

The `CONTAINER` statement creates a container control within a dialog window.

Syntax

CONTAINER id, x, y, width, height [, style]

Description

This control holds objects and is defined by its identifier, position, dimensions, and attributes. The predefined class is `WC_CONTAINER`. Default style: `WS_TABSTOP`, `WS_VISIBLE`, `CCS_SINGLESEL`. Used only in `DIALOG` or `WINDOW` statements.

Example

This example creates a container control with multiple selection. 

#define IDC_CONTAINER    301
#define IDD_CONTAINERDLG 504
DIALOG "Container", IDD_CONTAINERDLG, 23, 6, 120, 280, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
BEGIN
    CONTAINER IDC_CONTAINER, 30, 30, 70, 200, CCS_MULTIPLESEL | WS_GROUP
END

CONTROL Statement

The `CONTROL` statement defines a control belonging to a specified class.

Syntax

CONTROL text, id, x, y, width, height, class [, style]
[ data-definitions ]
[ BEGIN
    control-definition
    ...
END ]

Description

This statement defines the position, dimensions, and style of a control within its parent window. Used primarily in `DIALOG` or `WINDOW` statements, each control must have a unique `id`. Optional `BEGIN` and `END` enclose child control statements.

Example

This example creates a push-button control. 

CONTROL "OK", 101, 10, 10, 20, 50, WC_BUTTON, BS_PUSHBUTTON | WS_TABSTOP | WS_VISIBLE

CTEXT Statement

The `CTEXT` statement creates a centered-text control.

Syntax

CTEXT text, id, x, y, width, height [, style]

Description

This control displays centered text in a rectangle, wrapping words to the next line as needed. Used only in `DIALOG` or `WINDOW` statements, it defines the text, identifier, dimensions, and attributes. The predefined class is `WC_STATIC`. Default style: `SS_TEXT`, `DT_CENTER`, `WS_GROUP`.

Example

This example creates a centered-text control labeled `Filename`. 

CTEXT "Filename", 101, 10, 10, 100, 100

CTLDATA Statement

The `CTLDATA` statement defines control data for a custom dialog box, window, or control.

Syntax

CTLDATA word-value [, word-value]
CTLDATA string
CTLDATA MENU
BEGIN
    menuitem-definition
    ...
END

Description

This statement supports three forms: menu, word values, or strings, allowing custom data for window procedures. It is typically used for custom window classes to control their operation, such as extended style bits.

Example

This example creates a menu for a window. 

WINDOWTEMPLATE 1
BEGIN
    WINDOW "Sample", 1, 0, 0, 100, 100, "MYCLASS", 0, FCF_STANDARD
    CTLDATA MENU
    BEGIN
        MENUITEM "Exit", 101
    END
END

DEFAULTICON Statement

The `DEFAULTICON` statement installs an icon file as the default icon under the `ICON` extended attribute.

Syntax

DEFAULTICON filename

Description

An icon with `icon-id` of `1` is the default unless another is specified.

Example

DEFAULTICON filename.ico

DEFPUSHBUTTON Statement

The `DEFPUSHBUTTON` statement creates a default push-button control.

Syntax

DEFPUSHBUTTON text, id, x, y, width, height [, style]

Description

This control is a round-cornered rectangle with bold text, acting as the default response. It sends a message to its parent when selected. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_BUTTON`. Default style: `BS_PUSHBUTTON`, `BS_DEFAULT`, `WS_TABSTOP`.

Example

This example creates a default push-button labeled `Cancel`. 

DEFPUSHBUTTON "Cancel", 101, 10, 10, 24, 50

DIALOG Statement

The `DIALOG` statement defines a dialog box window.

Syntax

DIALOG text, id, x, y, width, height [, [style] [,framectl]] [data-definitions]
BEGIN
    control-definition
    ...
END

Description

This statement defines the position, dimensions, and style of a dialog box, typically used in `DLGTEMPLATE` statements. Coordinates depend on the style (`FS_SCREENALIGN`, `FS_MOUSEALIGN`, or parent window origin). It can contain `CONTROL`, `DIALOG`, or `WINDOW` statements.

Example

This example creates a dialog box labeled `Disk Error`. 

DLGTEMPLATE 1
BEGIN
    DIALOG "Disk Error", 100, 10, 10, 300, 110
    BEGIN
        CTEXT "Select One:", 1, 10, 80, 280, 12
        RADIOBUTTON "Retry", 2, 75, 50, 60, 12
        RADIOBUTTON "Abort", 3, 75, 30, 60, 12
        RADIOBUTTON "Ignore", 4, 75, 10, 60, 12
    END
END

DLGINCLUDE Statement

The `DLGINCLUDE` statement adds a specified file to the resource file.

Syntax

DLGINCLUDE id filename

Description

This statement allows access to a definitions file for a dialog box with the corresponding identifier. Each `DLGINCLUDE` statement must have a unique `id`.

Example

This example includes the file `dlgdef.h` for dialog-box identifier `5`. 

DLGINCLUDE 5 "\\INCLUDE\\DLGDEF.H"

DLGTEMPLATE Statement

The `DLGTEMPLATE` statement creates a dialog-box template.

Syntax

DLGTEMPLATE dialog-id [load-option] [mem-option]
BEGIN
    dialog-definition
    ...
END

Description

A dialog-box template defines the identifier, load/memory options, dimensions, and controls. It can be loaded using `WinLoadDlg`. Each template must have a unique `dialog-id`.

Example

This example creates a dialog box for a timer. 

DLGTEMPLATE ID_GETTIMER
BEGIN
    DIALOG "Timer", 1, 10, 10, 100, 40
    BEGIN
        LTEXT "Time (0 - 15):", 4, 8, 24, 72, 12
        ENTRYFIELD "0", ID_TIME, 80, 28, 16, 8, ES_MARGIN
        DEFPUSHBUTTON "Enter", ID_TIMEOK, 10, 6, 36, 12
        PUSHBUTTON "Cancel", ID_TIMECANCEL, 52, 6, 40, 12
    END
END

EDITTEXT Statement

The `EDITTEXT` statement creates an entry-field control.

Syntax

EDITTEXT text, id, x, y, width, height [, style]

Description

This control is a rectangle for typing and editing text, supporting keyboard and mouse interactions. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_ENTRYFIELD`. Default style: `ES_AUTOSCROLL`, `WS_TABSTOP`. Identical to `ENTRYFIELD`.

Example

This example creates an unlabeled entry-field control. 

EDITTEXT "", 101, 10, 10, 24, 50

ENTRYFIELD Statement

The `ENTRYFIELD` statement creates an entry-field control.

Syntax

ENTRYFIELD text, id, x, y, width, height [, style]

Description

This control is a rectangle for typing and editing text, identical to `EDITTEXT`. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_ENTRYFIELD`. Default style: `ES_AUTOSCROLL`, `WS_TABSTOP`.

Example

This example creates an unlabeled entry-field control. 

ENTRYFIELD "", 101, 10, 10, 24, 50

FONT Statement

The `FONT` statement defines a font resource for an application.

Syntax

FONT font-id [load-option] [mem-option] filename

Description

A font resource, created using the OS/2 Font Editor, defines character shapes. The statement copies the font from the specified file and can be loaded using `GpiLoadFonts`. Each `FONT` statement must have a unique `font-id`.

Example

This example defines a font with identifier `5`, copied from `cmroman.fon`. 

FONT 5 cmroman.fon

FRAME Statement

The `FRAME` statement defines a frame window.

Syntax

FRAME text, id, x, y, width, height, style [, framectl]
data-definitions
[ BEGIN
    window-definition
    ...
END ]

Description

This statement defines the title, identifier, position, dimensions, and style of a frame window, typically used in `WINDOWTEMPLATE` statements. It usually contains a `WINDOW` statement for the client window. Frame controls (e.g., title bar) are defined via `framectl`.

Example

This example creates a frame window with a client window. 

WINDOWTEMPLATE 1
BEGIN
    FRAME "My Window", 1, 10, 10, 320, 130, 0, FCF_STANDARD | FCF_VERTSCROLL
    BEGIN
        WINDOW "", FID_CLIENT, 0, 0, 0, 0, "MyClientClass"
    END
END

GROUPBOX Statement

The `GROUPBOX` statement creates a group-box control.

Syntax

GROUPBOX text, id, x, y, width, height [, style]

Description

This control groups other controls with a border and text in the upper-left corner. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_STATIC`. Default style: `SS_GROUPBOX`, `WS_TABSTOP`.

Example

This example creates a group-box control labeled `Options`. 

GROUPBOX "Options", 101, 10, 10, 100, 100

HELPITEM Statement

The `HELPITEM` statement defines help items in a help table.

Syntax

HELPITEM application-window-id, help-subtable-id, extended-helppanel-id

Description

This statement specifies identifiers for an application window, its help subtable, and extended help panel. Used only in `HELPTABLE` statements, one `HELPITEM` is needed per application window with help.

Example

This example associates a help subtable and panel with an application window. 

HELPITEM IDWIN_FILEMENU, IDSUB_FILEMENU, IDEXT_APPHLP

HELPSUBITEM Statement

The `HELPSUBITEM` statement defines help subitems in a help subtable.

Syntax

HELPSUBITEM child-window-id, helppanel-id [, integer]

Description

This statement specifies a child window’s identifier, its help panel, and optional integers. Used only in `HELPSUBTABLE` statements, one `HELPSUBITEM` is needed per child window with help.

Example

This example associates a child window with a help panel. 

HELPSUBITEM IDCLD_FILEMENU, IDHP_FILEMENU

HELPSUBTABLE Statement

The `HELPSUBTABLE` statement defines a help-subtable resource.

Syntax

HELPSUBTABLE helpsubtable-id [SUBITEMSIZE size]
BEGIN
    helpsubitem-definition
    ...
END

Description

A help subtable contains a help subitem for each selectable item in an application window. Each `HELPSUBTABLE` must have a unique `helpsubtable-id`. The `SUBITEMSIZE` statement is required if optional integers are included.

Example

This example creates a help subtable with two subitems. 

HELPSUBTABLE IDSUB_FILEMENU
BEGIN
    HELPSUBITEM IDCLD_OPEN, IDPNL_OPEN
    HELPSUBITEM IDCLD_SAVE, IDPNL_SAVE
END

HELPTABLE Statement

The `HELPTABLE` statement defines a help-table resource.

Syntax

HELPTABLE helptable-id
BEGIN
    helpitem-definition
    ...
END

Description

A help table contains a help item for each application window, dialog box, or message box with help. Each `HELPTABLE` must have a unique `helptable-id`.

Example

This example creates a help table with two help items. 

HELPTABLE 1
BEGIN
    HELPITEM IDWIN_FILEMENU, IDSUB_FILEMENU, IDEXT_APPHLP
    HELPITEM IDWIN_EDITMENU, IDSUB_EDITMENU, IDEXT_APPHLP
END

ICON Statement (Resource)

The `ICON` statement defines an icon resource for an application.

Syntax

ICON icon-id [load-option] [mem-option] filename

Description

An icon resource, created with the Icon Editor, defines an application’s icon. It is copied from the specified file and can be loaded using `WinCreateStdWindow` with `FS_ICON`. Each `ICON` statement must have a unique `icon-id`. An `icon-id` of `1` is the default and written to the `.ICON` extended attribute.

Example

This example defines an icon with identifier `11`, copied from `custom.ico`. 

ICON 11 custom.ico

ICON Statement (Control)

The `ICON` statement creates an icon control.

Syntax

ICON icon-id, id, x, y, width, height [, style]

Description

This control displays an icon in a dialog box. The width and height fields are ignored as the icon sizes itself. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_STATIC`. Default style: `SS_ICON`.

Example

This example creates an icon control with icon identifier `99`. 

ICON 99, 101, 10, 10, 0, 0

LISTBOX Statement

The `LISTBOX` statement creates a list-box control.

Syntax

LISTBOX id, x, y, width, height [, style]

Description

This control displays a list of user-selectable strings. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_LISTBOX`. Default style: `WS_TABSTOP`.

Example

This example creates a list-box control with identifier `101`. 

LISTBOX 101, 10, 10, 100, 100

LTEXT Statement

The `LTEXT` statement creates a left-aligned text control.

Syntax

LTEXT text, id, x, y, width, height [, style]

Description

This control displays left-aligned text, wrapping words to the next line. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_STATIC`. Default style: `SS_TEXT`, `DT_LEFT`, `WS_GROUP`.

Example

This example creates a left-aligned text control labeled `Filename`. 

LTEXT "Filename", 101, 10, 10, 100, 100

MENU Statement

The `MENU` statement defines a menu resource.

Syntax

MENU menu-id [load-option] [mem-option]
BEGIN
    menuitem-definition
    ...
END

Description

A menu resource defines an application’s menu appearance and function, loadable via `WinLoadMenu`. Each `MENU` statement must have a unique `menu-id`. Menu items are defined in the order specified.

Example

This example creates a menu with a menu item and a submenu. 

MENU 1
BEGIN
    MENUITEM "Alpha", 100
    SUBMENU "Beta", 101
    BEGIN
        MENUITEM "Item 1", 200
        MENUITEM "Item 2", 201, , MIA_CHECKED
    END
END

MENUITEM Statement

The `MENUITEM` statement creates a menu item.

Syntax

MENUITEM text, menu-id [, menuitem-style [, menuitem-attribute]]

Description

This statement defines a menu item’s text, identifier, and attributes, used only in `MENU` or `SUBMENU` statements. A `WM_COMMAND` message is sent when selected. The `MENUITEM SEPARATOR` form creates a horizontal divider. Special characters like `\t`, `\a`, and `~` control formatting and mnemonics.

Example

This example creates various menu items. 

MENUITEM "Alpha", 101
MENUITEM "Beta", 102, MIS_TEXT, MIA_CHECKED
MENUITEM "Gamma", 103
MENUITEM SEPARATOR
MENUITEM "Delta", 104
BITMAP 1 mybitmap.bmp
MENUITEM "#1", 301, MIS_BITMAP

MESSAGETABLE Statement

The `MESSAGETABLE` statement creates string resources.

Syntax

MESSAGETABLE [load-option] [mem-option]
BEGIN
    string-id string-definition
    ...
END

Description

String resources are null-terminated with unique identifiers, loadable via `DosGetResource` with `RT_MESSAGE`. Strings are bundled in groups of 16, with bundle ID calculated as `(id / 16) + 1` and string index as `id % 16`. Most applications prefer `STRINGTABLE`.

Example

This example creates two string resources. 

MESSAGETABLE
BEGIN
    1 "Filename not found"
    2 "Cannot open file for reading"
END

MLE Statement

The `MLE` statement creates a multiple-line entry-field control.

Syntax

MLE text, id, x, y, width, height [, style]

Description

This control allows typing and editing multiple lines of text. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_MLE`. Default style: `MLS_BORDER`, `WS_GROUP`, `WS_TABSTOP`.

Example

This example creates an unlabeled multiple-line entry-field control. 

MLE "", 101, 10, 10, 50, 100

NOTEBOOK Statement

The `NOTEBOOK` statement creates a notebook control.

Syntax

NOTEBOOK id, x, y, width, height [, style]

Description

This control organizes information on pages. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_NOTEBOOK`. Default style: `WS_TABSTOP`, `WS_VISIBLE`.

Example

This example creates a notebook control with rounded tabs. 

#define IDC_NOTEBOOK 201
#define IDD_NOTEBOOKDLG 503
DIALOG "Notebook", IDD_NOTEBOOKDLG, 11, 11, 420, 420, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
BEGIN
    NOTEBOOK IDC_NOTEBOOK, 20, 20, 200, 400, BKS_ROUNDEDTABS | WS_GROUP
END

POINTER Statement

The `POINTER` statement defines a pointer resource.

Syntax

POINTER pointer-id [load-option] [mem-option] filename

Description

A pointer resource, created with the OS/2 Icon Editor, defines the mouse pointer shape. It is copied from the specified file and loadable via `WinLoadPointer`. Each `POINTER` statement must have a unique `pointer-id`.

Example

This example defines a pointer with identifier `10`, copied from `custom.cur`. 

POINTER 10 custom.cur

PRESPARAMS Statement

The `PRESPARAMS` statement defines presentation fields for customization.

Syntax

PRESPARAMS presparam, value [, value]

Description

This statement provides data to control the appearance of dialog boxes, menus, windows, or controls, processed by their window procedures. It is often used for custom controls, e.g., specifying colors or fonts.

Example

This example sets a menu’s font to 12-point Helvetica. 

MENU 1
BEGIN
    PRESPARAMS PP_FONTNAMESIZE, "12.Helv"
    MENUITEM "New", 100
    MENUITEM "Open", 101
    MENUITEM "Save", 102
END

PUSHBUTTON Statement

The `PUSHBUTTON` statement creates a push-button control.

Syntax

PUSHBUTTON text, id, x, y, width, height [, style]

Description

This control is a round-cornered rectangle with text, sending a message to its parent when selected. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_BUTTON`. Default style: `BS_PUSHBUTTON`, `WS_TABSTOP`.

Example

This example creates a push-button control labeled `OK`. 

PUSHBUTTON "OK", 101, 10, 10, 100, 100

RADIOBUTTON Statement

The `RADIOBUTTON` statement creates a radio-button control.

Syntax

RADIOBUTTON text, id, x, y, width, height [, style]

Description

This control is a small circle with text, highlighting when selected and sending a message to its parent. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_BUTTON`. Default style: `BS_RADIOBUTTON`.

Example

This example creates a radio-button control labeled `Italic`. 

RADIOBUTTON "Italic", 101, 10, 10, 24, 50

RCDATA Statement

The `RCDATA` statement defines a custom-data resource.

Syntax

RCDATA resource-id
BEGIN
    data-definition [, data-definition]
    ...
END

Description

Custom data can be in any format, loadable via `DosGetResource` or `DosGetResource2` with `RT_RCDATA`. Each `RCDATA` statement must have a unique `resource-id`.

Example

This example defines custom data with identifier `5`. 

RCDATA 5
BEGIN
    "E. A. Poe", 1849, -32, 3L, 0x8000000l, 3+4+5
END

RCINCLUDE Statement

The `RCINCLUDE` statement includes another resource script file.

Syntax

RCINCLUDE filename

Description

The specified file is processed alongside the current script, with results compiled into one binary resource file. For HPFS filenames with spaces, use double quotes.

Example

This example includes `dialogs.rc`. 

RCINCLUDE dialogs.rc

RESOURCE Statement

The `RESOURCE` statement defines a custom resource.

Syntax

RESOURCE type-id resource-id [load-option] [mem-option] filename

Description

Custom resources can be any data, copied from the specified file and loadable via `DosGetResource` or `DosGetResource2`. Each statement must have a unique `type-id` and `resource-id` combination.

Example

This example defines a custom resource with type `300` and identifier `14`. 

RESOURCE 300 14 custom.res

RTEXT Statement

The `RTEXT` statement creates a right-aligned text control.

Syntax

RTEXT text, id, x, y, width, height [, style]

Description

This control displays right-aligned text, wrapping words to the next line. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_STATIC`. Default style: `SS_TEXT`, `DT_RIGHT`, `WS_GROUP`.

Example

This example creates a right-aligned text control labeled `Filename`. 

RTEXT "Filename", 101, 10, 10, 100, 100

SLIDER Statement

The `SLIDER` statement creates a slider control.

Syntax

SLIDER id, x, y, width, height [, style]

Description

This control allows users to set or modify a value by moving a slider arm. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_SLIDER`. Default style: `WS_TABSTOP`, `WS_VISIBLE`.

Example

This example creates a slider control with buttons on the left. 

#define IDC_SLIDER 101
#define IDD_SLIDERDLG 502
DIALOG "Slider", IDD_SLIDERDLG, 11, 11, 200, 240, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
BEGIN
    SLIDER IDC_SLIDER, 40, 30, 120, 16, SLS_BUTTONSLEFT | WS_VISIBLE
END

SPINBUTTON Statement

The `SPINBUTTON` statement creates a spin-button control.

Syntax

SPINBUTTON id, x, y, width, height [, style]

Description

This control provides access to a finite set of data. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_SPINBUTTON`. Default style: `WS_TABSTOP`, `WS_VISIBLE`, `SPBS_MASTER`.

Example

This example creates a numeric-only spin-button control. 

#define IDC_SPINBUTTON 302
#define IDD_SPINDLG 502
DIALOG "Spin button", IDD_SPINDLG, 11, 11, 200, 240, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
BEGIN
    SPINBUTTON IDC_SPINBUTTON, 80, 20, 60, 24, SPBS_NUMERICONLY | WS_TABSTOP
END

STRINGTABLE Statement

The `STRINGTABLE` statement creates string resources.

Syntax

STRINGTABLE [load-option] [mem-option]
BEGIN
    string-id string-definition
    ...
END

Description

String resources are null-terminated with unique identifiers, loadable via `WinLoadString` or `DosGetResource` with `RT_STRING`. Strings are bundled in groups of 16, with bundle ID calculated as `(id / 16) + 1` and string index as `id % 16`.

Example

This example creates two string resources. 

#define IDS_HELLO 1
#define IDS_GOODBYE 2
STRINGTABLE
BEGIN
    IDS_HELLO "Hello"
    IDS_GOODBYE "Goodbye"
END

SUBITEMSIZE Statement

The `SUBITEMSIZE` statement specifies the size of help subitems.

Syntax

SUBITEMSIZE size

Description

This statement sets the size (in words) of each help subitem in a help subtable, with a minimum of two words. It must appear after `HELPSUBTABLE` and before `BEGIN`.

Example

This example specifies three-word help subitems. 

HELPSUBTABLE 1
SUBITEMSIZE 3
BEGIN
    HELPSUBITEM IDCLD_FILEMENU, IDHP_FILEMENU, 5
    HELPSUBITEM IDCLD_HELPMENU, IDHP_HELPMENU, 6
END

SUBMENU Statement

The `SUBMENU` statement creates a submenu.

Syntax

SUBMENU text, submenu-id [, menuitem-style[, menuitem-attribute]]
BEGIN
    menuitem-definition
    ...
END

Description

A submenu is a vertical list of menu items. Each `SUBMENU` statement must have a unique `submenu-id`. Menu items are defined in the order specified.

Example

This example creates a submenu with three menu items. 

SUBMENU "Elements", 2
BEGIN
    MENUITEM "Oxygen", 200
    MENUITEM "Carbon", 201, , MIA_CHECKED
    MENUITEM "Hydrogen", 202
END

VALUESET Statement

The `VALUESET` statement creates a value set control.

Syntax

VALUESET id, x, y, width, height [, style]

Description

This control allows selection from mutually exclusive choices. Used only in `DIALOG` or `WINDOW` statements, the predefined class is `WC_VALUESET`. Default style: `WS_TABSTOP`, `WS_VISIBLE`.

Example

This example creates a value set control with icons. 

#define IDC_VALUESET 302
#define IDD_VALUESETDLG 501
DIALOG "Value set", IDD_VALUESETDLG, 11, 11, 260, 240, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
BEGIN
    VALUESET IDC_VALUESET, 40, 40, 220, 160, VS_ICON | WS_TABSTOP
END

WINDOW Statement

The `WINDOW` statement creates a window of a specified class.

Syntax

WINDOW text, id, x, y, width, height, class [, style [, framect]]
data-definitions
[ BEGIN
    control-definition
    ...
END ]

Description

This statement defines the window’s position, dimensions, and style, typically used in `WINDOWTEMPLATE` or `FRAME` statements. It usually defines a client window in a `FRAME` statement.

Example

This example creates a client window. 

WINDOWTEMPLATE 1
BEGIN
    FRAME "My Window", 1, 10, 10, 320, 130, 0, FCF_STANDARD | FCF_VERTSCROLL
    BEGIN
        WINDOW "", FID_CLIENT, 0, 0, 0, 0, "MyClientClass"
    END
END

WINDOWTEMPLATE Statement

The `WINDOWTEMPLATE` statement creates a window template.

Syntax

WINDOWTEMPLATE window-id [load-option] [mem-option]
BEGIN
    window-definition
    ...
END

Description

A window template defines the window identifier, load/memory options, dimensions, and controls, loadable via `WinLoadDlg`. Each template must have a unique `window-id`.

Description

A window template defines the window identifier, load/memory options, dimensions, and controls, loadable via `WinLoadDlg`. Each template must have a unique `window-id`.

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

#define Directive

The #define directive assigns the given value to the specified name. All subsequent occurrences of the name are replaced by the value.

Syntax

#define name value

Example

This example assigns values to the names `NONZERO` and `USERCLASS`. 

#define NONZERO 1
#define USERCLASS "MyControlClass"

#elif Directive

The #elif directive marks an optional clause of a conditional-compilation block defined by a #ifdef, #ifndef, or #if directive. The directive controls conditional compilation of the resource file by checking the specified constant expression. If the constant expression is nonzero, #elif directs the compiler to continue processing statements up to the next #endif, #else, or #elif directive and then skip to the statement after #endif. If the constant expression is zero, #elif directs the compiler to skip to the next #endif, #else, or #elif directive. You can use any number of #elif directives in a conditional block.

Syntax

#elif constant-expression

Example

In this example, #elif directs the compiler to process the second BITMAP statement only if the value assigned to the name `Version` is less than 7. The #elif directive itself is processed only if Version is greater than or equal to 3. 

#if Version < 3
BITMAP 1 errbox.bmp
#elif Version < 7
BITMAP 1 userbox.bmp
#endif

#else Directive

The #else directive marks an optional clause of a conditional-compilation block defined by a #ifdef, #ifndef, or #if directive. The #else directive must be the last directive before the #endif directive. This directive has no arguments.

Syntax

#else

Example

This example compiles the second BITMAP statement only if the name `DEBUG` is not defined. 

#ifdef DEBUG
BITMAP 1 errbox.bmp
#else
BITMAP 1 userbox.bmp
#endif

#endif Directive

The #endif directive marks the end of a conditional-compilation block defined by a #ifdef directive. One #endif is required for each #if, #ifdef, or #ifndef directive. This directive has no arguments.

Syntax

#endif

#if Directive

The #if directive controls conditional compilation of the resource file by checking the specified constant expression. If the constant expression is nonzero, #if directs the compiler to continue processing statements up to the next #endif, #else, or #elif directive and then skip to the statement after the #endif directive. If the constant expression is zero, it directs the compiler to skip to the next #endif, #else, or #elif directive.

Syntax

#if constant-expression

Example

This example compiles the BITMAP statement only if the value assigned to the name `Version` is less than 3. 

#if Version < 3
BITMAP 1 errbox.bmp
#endif

#ifdef Directive

The #ifdef directive controls conditional compilation of the resource file by checking the specified name. If the name has been defined by using a define directive or by using the -d command-line option of rc, #ifdef directs the compiler to continue with the statement immediately after the #ifdef directive. If the name has not been defined, #ifdef directs the compiler to skip all statements up to the next #endif directive.

Syntax

#ifdef name

Example

This example compiles the BITMAP statement only if the name `Debug` is defined. 

#ifdef Debug
BITMAP 1 errbox.bmp
#endif

#ifndef Directive

The #ifndef directive controls conditional compilation of the resource file by checking the specified name. If the name has not been defined or if its definition has been removed by using the #undef directive, #ifndef directs the compiler to continue processing statements up to the next #endif, #else, or #elif directive and then skip to the statement after the #endif directive. If the name is defined, #ifndef directs the compiler to skip to the next #endif, #else, or #elif directive.

Syntax

#ifndef name

Example

This example compiles the BITMAP statement only if the name `Optimize` is not defined. 

#ifndef Optimize
BITMAP 1 errbox.bmp
#endif

#include Directive

The #include directive causes RC to process the file specified in the filename field. This file should be a header file that defines the constants used in the resource script file. Only the define directives in the specified file are processed. All other statements are ignored. The filename field is handled as a C string. Therefore, you must include two backslashes (\\) wherever one is required in the path. (As an alternative, you can use a single forward slash (/) instead of two backslashes.)

Syntax

#include filename

Example

This example processes the header files OS2.H and HEADERS\MYDEFS.H while compiling the resource script file. 

#include <os2.h>
#include "headers\\mydefs.h"

#undef Directive

The #undef directive removes the current definition of the specified name. All subsequent occurrences of the name are processed without replacement.

Syntax

#undef name

Example

This example removes the definitions for the names `nonzero` and `USERCLASS`. 

#undef nonzero
#undef USERCLASS

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
Retrieved from "https://www.edm2.com/index.php?title=PMGuide_-_Resource_Files&oldid=86532"