Resources

version 11 (Modified)

The management of resources has been modified in 4D beginning with version 11. In conformity with the directions specified by Apple and implemented in the most recent Mac OS versions, the concept of resources in the strictest sense (see definition below) is now obsolete and will be abandoned progressively. New mechanisms have been implemented to support the needs that were previously met by resources: XLIFF files for the translation of character strings, .png picture files, etc. In fact, resource files will be replaced in favor of standard type files. 4D supports this evolution and, beginning with version 11, provides new tools for the management of database translations, while maintaining compatibility with existing systems.

To maintain compatibility and in order to permit the progressive adaptation of existing applications, the former resource mechanisms will containue to work in 4D v11, with just a few notable differences:

• When present, resource files are still supported by 4D and the principle of the"string of resource files" (successive opening of several resource files) remains valid. The "string of resource files" includes more particularly the .rsr or .4dr files of converted databases (opened automatically) and the custom resource files opened using the commands of this theme.

• However, for reasons related to the evolution of the internal architecture, it is no longer possible to access the resources of the 4D application nor those of the system directly, whether via the commands of this theme or using dynamic references. Certain developers make use of 4D internal resources for their interfaces (for example, resources containing the names of the months or those of the language commands). This practice is now strictly forbidden. In most cases, it is possible to use other means instead of 4D internal resources (constants, language commands, and so on). In order to limit the impact of this modification on existing databases, a substitution system has been implemented, based on the externalization of the resources that are most frequently used. It is nevertheless strongly recommended to change converted databases and to remove any calls to 4D internal resources they may contain.

• Starting with version 11, databases created by 4D will no longer contain .RSR (structure resources) and .4DR (data resources) files by default.

In 4D v11, the notion of "resources" must now be understood in the broader sense as "files that are necessary for the translation of application interfaces." The new architectue of resources is based on a folder, named Resources, that must be located next to the database structure file (.4db or .4dc). It is not created by default; you will have to create it if your database uses resources. In this folder, you need to put all the files that are necessary for the translation or customizing of the application interfaces (picture files, text files, XLIFF files, and so on).

It can also contain any "former generation" resource files of the database (.rsr files). Be careful, these files are not automatically included in the string of resources; they must be opened using standard 4D resource handling commands. 4D uses automatic mechanisms when working with the contents of this folder, in particular for the management of XLIFF files (this point is covered in the Design Reference manual). Two commands of the "Resources" theme can be used to take advantage of this architecture (see the Get indexed string and STRING LIST TO ARRAY commands).

Compatibility Note: The traditional resource management principles are progressively being abandoned in 4D (see previous paragraph). For new databases, it is now recommended to rely on XLIFF architecture or the use of standard files.

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 4D, 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 4D and allows direct exchange of files between the different platforms without conversion.

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

In databases created with a version of 4D prior to v11, 4D automatically created a .rsr file in order to store the structure file resources and a .4dr file for the data file resources.

The 4D application itself uses resources, stored in a file suffixed ".RSR". 4D Plug-ins like 4D Write can also use resources.

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 (if any).

• The database data file resource file (if any) 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.

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 4D.

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.

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;UTF8 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.