Resource (.res) files are an intermediate container for resources such as bitmaps or text, which may later be compiled into applications, components, or DLLs. This article documents how and when to compile resource (.res) files from .rc text file prescriptions.

Visual GUIs are not always the "easy," most efficient, or most reliable way to get a job done. "Manual" compilation of resource (.res) files from .rc text file prescriptions overcomes the limitations of visual resource editors, and substantially automates your work:

• A simple .rc text file prescription prescribes run time resource names and associated source files.
  • Building a .rc text prescription is equivalent to merely providing the nomenclature required by a visual editor.
  • Usual visual processes such as opening source files, selecting and copying content, and pasting it into graphic containers of the visual editor, are eliminated.
• A shortcut runs the Borland Resource Compiler, which reads the prescription and generates the same .res file you would build far more laboriously with a visual resource editor.
• Direct reliance on the resource compiler digests any processable resource, and frees your work from any limitations of visual resource editors.
  • This allows you to use more appropriate applications to pre-process output such as graphics. If you want to use a favorite PhotoShop plug-in to pull off a drop shadow, your image won't be mangled into a cobby 8-bit result.

The following techniques allow application developers to compile or re-compile resources with a single click.

Resource (.res) files should be routinely compiled into distributables for the following reasons:

1. To reduce the size of executable files and the time necessary to load executables.
   • A single embedded resource instance can be loaded into many runtime instances.
2. To gain the speed advantages of LoadFromResourceName.
   • Because LoadFromResourceName directly accesses memory, LoadFromResourceName is substantially faster than the I/O intensive LoadFromFile method.
3. To eliminate the need to distribute separate files containing resources.
   • Distribute one integrated file, instead of many.

Resource Compiler (.rc) files are built with generic text editors, and are simply text file prescriptions which declare on each line, the run time reference names and source files of resources to be compiled into a .res file.

Resource (.res) files are generated by the resource compiler, and ultimately are compiled into applications, components, or dynamic link libraries by your regular application compiler, which heeds linking instructions indicating the .res resources which thus are internalized into your project.

• For each resource file, keep source files such as bitmaps, the .rc file, batch files, and the generated .res file in a dedicated subdirectory of your project.
• Keep shortcuts to batch files in project toolbar directories installed to the Windows™ QuickLaunch™ toolbar while working on the principal project.
• After compiling the .res file from a shortcut, copy it to the project directory with a further shortcut running a batch file.

Two clicks generate the .res file (1/2) and copy it to the project directory (2/2).

To avoid undocumented problems (or rules), we use uppercase alpha-numeric resource and file names with underscore characters.

Each line of the .rc text file prescribes:

1. A unique resource name.
   • The code of your application eventually refers to the resource by this unique name.
   • Usual naming rules apply.
2. A user-defined category name.
   • The category name is ignored by the resource compiler, but visual resource editors may utilize this parameter for whatever purposes.
3. The original source file name.
   • The source file name must be placed in double quotes.
   • The file must be located in the same directory as the .rc prescription, unless you are willing to express complete paths.

In the following example .rc prescription statement,

1. MT_FIRST declares the unique run time resource name.
2. UPCBMP24 declares an irrelevant, user-definable category name.
3. "MT_FIRST.BMP" is the source file.

Because our source file is identified by the resource name, we can simply copy source file names into the .rc prescription.

EXAMPLE .RC PRESCRIPTION STATEMENT

MT_FIRST UPCBMP24 "MT_FIRST.BMP"

To quickly build a prescription, copy a template block into enough lines for the .rc file you need to build. You require 1 line per resource.

EXAMPLE REPLACEMENT TOKEN STATEMENTS (10 ONLY)

UPCBMP24 "zzzzz.BMP" UPCBMP24 "zzzzz.BMP" UPCBMP24 "zzzzz.BMP" UPCBMP24 "zzzzz.BMP" UPCBMP24 "zzzzz.BMP" UPCBMP24 "zzzzz.BMP" UPCBMP24 "zzzzz.BMP" UPCBMP24 "zzzzz.BMP" UPCBMP24 "zzzzz.BMP" UPCBMP24 "zzzzz.BMP"

Now open Windows Explorer to your source directory so that you can select file names to paste into your .rc prescription. Because our source files are identified by the intended run time resource names, we can quickly build each line of the .rc prescription file by,

1. Copying the file identifier into the zzzzz replacement token.
2. Pressing the HOME key.
3. Pasting the file identifier again at the beginning of each line.

EXAMPLE AISUPC.RC FILE CONTENT

AIS2005_045X163_LPCROP UPCBMP24 "AIS2005_045X163_LPCROP.BMP" GLYPH_CLOSURE UPCBMP24 "GLYPH_Closure.BMP" GLYPH_DEFAULTDROPDOWN4 UPCBMP24 "GLYPH_DefaultDropDown4.BMP" GLYPH_SCROLLLEFT UPCBMP24 "GLYPH_ScrollLeft.BMP" GLYPH_SCROLLRIGHT UPCBMP24 "GLYPH_ScrollRight.BMP" MT_ADD UPCBMP24 "MT_ADD.BMP" MT_CLONE UPCBMP24 "MT_CLONE.BMP" MT_CONFIRMCANCEL UPCBMP24 "MT_ConfirmCANCEL.BMP" MT_CONFIRMDELETE UPCBMP24 "MT_ConfirmDELETE.BMP" MT_CONFIRMREFRESH UPCBMP24 "MT_ConfirmREFRESH.BMP" MT_FIND UPCBMP24 "MT_FIND.BMP" MT_FINDSQL UPCBMP24 "MT_FINDSQL.BMP" MT_FIRST UPCBMP24 "MT_FIRST.BMP" MT_HELP UPCBMP24 "MT_HELP.BMP" MT_LAST UPCBMP24 "MT_LAST.BMP" MT_NEXT UPCBMP24 "MT_NEXT.BMP" MT_OKPOST UPCBMP24 "MT_OKPOST.BMP" MT_PRIOR UPCBMP24 "MT_PRIOR.BMP" MT_RECONNECT UPCBMP24 "MT_RECONNECT.BMP" MT_REDO UPCBMP24 "MT_REDO.BMP" MT_RESTORETOORIGINAL UPCBMP24 "MT_RESTOREToOriginal.BMP" MT_TENTATIVEACCEPT UPCBMP24 "MT_TentativeACCEPT.BMP" MT_UNDO UPCBMP24 "MT_UNDO.BMP" SIZING_CLOSURE UPCBMP24 "Sizing_Closure.BMP" SIZING_HEIGHTMAXIMIZE UPCBMP24 "Sizing_HeightMaximize.BMP" SIZING_HEIGHTMINIMIZE UPCBMP24 "Sizing_HeightMinimize.BMP" SIZING_HEIGHTNORMALIZE UPCBMP24 "Sizing_HeightNormalize.BMP" SIZING_WIDTHANDHEIGHTMAXIMIZE UPCBMP24 "Sizing_WidthAndHeightMaximize.BMP" SIZING_WIDTHANDHEIGHTMINIMIZE UPCBMP24 "Sizing_WidthAndHeightMinimize.BMP" SIZING_WIDTHANDHEIGHTNORMALIZE UPCBMP24 "Sizing_WidthAndHeightNormalize.BMP" SIZING_WIDTHMAXIMIZE UPCBMP24 "Sizing_WidthMaximize.BMP" SIZING_WIDTHMINIMIZE UPCBMP24 "Sizing_WidthMinimize.BMP" SIZING_WIDTHNORMALIZE UPCBMP24 "Sizing_WidthNormalize.BMP"

Here, we use an AISUPC.BAT batch file to run the Borland RC Compiler, BRCC32.EXE, with the switch -r, passing AISUPC.RC as the .rc file argument.

• The -r switch and AISUPC.RC arguments automatically name the output, AISUPC.RES.
• Keep the batch file in your dedicated resource subdirectory, and invoke the batch file with a shortcut.

EXAMPLE AISUPC.BAT COMPILER FILE CONTENT

BRCC32 -r AISUPC.RC

• Compiling overwrites the previous .res file.
• Compile time errors simply result in no .res file or overwrite.
  • The author of the .rc file is responsible for the integrity of the prescription.
  • Possible errors are rudimentary and obvious, including duplicate resource names or missing source files.
  • Should a compile fail, this will be evident in a lacking last modified timestamp of the .res file.
    • The error should be obvious in the .rc prescription or environment (available source files).

Because the output .res file lands in the same directory, now we will want to copy the .res file to destination directories which may compile it into executables. This process too can be automated into a single click. A batch file invoked by another shortcut copies our .res output file to destination directories:

AISUPC_COPY_RES_TO_DESTINATION.BAT

copy AISUPC.RES c:\MyProjectDirectory\AISUPC.RES

• Whenever we need to include further content or otherwise modify our resource file, we revise our .rc prescription.
• To re-compile our resource file, we click our AISUPC.BAT shortcut.
• To copy output to destination directories, we click our AISUPC_COPY_RES_TO_DESTINATION shortcut.
  • Why do we perform the copy from a second batch file and shortcut? Because if the copy were integrated with the compile instruction (not having any power to wait for the compile to be completed), the copy could be initiated while output is still compiling.

Now we can use our resource file.

Linking causes the .res file to be built into your application, component or DLL during regular project compiles.

To link your .res file into a Delphi project, place a $R ("Resource") compiler directive and resource filename statement under the implementation keyword of the bottom-most unit referring to the resources. If UnitC uses UnitB which uses UnitA, and if all of these units might rely on any of the embedded resources, link to the .res file from UnitA.

EXAMPLE RESOURCE COMPILER DIRECTIVE

// IN UNIT A *ONLY*... implementation {$R AISUPC.RES}

One way to bundle compiled resources with distributables is to compile your resource file into a DLL. To build compiled resources into a Delphi DLL, all you have to do is add the $R directive to the project skeleton generated by the IDE:

1. Click File->New->Other->DLL.
2. Add a resource directive statement to the generated skeleton project.
3. Save the DLL project to your resource compiling directory.
4. Compile.
5. Copy the DLL to your application directory, and bundle it with your distributable.

DELPHI EXAMPLE — A COMPLETE RESOURCE DLL

library UPC_IMAGES; uses SysUtils, Classes; {$R *.res} {$R UPCDEMO.RES} // YOU ONLY NEED TO ADD THIS LINE. begin end.

The equivalent C++ Builder™ DLL wizard generates all of the following code but the necessary #pragma resource statement:

C++ EXAMPLE — A COMPLETE RESOURCE DLL

#include <vcl.h> #include <windows.h> #pragma hdrstop #pragma argsused #pragma resource "UPCDEMO.RES" // YOU ONLY NEED TO ADD THIS LINE. int WINAPI DllEntryPoint(HINSTANCE hinst, unsigned long reason, void* lpReserved) { return 1; }

We must call LoadFromResourceName() to assign resources to Delphi and C++Builder objects.

The following examples assign a MT_CLONE image resource to the Glyph property of MySpeedbutton:

DELPHI EXAMPLE

MySpeedbutton.Glyph.LoadFromResourceName(HInstance, 'MT_CLONE');

C++ EXAMPLE

MySpeedbutton->Glyph->LoadFromResourceName(((unsigned int)HInstance), "MT_CLONE");

To load images from DLLs, we need to declare a THandle (Delphi) or HANDLE (C++):

DELPHI EXAMPLE

HImages : THandle; // DECLARED IN INTERFACE. procedure TForm1.FormCreate(Sender: TObject); begin HImages := LoadLibrary('UPC_IMAGES.dll'); end; procedure TForm1.MyMethod; var TEMP_Glyph : TBitmap; begin TEMP_Glyph.LoadFromResourceName(HImages, 'MT_CLONE'); end;

C++ EXAMPLE

HANDLE HImages; // DECLARED IN HEADER. void __fastcall TForm1 :: FormCreate(System :: TObject * Sender) { HImages = LoadLibrary("UPC_IMAGES_PROJ.dll"); } void __fastcall TForm1 :: MyMethod(void) { Graphics :: TBitmap * TEMPGlyph->LoadFromResourceName(((unsigned int)HImages), "MT_CLONE"); }

The Delphi and C++Builder development environments allow developers to add RC files to projects. In our experience however, this feature does not necessarily link the .res file to the appropriate unit; nor is it useful to recompile resources every time the project is compiled.

Why are developers embedding resources into DLLs, instead of directly into their executables?

C++ debug sessions show that there are problems casting HInstance to an unsigned integer. The compiler asks for an unsigned integer, but the value of the necessary HANDLE is incorrectly cast to unsigned int:

LONG EXISTING C++Builder AND DELPHI BUG?

HANDLE GHInstanceInt = ((unsigned int)HInstance); // GHinstanceInt = 4194304; HInstance = 004000000.

Calvert provides excellent teaching of .res and .rc topics in his "Delphi Unleashed" series.