Declaring resources - The ARC file Foundation

When an Xbase++ application requires resources such as Icons, Bitmaps, localized strings and so on, they are declared in an ARC file. This is a plain text file which is compiled to a binary resource file (RES file) by the resource compiler ARC.EXE.

A resource will be uniquely identified by the resource type, the resource identifier and the language identifier.

The resulting binary resource file (.RES) must be linked to the program, either to the .EXE file or to a .DLL which used by the .EXE file. The program can make use of the resources depending on the resource type.

Statement

A resource statement consists of the Resource-Type keyword as listed above, an identifier to find the resource when the program runs, the equal sign and the value of the resource. The resource type can be omitted if the next resources are of the same type.

CHARACTER 
   100 = "Nice feature!" 
   101 = "Indeed." 
ICON 
   1   = "stop.ico" 
   7   = "go.ico" 

Identifiers

A resource identifier can either be a numeric value in the range of 1 to 16384 - typically provided by #define constants - or a name. Using named resources has two advantages: First, maintaining #define constants is not required any more and second, more resources can be stored in the same file for this resource type. Unless otherwise documented, the LoadResource()function must be used in conjunction with an XbpBitmap or XbpIcon object for loading named image resources. It is recommended to always use upper-case letters for named resources even so named resource identifiers are case-sensitive.

USERDEF JPEG 
   MYIMAGE = FILE "cool.jpeg" 

Data

The value part of the declaration can either be a string literal, or a FILEstatement. ICON, BITMAP and POINTER values are treated as file names by default, there is no difference when using FILE on these resource types. Other resource types such as CHARACTER interprete the FILE statement as a file which data is to be loaded. The file will be read, if the resource type is CHARACTER converted to Unicode, and stored as the resource data.

CHARACTER 1 = FILE "hello.txt" 

FONT

A FONT resource can be used to temporarily use a font or to create a .FON file which can be installed permanently. Supported font file types: .FNT.

LANGUAGE

Use the LANGUAGE statement to set the language identifier for the following resources. The statement has the form:

LANGUAGE = <string-id>| <primary>, <secondary> 

Language Identifiers:The <string-id> is a string literal consisting of language codes according to ISO 639-1, where the primary language can be followed by a sub-language identifier, separated by a hyphen. If the <primary>, <secondary> notation is used, the numeric equivalents of the current operating system must be used.

LANGUAGE = "es-ar"       // sets language Spanish, sub-language Argentinian 
LANGUAGE = 0x07, 0x04    // sets language to German, sub-language Luxembourg 
LANGUAGE = "de"          // equivalent for standard German 

The numeric values for <primary> and <secondary> defined for the operating system are listed in the winnt.h header file. This file is included in the Windows SDK.

// Extract from winnt.h 
#define LANG_GERMAN                 0x07 
#define SUBLANG_GERMAN_LUXEMBOURG   0x04  // German (Luxembourg) 

The default language identifier is "neutral", that means, the resources are valid for any language.

VERSION

The VERSION resource syntax differs from other types because an identifier must be a string literal. Version resource identifiers will be recognized by the operating system by their name, but other names might be used. There is only one version resource allowed per file (EXE or DLL).

The file and product version numbers will also be stored in a binary form. A dot can be used to separate the parts of the version numbers, the number of characters between the dots designate the highest possible number. It is important which version numbering system is choosen to cover all upcoming versions. Version numbers are important for the installation process. The following table shows how string version numbers transformed into numerical values:

USERDEF HTML 
            TITLE = "<title>This is the page title</title>" 

Samples for the declaration of resources:

* 
* TEST.ARC 
* 

/* Declaration of different 
   resource types 
*/ 

BITMAP     110 = "Logo.bmp"        // Bitmap 
ICON       120 = "Folder.ico"      // Icon 
POINTER    130 = "Arrow.ptr"       // Pointer 
CHARACTER  200 = "Question."       // String resource 

/* a version resource */ 
VERSION 
   "CompanyName"      = "Alaska Software" 
   "LegalCopyright"   = "Copyright © Alaska Software 1997-2008" 
   "ProductName"      = "Alaska Xbase++" 
   "ProductVersion"   = " 1.90.0331" 
   "FileDescription"  = "Xbase++ Development tool" 
   "FileVersion"      = " 1.90" 
   "OriginalFilename" = "Arc.exe" 

/* localize some resources */ 
LANGUAGE = "de" 

CHARACTER  200 = "Frage."    

* EOF 

Comments can be included in the ARC file (as in a PRG file) by using the characters /* and */ or a double slash for inline comments. In addition, the asterisk indicates a comment line when it is the first character in a line.

The OS/2 resource compiler RC.EXE requires resources to be declared in a different way . However, if ARC.EXE is invoked with the command line switch /rc, it translates an ARC file into a RC file that can be compiled by other resource compilers, like RC.EXE on the OS/2 platform, for example. This way, resource declarations can be made independently of the resource compiler.