PMGuide - Resource Files

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

Presentation Manager Programming Guide and Reference

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

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

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

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

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

About Resource Files

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

Resource Statements

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

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

Single-line Statements

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

ICON 1 myicon.ico

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

Multiple-line Statements

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

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

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

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

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

Directives

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

Some examples of directives are:

• define
• if
• ifdef
• include

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

Resource File Statement Descriptions

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

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

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

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

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