Tcl Windows API extension

Windows resources are binary data that can be added to executable files. Examples include icons, strings and fonts. This module provides commands related to manipulation of these resources.

Resources are stored in Portable Executable format files (exe's and dll's). A resource has an associated name, type and a language. The name and type can be either integer values or strings. To retrieve a particular resource, you must know both the associated values, the type and the name, for that resource. When a resource type or name is a string, it must be explicitly enclosed in quotes. For example,

::twapi::read_resource $h 14 {"ICON3"} 0

and not

::twapi::read_resource $h 14 "ICON3" 0

::twapi::read_resource $h 14 ICON3 0

To support localization, there can be several resources with the same type and name, but associated with different languages. These languages are identified by a 16 bit language identifier (LANGID) as described in the TWAPI Internationalization documentation.

TWAPI provides commands to retrieve and update resources as binary data. It does not provide any functionality related to constructing the actual binary data itself. Each resource type has a specific structure and it is up to the application to construct it appropriately.

In addition to the commands to load resources as binary data, TWAPI also provides commands to load certain resource types - icons, cursors and bitmaps - as GDI objects accessed through handles by other functions in the Windows API.

Resource Types

Windows defines certain standard resource types shown in the table below along with the corresponding #define values from the SDK.

1	RT_CURSOR - Cursor
2	RT_BITMAP - Bitmap
3	RT_ICON - Icon
4	RT_MENU - Menu
5	RT_DIALOG - Dialog
6	RT_STRING - String (see String Resources)
7	RT_FONTDIR - Font directory
8	RT_FONT - Font
9	RT_ACCELERATOR - Accelerator
10	RT_RCDATA - Application defined raw data
11	RT_MESSAGETABLE - Message table
12	RT_GROUP_CURSOR - Hardware independent cursor
14	RT_GROUP_ICON - Hardware independent icon
16	RT_VERSION - Version
17	RT_DLGINCLUDE - Name of C include file containing corresponding symbolic names of resources
19	RT_PLUGPLAY - Plug and play
20	RT_VXD - Vxd
21	RT_ANICURSOR - Animated cursor
22	RT_ANIICON - Animated icon
23	RT_HTML - HTML
24	RT_MANIFEST - Executable Manifest

Locating and Loading Resources

Manipulating a resource requires a Windows executable module handle for the corresponding executable file. The commands will accept NULL or 0 for this handle corresponding the the main executable for the process. To retrieve resources in other executables or DLL's, the module must be first loaded through the load_library call. Generally, the -datafile option should be passed to the load_library command if the only purpose is to access or update resources.

When the resources in a module are no longer required, it must be released through free_library call.

Once the module is loaded, the content of a particular resource can be retrieved using read_resource and read_resource_string.

You can also enumerate resources present in a module using the enumerate_resource_types enumerate_resource_names enumerate_resource_languages commands. The entire resource tree can be enumerated, optionally retrieving the resource values, through the command extract_resources.

Note that resources themselves do not need to be explicitly freed up. In particular, do not try to close the resource handles through the CloseHandle or close_handles.

Updating Resources

Updating a resource in a file requires that the file not be in use by any application (including the current process). The begin_resource_update command prepares the file for update. One or more update_resource commands can be used to modify the resources in the file and delete_resource commands can be used to delete resources. Finally, the the end_resource_update command is used to commit or discard the modifications.

String Resources

Strings defined through a string table definition in a resource definition file are not directly stored in the resource binary. They are stored in string blocks, each containing 16 strings. It is therefore not possible to directly retrieve or update a string based on its string id.

If you call read_resource with a resource type of 6 (STRING), the resource name or id has to actually be the id of the string block, not the string. The command resource_stringid_to_stringblockid will take a string id and return a pair consisting of the id of the corresponding block and the index of the string within the block. The block id can be passed to read_resource to read the string block. Since this is in binary format, it needs to be converted into a list of strings using resource_stringblock_to_strings. The string index returned from resource_stringid_to_stringblockid can be used to then pick out the appropriate string from the this list.

If you are only interested in a single string, the command read_resource_string encapsulates this entire process.

Updating strings in a resource involves multiple steps for the same reason. First, the string block has to be retrieved and converted to a list of strings as described above. The list must then be modified as desired and converted back to a string block using strings_to_resource_stringblock and then written out using update_resource.

Deleting a string resource is similar. Once the list of strings in the appropriate block is retrieved, set the corresponding element in the list to an empty string before writing it back using update_resource.

A peculiarity in the storage format for resource strings means it is not always possible to distinguish between a resource string that is not defined and a resource string that is defined with an empty value. An attempt to read an undefined resource string may either result in an error being generated, or in the return of an empty string.

Loading Resources as GDI objects

TWAPI also provides commands to load some resource types as GDI objects whose handles are opaque but can be passed to other commands in the Windows API. These include the commands load_icon_from_file, load_cursor_from_file, load_bitmap_from_file, load_icon_from_module, load_cursor_from_module, load_bitmap_from_module, load_icon_from_system, load_cursor_from_system and load_bitmap_from_system.

The handles returned by the above commands may be shared or unshared (as described in the documentation for the specific command). Unshared handles must be freed using free_icon, free_cursor and free_bitmap respectively. Shared handles are automatically freed by the system and must not be passed to the free commands.

The commands to load these GDI objects share a common set of options:

-createdibsection BOOLEAN	If true, returns a DIB section bitmap instead of a compatible bitmap. Default is false. This option is only valid for bitmap resources.
-defaultsize BOOLEAN	If false (default) and options -height and -width are not specified or specified as 0, Windows will use the actual resource size. If true, Windows will use the system metric settings. This option is only valid for cursors and icons.
-height INTEGER	Specifies the desired height of the icon or cursor. Default value is 0 in which case the width is controlled by the -defaultsize option.
-loadtransparent BOOLEAN	If specified as true, the color of the first pixel is replaced with the default window color. Should be used only if the color depth is 8 bpp or less. Default is false.
-monochrome BOOLEAN	If specified as true, returns a monochrome image. Default is false.
-vgacolor BOOLEAN	If true, uses VGA color.
-width INTEGER	Specifies the desired width of the icon or cursor. Default value is 0 in which case the width is controlled by the -defaultsize option.

Commands

begin_resource_update MODULEPATH ?-deleteall?: Returns a handle to the file MODULEPATH to be updated. The returned handle must be closed through the end_resource_update command. If the option -deleteall is specified, all existing resources in the file are deleted.
delete_resource HMODULE RESTYPE RESNAME LANGID: Deletes a resource from the specified module HMODULE which must be a handle previously retrieved via begin_resource_update. The resource is not actually deleted from the file until the end_resource_update command is called.
end_resource_update HMODULE ?-discard?: Closes a handle previously returned by the begin_resource_update command. Any modifications made through update_resource are written to the file unless the -discard option is specified in which case they are discarded.
enumerate_resource_languages HMODULE RESTYPE RESNAME: Returns a list of language identifiers for which the specified module contains a resource of type RESTYPE with name RESNAME. HMODULE must be a handle previously retrieved via load_library.
enumerate_resource_names HMODULE RESTYPE: Returns a list of the names of resources of type RESTYPE in the specified module. HMODULE must be a handle previously retrieved via load_library, get_module_handle, or get_module_handle_from_address.
enumerate_resource_types HMODULE: Returns a list of the types of resources in the specified module. HMODULE must be a handle previously retrieved via load_library.
extract_resources HMODULE ?INCLUDEDATA?: Extracts all resources from the specified module. The returned data is a nested dictionary with the first level key being the resource type, second level key the resource name and the third level key the language identifier.

If INCLUDEDATA is true, the actual binary data for the resource is returned as the value for each nested key. If INCLUDEDATA is not specified or is false, an empty string is returned as the value.
free_bitmap HBITMAP: Frees a bitmap handle and associated resources. The handle must not be for be a shared bitmap.
free_cursor HCURSOR: Frees a cursor handle and associated resources. The handle must not be for be a shared cursor.
free_icon HBITMAP: Frees a icon handle and associated resources. The handle must not be for be a shared icon.
load_bitmap_from_file PATH ?options?: Returns a handle to a bitmap loaded from a standalone file. The returned bitmap must be freed when no longer needed by calling free_bitmap.

See Loading Resources as GDI objects for a list of valid options.
load_bitmap_from_module HMODULE NAME ?options?: Returns a handle to a bitmap from a resource in a module that has been loaded into the process. The returned bitmap must be freed when no longer needed by calling free_bitmap.

HMODULE is handle to the module as returned by load_library, get_module_handle, or get_module_handle_from_address. NAME is the resource identifier.

See Loading Resources as GDI objects for a list of valid options.
load_bitmap_from_system NAME ?options?: Returns a handle to a bitmap built into Windows. The returned bitmap is a shared bitmap. Applications must not attempt to free it by calling free_bitmap.

NAME must be one of close, uparrow, dnarrow, rgarrow, lfarrow, reduce, zoom, restore, reduced, zoomd, restored, uparrowd, dnarrowd, rgarrowd, lfarrowd, mnarrow, combo, uparrowi, dnarrowi, rgarrowi, lfarrowi, size, btsize, check, checkboxes, btncorners.

See Loading Resources as GDI objects for a list of valid options.
load_cursor_from_file PATH ?options?: Returns a handle to a cursor loaded from a standalone file. The returned cursor must be freed when no longer needed by calling free_cursor.

See Loading Resources as GDI objects for a list of valid options.
load_cursor_from_module HMODULE NAME ?options?: Returns a handle to a cursor from a resource in a module that has been loaded into the process. The returned cursor must be freed when no longer needed by calling free_cursor.

HMODULE is handle to the module as returned by load_library, get_module_handle, or get_module_handle_from_address. NAME is the resource identifier.

See Loading Resources as GDI objects for a list of valid options.
load_cursor_from_system NAME ?options?: Returns a handle to a cursor built into Windows. The returned cursor is a shared cursor. Applications must not attempt to free it by calling free_cursor.

NAME must be one of normal, ibeam, wait, cross, up, sizenwse, sizenesw, sizewe, sizens, sizeall, no, hand or appstarting.

See Loading Resources as GDI objects for a list of valid options.
load_icon_from_file PATH ?options?: Returns a handle to an icon loaded from a standalone file. The returned icon must be freed when no longer needed by calling free_icon.

See Loading Resources as GDI objects for a list of valid options.
load_icon_from_module HMODULE NAME ?options?: Returns a handle to an icon from a resource in a module that has been loaded into the process. The returned icon must be freed when no longer needed by calling free_icon.

HMODULE is handle to the module as returned by load_library, get_module_handle, or get_module_handle_from_address. NAME is the resource identifier.

See Loading Resources as GDI objects for a list of valid options.
load_icon_from_system NAME ?options?: Returns a handle to an icon built into Windows. The returned icon is a shared icon. Applications must not attempt to free it by calling free_icon.

NAME must be one of sample, hand, ques, bang, note, winlogo, warning, error, information or shield.

See Loading Resources as GDI objects for a list of valid options.
read_resource HMODULE RESTYPE RESNAME LANGID: Returns the content of a resource from the specified module HMODULE which must be a handle previously retrieved via load_library.

Note that If RESTYPE is 6, specifying a STRING resource, RESTYPE is the id for a string block, not an individual string. The returned value is the binary data corresponding to the string block. To retrieve individual strings, use the read_resource_string command.
read_resource_string HMODULE STRINGID LANGID: Returns the string in the resource table for the module specified by HMODULE which must be a handle previously retrieved via load_library.

Because of the storage format used in string resources, it is not always possible to distinguish between a resource string that is not defined and a resource string that is defined with an empty value. An attempt to read an undefined resource string may either result in an error being generated, or in the return of an empty string.
resource_stringblock_to_strings BINDATA: Converts a binary resource string block to a list of strings. As every string block contains 16 strings, the returned list as exactly 16 strings.
resource_stringid_to_stringblockid STRINGID: Maps a string resource id to a list containing the id of the corresponding string block in the resource and the index of the string within the block as described in String Resources.
strings_to_resource_stringblock STRINGS: Converts the list of strings in STRINGS to a binary resource string block that can be passed to update_resource. The number of strings in STRINGS must not be more than 16 which is the number stored in a single resource string block. If fewer than 16 strings are provided, they are stored as empty strings.
update_resource HMODULE RESTYPE RESNAME LANGID RESDATA: Updates a resource from the specified module HMODULE which must be a handle previously retrieved via begin_resource_update. RESDATA should be the raw binary data for the resource in the type-specific format.

The resource is not actually written out to the file until the end_resource_update command is called.

Resources

SYNOPSIS

DESCRIPTION

Windows Resources