Resources

version 2004 (Modified)

A resource is data of any kind stored in a defined format in a separate file or in the resource fork of a Macintosh file. Resources typically include data such as strings, pictures, icons and so on. As a matter of fact, you can create and use your own kinds of resources and store whatever data you want into them.

Originally, on Macintosh, data and resources were stored in the same file, made of a data fork and a resource fork. The data fork of a Macintosh file is the equivalent of a file on Windows and UNIX. The resource fork of a Macintosh file contains the Macintosh-based resources of the file and has no direct equivalent on Windows or UNIX.

Although this feature is still supported by 4th Dimension, now under Mac OS as well as under Windows, the resources are stored in a separate file (in the data fork on Mac OS). This principle is managed transparently by 4th Dimension and allows direct exchange of files between the different platforms without conversion. For example, when you create a new database, 4th Dimension creates a file with the suffix .rsr to store the structure file resources and a file with the suffix .4dr to store the data file resources.

Resource file management commands (Create resource file and Open resource file) can work directly within the data fork for a better cross-platform compatibility.

No matter what platform you are using, a 4D database structure file is not the only type of file with resources. The 4D application itself uses resources, stored in a file suffixed ".RSR".

4D Plug-ins like 4D Write can also use resources.

It is also the case for the data file of a 4D database. For example, you can lock a data file for exclusive use with a particular structure file. This operation is done in the application Preferences dialog box and results with the creation of the same WEDD ("WEDD" for "wedding") resource in both the structure and data resource files.

In addition to the resource files provided by 4D, you can create and use your own resource files using the 4D commands Create resource file and Open resource file. These two commands return a resource file reference number that uniquely identifies the open resource file. The resource file reference number is the equivalent of the document reference number for regular files returned by System documents commands such as Open document. All the 4D Resources commands optionally expect a resource file reference number. After you have finished with a resource file, remember to close it using the command CLOSE RESOURCE FILE.

When you work with a 4D database, you can either work with all the currently open resource files or with a specific resource file.

Multiple resource files can be open at the same time. This is always the case from within a 4D database. The following files are open:

• On Macintosh, the System resource file.

• On Windows, the ASIPORT.RSR file (it contains part of the Macintosh system resources).

• The 4D application resource file.

• The database structure resource file.

• The database data file resource file may be optionally open.

• Finally, you can open your own resource file using the command Open resource file.

This list of open resource files is called the resource files chain. You can search for a given resource in two ways:

• If you pass a resource file reference number to a resource 4D command, the resource is searched for in that resource file only.

• If you do not pass a resource file reference number to a 4D Resource command, the resource is searched for in all currently open resource files, starting with the most recently opened file and ending with the first opened file. The resource files chain is thus browsed in the reverse order of opening—the last opened resource file is examined first.

Here is an example:

   $vhResFile:=Create resource file("Just_a_file")
   If (OK=1)
      ARRAY STRING(63;asSomeStrings;0)
      STRING LIST TO ARRAY(8;asSomeStrings;$vhResFile)
      ALERT("The size of the array is "+String(Size of array(asSomeStrings))+" element(s).")
      STRING LIST TO ARRAY(8;asSomeStrings)
      ALERT("The size of the array is "+String(Size of array(asSomeStrings))+" element(s).")
      CLOSE RESOURCE FILE($vhResFile)
   End if 

At execution of this method, the first alert will display "The size of the array is 0 element(s)" and the second alert will display "The size of the array is 634 element(s)".

The first call:

      STRING LIST TO ARRAY(8;asSomeStrings;$vhResFile)

looks for the resource "STR#" ID=8 only in the resource file just created and open by the call to Create resource file. Because the file is new and therefore empty, the resource is not found.

The second call:

      STRING LIST TO ARRAY(8;asSomeStrings)

looks for the resource "STR#" ID=8 in all the currently open resource files. Since the file just created and opened (by the call to Create resource file) does not contain that resource, STRING LIST TO ARRAY then looks for the resource in the database structure resource file. This resource file does not contain that resource either, so STRING LIST TO ARRAY then examines the 4D resource file, locates the resource in this file, and populates the array with it.

Conclusion: When working with resource files, if you want to access a specific file, make sure to pass the resource file reference number to a 4D Resources command. Otherwise, the command assumes that you do not care which file is the source of the resources.

A resource file is highly structured. In addition to the data of each resource, it contains a header and a map that fully describe its contents.

Resources are classified by types. A resource type is always denoted by a 4-character string. A resource type is both case sensitive and diacritical sensitive. For example, the resource types "Hi_!", "hi_!" and "HI_!" are all different.

Important: Resource types with lowercase characters are reserved for use by the Operating System. Avoid designating your own resource types with lowercase characters.

The following is a list of some commonly-used resource types:

• A resource of type "STR#" is a resource containing a list of Pascal strings. This resource is called a string list resource.

• A resource of type "STR " (note the space as fourth character) is a resource containing an individual Pascal string. This resource is called a string resource.

• A resource of type "TEXT" is a resource containing a text string without length. This resource is called a text resource.

• A resource of type "PICT" is a resource containing a Macintosh-based QuickDraw picture that you can use and display on both Macintosh and Windows with 4D. This resource is called a picture resource.

• A resource of type "cicn" is a resource containing a Macintosh-based color icon that you can use and display with 4D on both Macintosh and Windows. This resource is called a color icon resource. For example, a "cicn" resource can be associated with an item of a hierarchical list, using the command SET LIST ITEM PROPERTIES.

In addition to the standard resource types, you can create you own types. For example, you can decide to work with resources of type "MTYP" (for "My Type").

To obtain the list of resource types currently present in all open resource files or in a particular resource file, use the command RESOURCE TYPE LIST. Then, to obtain the list of a specified type of resource present in all open resource files or in a particular resource file, use the command RESOURCE LIST. This command returns the IDs and Names (see next section) of all resources of a given type.

WARNING: Many applications rely on the resource type for working with its contents. For example, while accessing a "STR#" resource, applications expect to find a string list in the resource. Do NOT store inconsistent data in resources of standard types; this may lead to system errors in your 4D application or in other applications.

WARNING: A resource is a highly structured file—do NOT access the file with commands other than Resources commands. Note that nothing prevents you from passing a resource file reference number (formally a 4D time expression like the document reference number) to a command such as SEND PACKET. However, if you do so, you will probably damage the resource file.

WARNING: A resource file can contain about up to 2,700 individual resources. Do NOT attempt to exceed this limit. Note that nothing prevents you from doing so; however, this will damage the resource file and make it unusable.

A resource has a resource name. A resource name can be up to 255 characters, and is diacritical sensitive but not case sensitive. Resource names are useful for describing a resource, but you access a resource using its type and ID number. Resource names are not unique; several resources can have the same name.

A resource has a resource ID number (for short, resource ID or ID). This ID is unique within a resource type and a resource file. For example:

• One resource file can contain a resource "ABCD" ID=1 and a resource "EFGH" ID=1.

• Two resource files can contain a resource with the same type and ID.

When you access a resource using a 4D command, you indicate its type and ID. If you do not specify the resource file in which you are looking for this resource, the command returns the occurrence of the resource found in the first examined resource file. Remember that resource files are examined in the reverse order in which they have been opened.

The range of a resource ID is -32,768..32,767.

Important: Use the range 15,000..32,767 for your own resources. Do NOT use negative resource IDs; these are reserved for use by the Operating System. Do NOT use resource IDs in the range 0..14,999; this range is reserved for use by 4th Dimension.

To obtain the IDs and names of a given resource type, use the command RESOURCE LIST.

To obtain the name of an individual resource, use the command Get resource name.

To change the name of and individual resource, use the command SET RESOURCE NAME.

To obtain the current (actual) number for a resource installed by a 4D component, use the command Get component resource ID.

As each 4D command optionally accepts a resource file reference number, you can easily deal with resources having the same type and ID in two different resource files. The following example copies all the "PICT" resources from one resource file to another:

      ` Open an existing resource file
   $vhResFileA:=Open resource file("")
   If (OK=1)
         ` Create a new resource file
      $vhResFileB:=Create resource file("")
      If (OK=1)
            ` Get the ID and Name lists of all the resources of type "PICT"
            ` located in the resource file A
         RESOURCE LIST("PICT";$aiResID;$asResName;$vhResFileA)
            ` For each resource:
         For($vlElem;1;Size of array($aiResID))
            $viResID:=$aiResID{$vlElem}
               ` Load the resource from file A
            GET RESOURCE ("PICT";$viResID;vxResData;$vhResFileA)
               ` If the resource could be loaded
            If (OK=1)
                  ` Add and write the resource into file B
               SET RESOURCE ("PICT";$viResID;vxResData;$vhResFileB)
                  ` If the resource could be added and written
               If (OK=1)
                     ` Copy also the name of the resource
                  SET RESOURCE NAME("PICT";$viResID;$asResName{$vlElem};$vhResFileB)
                     ` As well as its properties (see Resource Properties below)
                  $vlResAttr:=Get resource properties("PICT";$viResID;$vhResFileA)
                  SET RESOURCE PROPERTIES("PICT";$viResID;$vlResAttr;$vhResFileB)
               Else
                  ALERT("The resource PICT ID="+String($viResID)+" could not be added.")
               End if
            Else
               ALERT("The resource PICT ID="+String($viResID)+" could not be loaded.")
            End if
         End for
         CLOSE RESOURCE FILE($vhResFileB)
      End if
      CLOSE RESOURCE FILE($vhResFileA)
   End if

Besides its type, name and ID, a resource has additional properties (also called attributes). For example, a resource may or may not be purged. This attribute tells the Operating System whether or not a loaded resource can be purged from memory when free memory is required for allocating another object. As shown in the previous example, when creating or copying a resource, it can be important to not only copy the resource, but also its name and properties. For a complete explanation of resource properties, see the description of the commands Get resource properties and SET RESOURCE PROPERTIES.

To load a resource of any type into memory, call GET RESOURCE, which returns the contents of the resource in a BLOB.

To add or rewrite a resource on disk, call SET RESOURCE, which sets the contents of the resource to the contents of the BLOB you pass.

To delete an existing resource, use the command DELETE RESOURCE.

To simplify handling of standard resource types, 4D provides additional built-in commands that save you from having to parse a BLOB in order to extract the resource data:

• STRING LIST TO ARRAY populates a String or Text array with the strings contained in a string list resource.

• ARRAY TO STRING LIST creates or rewrites a string list resource with the elements of a String or Text array.

• Get indexed string returns a particular string from a string list resource.

• Get string resource returns the string from a string resource.

• SET STRING RESOURCE creates or rewrites a string resource.

• Get text resource returns the text of a text resource.

• SET TEXT RESOURCE creates or rewrites a text resource.

• GET PICTURE RESOURCE returns the picture of a picture resource.

• SET PICTURE RESOURCE creates or rewrites a picture resource.

• GET ICON RESOURCE returns a color icon resource as a picture.

Note that these commands are provided to simplify manipulation of standard resource types; however, they do not prevent you from using GET RESOURCE and SET RESOURCE using BLOBs. For example, this line of code:

   ALERT(Get text resource(20000))

is the shorter equivalent of:

   GET RESOURCE("TEXT";20000;vxData)
   If (OK=1)
      $vlOffset:=0
      ALERT(BLOB to text(vxData;Text without length;$vlOffset;BLOB Size(vxData)))
   End if

In addition to the Resources commands described in this chapter, there are other 4D commands that work with resources and resource files:

• On Macintosh, DOCUMENT TO BLOB and BLOB TO DOCUMENT can load and write the whole resource fork of a Macintosh file.

• Using the commands SET LIST ITEM PROPERTIES and SET LIST PROPERTIES, you can associate picture or color icon resources to the items of a list or use color icon resources as nodes of a list.

• The PLAY command plays "snd " resources on both Macintosh and Windows.

• The SET CURSOR command changes the appearance of the mouse using "CURS" resources.

BLOB Commands, Get component resource ID, OS Resource Manager Errors, Resources and 4D Insider: an Example.