# Windows Programming/Resource Script Reference

This appendix page will attempt to list the different types of resources, and will attempt to show how to use those resources.

## General construction

Resource script files are human-readable text files in either ANSI or Unicode (more strictly: UTF-16 with byte order mark (BOM)) format. To intermix different languages in ANSI format, a quirks #pragma exist to switch the code page in between. Unicode, #pragma switch, and the LANGUAGE statement are only supported for Win32.
A typical small file may look like
Using curly braces or BEGIN/END depends on your preference. The old, space-wasting style is the BEGIN/END pair, coming from the Pascal heritage of MacOS and Win16 API calls. C programmers typically prefer curly braces. The Visual Studio Resource Editor always generates BEGIN/END pairs, besides lots of housekeeping stuff.
Beginning with some header inclusion and #define statements, every resource is included as either
or
An exception from this rule is
* The LANGUAGE statement, can be placed almost everywhere (Win32 only)
* The DIALOG and the VERSIONINFO resource, there are additional statements between heading line and BEGIN
* The STRINGTABLE resource, where no resource ID is before the keyword. Instead, every string is prefixed with an ID
id_of_resource and resource_type can be either a string or a number. No quotes are there! A number is the preferred method for identification. All predefined resource types are numbers. But watch out! If you use an unknown ID for the resource compiler (let's say MANIFEST for Visual Studio 6), you will get neither error nor warning, and the resource is built with string resource type. Windows XP, using ExecProcess, will not find that intended manifest and your program will show up in old visual style.
Conditional compilation with #if / #ifdef / #endif is also supported.
Expressions for IDs are limited to very simple math, no boolean operators are permitted.

### Under the hood

Resources are compiled into a three-level directory structure:
* Resource type (MENU, DIALOG etc.)
* Resource ID (the number that is ahead the Resource Type – for STRINGTABLE, the ID of a group of up to 16 strings)
* Resource language (the currently active language, given by command-line option or LANGUAGE statement; Win32 only)
The content of following data depends on actual resource type. Mostly, it's binary.
Read access to the binary data of an arbitrary resource is done with
Because bitmap, icon, cursor, dialog, string table, and menu resources are not officially documented and a bit hard to parse, programmers should use specialized resource load functions for these resource types instead. See description and examples for these types below.

### Identifiers

Identifiers are generally named in a certain way, although the reader and all programmers are free to alter this naming scheme. It is simply a suggestion. Identifiers generally start with the prefix "ID", followed by a letter that denotes the type of identifier:
* IDS: A string resource
* IDM: A menu resource
* IDC: A command identifier
* IDD: A dialog box resource
* IDA: An Accelerator table resource
* IDI: An Icon or bitmap resource
* IDB: A Bitmap resource
* ID: A custom resource, or an uncommon resource type.
Sometimes, the command identifiers in a menu are given an "IDM_" prefix, to distinguish between commands from other sources.
There is no need to use symbolic identifiers. In some cases, identifiers complicate access to numerically adjanced controls in a dialog or menu. In any case, identifiers don't help non-English programmers to read a software source. Numbers never need translation. And both identifiers and numbers need explanation.
IDs are allowed in range 0..65535 and preferred in range 1..32767.

### LANGUAGE

This keyword has different scope:
* Local (for one resource) if located below the resource line, like
This language applies to that menu
* Global (for all next resources) if located somewhere else
Language-neutral resources, like culture-free icons, VersionInfo, and Manifests, should be always set to LANGUAGE 0,0 (or, more verbously, LANG_NEUTRAL,SUBLANG_NEUTRAL).
Note to always check images against culture dependency! A typical mistake is the plug symbol for a mains-supplied notebook: It shows undoubtly an American plug, even in Europe. Obviously, images containing letters or text are culture-dependent.

### Memory Management Flags

There are some Memory Management Flags from Win16 heritage, like MOVEABLE, FIXED, etc. See LocalAlloc for some flags.

#### DISCARDABLE

Resources are loaded into memory when the program is run. However, if a resource is not in use, and if Windows does not need them immediately, resources can be optionally unloaded from memory until needed. To specify that it is okay to unload an unused resource from memory, you may list the DISCARDABLE keyword with the resource. DISCARDABLE resources allow more efficient memory usage, but can slow down your program if they need to be loaded from disk.
The DISCARDABLE keyword is ignored for 32-bit Windows, but remains for compatibility. 32 bit resources are never loaded but mapped into memory.

## Icons

Icons can be stored in a resource file using the ICON keyword. Here is a general example of using an icon in a resource script:
Windows Explorer will display the binary executable with the first icon from the script. For instance, if we load two icons, as such:
And we define our macros as such in the corresponding resource.h:
The executable file will have icon1.ico as its icon.
To load an icon from an executable module, assuming we have an instance handle to the module (hInst in the following example), we can get a handle to the icon as such:
This will return a handle to the icon associated with the identifier "IDI_ICON1". Icon identifiers are generally prefixed with an "IDI_" which is short for "ID for an Icon".
The second parameter to the LoadIcon function is a pointer to a string. String pointers are 32 bit values. However, if the most significant 16 bits are all zero, Windows will treat the value as a resource number, and not a string. To make the conversion between a string and a 16-bit integer, Microsoft provides the MAKEINTRESOURCE macro. Similarly, we could have used a string to define our Icon:
And we could load this string by name:
String identifiers for resources are case insensitive.
WNDCLASSEX has handle values for two icons: a large icon and a small icon. The small icon is the icon used in the upper-left corner. Small icons are generally 16 pixels square. Larger icons are 32 pixels square. If no small icon handle is provided, the large icon will be shrunk down to fit.
If the LoadIcon function is supplied with a NULL instance handle, Windows will supply a default icon for use.
Recently, the Win32 API provides the LoadImage function for loading icons, bitmaps, and mouse cursors from a single function. You can find more information about this function on MSDN.
Internally, Icons are stored under numeric resource type RT_ICON == 3, and are grouped under RT_GROUP_ICON == 14.

## Bitmaps

Bitmaps can be loaded similarly to Icons in resource files:
Bitmaps can be accessed with the aptly named LoadBitmap function (again, new versions of the Win32 API prefer you use LoadImage to load a bitmap, icon, or cursor). LoadBitmap returns an HBITMAP handle type:
Or, if we have named our bitmap resource:
Bitmaps are large resources, and if windows can't load the bitmap into memory (or if the ID or name value is invalid), the function will return a NULL value. Make sure you test this value before you use the handle.
Bitmaps must be unloaded from memory by passing the handle to the DeleteObject function. You can find more information about this on MSDN
Bitmap identifiers generally use a "IDB_" prefix, to indicate that it is the ID of a bitmap.
Internally, Bitmaps are stored under numeric resource type RT_BITMAP == 2.

## Mouse Cursors

Mouse cursors are specified similarly to icons and bitmaps, and are loaded with the LoadCursor function.
Internally, cursors are stored under numeric resource type RT_CURSOR == 1, and are grouped under RT_GROUP_CURSOR == 12.
As for any resource that implies binary data, the use of an external file with "filename" is recommended. However, most resource compilers allow to inline binary data to the resource file in this way:
with this rule, coming from Win16 heritage:
* Numbers (decimal or hexadecimal) are stored contiguously as 16-bit little-endian quantities (unaligned)
* Characters are stored as 8-bit quantities

## String Tables

A resource script can have many string tables, although this is unneccessary: the tables aren't differentiated (i.e. they get merged), and each string object, in any table, must have a unique identifier. Strings in a string table also may not use names, but instead must use numeric identifiers. After all, it doesn't make any sense to have to address a string with a string, does it?
Here is a general string table:
It is important to note that in place of the BEGIN and END keywords, the programmer may also use the more C-like curly brackets, as such:
Some people prefer one over the other, but they are all the same to the resource compiler.
Strings can be loaded using the LoadString function. LoadString is more involved then the LoadBitmap or LoadIcon functions:
The hInstance parameter, as we know, is the instance handle for the module that contains the string. The uID parameter contains the string number that we are trying to access. lpBuffer is the character array variable that will receive the string, and the nBufferMax number tells windows what the maximum number of characters that can be loaded is. This count is a security precaution, so make sure not to allow Windows to write character data beyond the end of the string. MSDN displays a large warning on the page for this function, and it is important that programmers heed this warning. msdn
Windows will automatically zero-terminate the string, once it is written to the buffer. LoadString will return the number of characters that were actually written into the string, in case the number of characters is less than the maximum number allowed. If this return value is 0, the string resource does not exist, or could not be loaded.
Strings can have "\0" in the middle. As strings are saved as counted strings, LoadString returns the number of characters saved, including the zeroes in between. But most Resource Editors fail with such strings.
Internally, stringtables are stored under numeric resource type RT_STRING == 6, in groups of up to 16 adjanced IDs.

## Accelerators

Keyboard accelerators are a common part of nearly every windows application, and therefore it is a good idea to simplify the job of creating accelerators by putting them in a resource script. Here is how to create an accelerator table:
Key combinations are specified in terms of either a string literal character ("A" for instance) or a virtual key code value. Here are some examples:
Now, when the key combination "Shift+A" is pressed, your window procedure will receive a WM_COMMAND message with the value IDA_ACTION_A in the WPARAM field of the message.
If we want to use combinations of the "Alt" key, or the "Ctrl" key, we can use the ALT and CONTROL keywords, respectively:
Also, we can use the "^" symbol to denote a CONTROL key code:
Similarly, if we want to be super hackers, would could use the ASCII code directly:
Or, we could refer to keys (including non-alphanumeric keys) with their Virtual Key Code identifiers, by using the VIRTKEY identifier:
Now, If we make an accelerator correspond to a menu command, the menu command will light up when we press the accelerator. That is, the menu will light up unless we specify the "NOINVERT" keyword:
To Load an accelerator table, we need to use the LoadAccelerators function, as such:
Again, we could have given our resource a string name, and used that string to load the table.
When using accelerators, we need to alter our message loop to intercept the keypress messages, and translate them into command messages according to our accelerator table rules. We use the TranslateAccelerator function, to intercept the keypress messages, and translate them into command messages, as such:
Also, if we are writing an MDI application, we need to intercept Accelerator messages from the child windows, we use the TranslateMDISysAccel function also:
Where "hwndFrame" is the handle to the frame window, and "hwndClient" is the handle to the MDI client window.
Internally, Accelerators are stored under numeric resource type RT_ACCELERATOR == 9.

## Menus

Menus can be defined in a resource script using the MENU keyword. There are 2 types of items that appear in a menu, the top level "POPUP" menu items, and the secondary "MENUITEM" items. These are defined in a menu as such:
We have included a few examples here, so that you can see the difference between a POPUP and a MENUITEM. When we have a menu with the ID_MENU identifier, we can load it into our program as such:
Once we have this handle, we can pass it to the CreateWindow function, and apply it to our window.
When a menu item is selected, the host program receives a WM_COMMAND message, with the menu item identifier in the WPARAM parameter. If we have a basic window procedure switch-case statement, we can see this as follows:
In a menu, if we want to associate a menu item with an accelerator, we can define it as such:
Notice how we put the ampersand (&) in front of the "C" in "Copy" and the "P" in "Paste". This means that those letters will be underlined, but more importantly, if an accelerator key combination is pressed, those items in the menu will be highlighted (unless the NOINVERT tag is specified in the accelerator table). If an ampersand is placed before a POPUP menu item, pressing ALT+ that letter will popup that menu. For instance, lets define our menu:
Now, if we press ALT+F, we will pop open the File menu, and if we press ALT+E it will open the Edit menu. That's pretty nice functionality for only a single extra character to type.
Internally, Menus are stored under numeric resource type RT_MENU == 4.

## Version Information

A program can include certain information about its version, and its author in a resource script. This version information appears when you right-click the executable in Windows, and click "Properties". In the properties dialog box, this information appears on the "Version" tab.
Internally, VersionInfo is stored under numeric resource type RT_VERSION == 16. It was introduced with Windows 3.

## Dialog Boxes

Dialog box resources follow a general pattern:
if a dialog box is not being associated with a class, the CLASS field does not need to be filled in. All strings listed as being in quotes must be in quotes in the resource script or there will be an error. Individual items in a dialog box are then specified between the BEGIN and END tags.
Internally, Dialogs are stored under numeric resource type RT_DIALOG == 5.

### Generic Controls

CONTROL classname,windowname,id,left,top,width,height,windowflags

### Edit Boxes
## Manifests

Manifest resources contain UTF-8 encoded XML description of operating system and DLL dependency. Mostly, this resource dictates to use the Windows XP Version 6.0 comctl32.dll, to have Luna style for the standard and common controls.
Internally, Manifests are stored under numeric resource type RT_MANIFEST == 24. It was introduced with Windows 4.1.

## User-type resources

User-type resources should use some greater resource type identifiers, or RT_RCDATA == 10.