#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.

The parameter ResID is a unique identifier which you create to reference this item.  It can be a number or an alphanumeric label.  If a number, it must be an integral value from 0 to 65535.  If a label, 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.

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)

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 offer 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.

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 2011 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"

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"