#RESOURCE metastatement

Purpose | Embed a PowerBASIC Resource data into a compiled EXE or DLL.

Syntax

#RESOURCE BITMAP, ResID, "filespec.BMP"

#RESOURCE ICON, ResID, "filespec.ICO"

#RESOURCE MANIFEST, 1, "filespec.XML"

#RESOURCE RCDATA, ResID, "filespec.DAT"

#RESOURCE STRING, ResID, "YourWideText"$$ [,LangID]

#RESOURCE TYPELIB, 1, "filespec.TLB"

#RESOURCE WAVE, ResID, "filespec.WAV"

#RESOURCE VERSIONINFO <<block>>

#RESOURCE RES, "filespec.RES"

#RESOURCE PBR, "filespec.PBR"

Remarks

This metastatement is used to include PowerBASIC Resource data into your program or DLL. Resource data may consist of bitmaps, icons, strings, COM Type Libraries, Version Information, and more. You can even embed custom binary data for your personal, specialized needs.

Resource data can be a very valuable tool. While you can certainly load bitmaps and icons from separate files, wouldn't it be better to just embed them in your application? When you need the bitmap, it's always right there for your use! You don't have to deal with scads of files. Now it's all at your fingertips.

The parameter ResID is a unique identifier which you create to reference this item. It can be a numeric or an alphanumeric literal. If numeric, it must be an integral value from 0 to 65535. If alphanumeric, it must begin with a letter, and consist of letters and numbers. Alphanumeric labels are not case sensitive. The filespec parameter must always be expressed as a string literal which tells the location of the resource data.

If a resource file's path is not specified, then the compiler will look in the default directory.

With most programming languages, creation and embedding of resource data is a cumbersome process. First you create a resource script (an .RC file) with a text editor. Then you save the .RC file. Now, compile the .RC file with a resource compiler to get a .RES file. Next, you convert it to a linkable file using Microsoft's CVTRES.EXE or another converter program like PBRES.EXE. Finally, you link it into your .EXE or .DLL with a compiler or linker program. What if you find you need to make a tiny change? Do it all over again, from the beginning. Even older versions of PowerBASIC suffered from this problem.

Isn't there a better way? Yes, PowerBASIC now handles the entire process in a single line of code. Need an embedded bitmap?

#RESOURCE BITMAP, 123, "MyPicture.BMP"

PowerBASIC finds your bitmap in the file MyPicture.BMP and embeds it in your executable. When you need to use it, you can reference it by the ID you chose for it (123). The ID can be an integral numeric value or a text name of your choice. So, to display the bitmap on a graphic window, it's as simple as:

GRAPHIC RENDER "#123", (100,100)-(160,140)

String Resources

The String resource contains string data which is always created and stored as Wide Unicode characters. It is retrieved at run-time with the RESOURCE$ function. Due to the manner in which Windows stores string resources in a string table, the ResID must be numeric.

The string data must be from 1 to 127 characters in length, and may not contain any embedded nuls ( CHR$(0)). The string data may be specified as a quoted wide string literal ("MyText"$$), or as a wide string literal expression. A string literal expression can be constructed from combinations of wide string equates or wide quoted string literals, the CHR$ function, SPACE$ function, and the STRING$ function when used with numeric parameters.

VersionInfo Resources

The VersionInfo resource contains information about the file, such as its version number, its intended operating system, its original file name, and much more. This resource is intended to be used with the Version Information API functions, so that Windows Explorer, and other programs, can display the relevant information about your EXE. The VersionInfo resource cannot be embedded in a Static Link Library (SLL).

The VersionInfo resource is unique in that it requires several #RESOURCE metastatements which are interpreted as a complete block. They must be placed consecutively in the correct sequence in order be processed correctly.

1. | The block begins with the VERSIONINFO metastatement which marks the beginning of the version block.

#RESOURCE VERSIONINFO

2. | Next, you may choose to add one or more of the numeric version metastatements which embed numeric values.

#RESOURCE FILEFLAGS FlagValue&

#RESOURCE FILEVERSION HiNum1&, LoNum1&, HiNum2&, LoNum2&

#RESOURCE PRODUCTVERSION HiNum1&, LoNum1&, HiNum2&, LoNum2&

3. | Next, the mandatory STRINGINFO metastatement is added, to identify the Language ID and CharSet to be used. Each of these parameters must be passed as a 4-digit HEX value in a string literal. The parameter must not contain the "&H" prefix used with numeric hex numbers.

#RESOURCE STRINGINFO "LangID", "CharSet"

4. | Finally, you will add one or more of the string version metastatements, to provide extensive information about the file. The first string literal parameter chooses one of the following predefined names. The second string literal parameter adds your personal choice of information about the file.

#RESOURCE VERSION$ "Comments", "Additional info"

#RESOURCE VERSION$ "CompanyName", "PowerBASIC Inc."

#RESOURCE VERSION$ "FileDescription", "Presented to users"

#RESOURCE VERSION$ "FileVersion", "Readable VerNum 1.02"

#RESOURCE VERSION$ "InternalName", "Private"

#RESOURCE VERSION$ "LegalCopyright", "Copyright 2012 PB Inc"

#RESOURCE VERSION$ "LegalTrademarks", "xx is a..."

#RESOURCE VERSION$ "OriginalFilename", "Original name w/o path"

#RESOURCE VERSION$ "PrivateBuild", "Private info"

#RESOURCE VERSION$ "ProductName", "Product distributed with"

#RESOURCE VERSION$ "ProductVersion", "Version distributed with"

#RESOURCE VERSION$ "SpecialBuild", "Special info"

FILEFLAGS
FlagValue& | Description
%VS_FF_DEBUG | File contains debugging information or is compiled with debugging features enabled.
%VS_FF_PATCHED | File has been modified and is not identical to the original shipping file of the same version number.
%VS_FF_PRERELEASE | File is a development version, not a commercially released product.
%VS_FF_PRIVATEBUILD | File was not built using standard release procedures. If this value is given, you must include a PrivateBuild string item.
%VS_FF_SPECIALBUILD | File was built by the original company using standard release procedures, but is a variation of the standard file of the same version number. If this value is given, you must include a SpecialBuild string item.

STRINGINFO
LangID | Language | LangID | Language
&H0401 | Arabic | &H0415 | Polish
&H0402 | Bulgarian | &H0416 | Portuguese (Brazil)
&H0403 | Catalan | &H0417 | Rhaeto-Romanic
&H0404 | Traditional Chinese | &H0418 | Romanian
&H0405 | Czech | &H0419 | Russian
&H0406 | Danish | &H041A | Croato-Serbian (Latin)
&H0407 | German | &H041B | Slovak
&H0408 | Greek | &H041C | Albanian
&H0409 | U.S. English | &H041D | Swedish
&H040A | Castilian Spanish | &H041E | Thai
&H040B | Finnish | &H041F | Turkish
&H040C | French | &H0420 | Urdu
&H040D | Hebrew | &H0421 | Bahasa
&H040E | Hungarian | &H0804 | Simplified Chinese
&H040F | Icelandic | &H0807 | Swiss German
&H0410 | Italian | &H0809 | U.K. English
&H0411 | Japanese | &H080A | Spanish (Mexico)
&H0412 | Korean | &H080C | Belgian French
&H0413 | Dutch | &H0816 | Portuguese (Portugal)
&H0414 | Norwegian - Bokmal | &H081A | Serbo-Croatian (Cyrillic)
&H0810 | Swiss Italian | &H0C0C | Canadian French
&H0813 | Belgian Dutch | &H100C | Swiss French
&H0814 | Norwegian - Nynorsk |  |

STRINGINFO
CharSet | Character Set
&H0000 | 7-bit ASCII
&H03A4 | Japan (Shift - JIS X-0208)
&H03B5 | Korea (Shift - KSC 5601)
&H03B6 | Taiwan (Big5)
&H04B0 | Unicode
&H04E2 | Latin-2 (Eastern European)
&H04E3 | Cyrillic
&H04E4 | Multilingual
&H04E5 | Greek
&H04E6 | Turkish
&H04E7 | Hebrew
&H04E8 | Arabic

RES/PBR Resources

The second group of syntax examples show how you can embed resources which have been pre-compiled used a resource compiler. Standard resource compilers output a binary resource with a .RES extension. PowerBASIC will embed this resource just as it is given in the file. This form will always be supported to support resource forms which are typically not needed for most PowerBASIC programs, or which usually require the use of a resource editor.

The final example, using a .PBR file, will only be supported for a limited period of time. This is the form created by the PowerBASIC PBRES utility in older versions of the compiler. It is recommended that you change to the .RES version soon, as it is more efficient, and needs less effort from the programmer. It should be noted that prior versions of PowerBASIC allowed the descriptor "PBR" to be omitted. While this option will be supported for a limited period of time, we recommend that you always insert "PBR" for clarity.

Restrictions | Windows 95, 98, and ME offer limited support for resources. When compiling on one of these versions of Windows, only #RESOURCE RES and #RESOURCE PBR may be used. Other forms of the #RESOURCE metastatement are not functional. RES and PBR resources cannot be mixed with any other resources. Once you add a PBR or RES resource, you cannot add any other #RESOURCE metastatements in your program.
See also | RESOURCE$, Resource Files
Example | #RESOURCE ICON, MySpecialIcon, "Icon.ICO"