9 Program resources

Resources, in the new sense of the word is data that is required by an application but cannot be expressed easily as program-code. Examples are image-files, help-files, and other files using non-Prolog syntax. Such files are declared by defining clauses for the predicate resource/3:

resource(?Name, ?Class, ?PathSpec)

Define the file specified by PathSpec to contain data for the resource named Name of resource-class Class.

Name refers to the logical name of the resource, which is interpreted locally for a Prolog module. Declarations in the module user are visible as defaults from all other modules. Class defines the type of object to be expected in the file. Right now, they provide an additional name-space for resources. PathSpec is a file specification as acceptable to absolute_file_name/[2,3].

Resources can be handled both from Prolog as for XPCE. From Prolog, this is achieved using open_resource/3:

open_resource(+Name, ?Class, -Stream)

Opens the resource specified by Name and Class. If the latter is a variable, it will be unified to the class of the first resource found that has the specified Name. If successful, Stream becomes a handle to a binary input stream, providing access to the content of the resource.

The predicate open_resource/3 first checks resource/3. If successful it will open the returned resource source-file. Otherwise it will look in the programs resource database. When creating a saved-state, the system saves the resource contents into the resource archive, but does not save the resource clauses.

This way, the development environment uses the files (and modifications to the resource/3 declarations and/or files containing resource info thus immediately affect the running environment, while the runtime system quickly accesses the system resources.

From XPCE, resources are accessed using the class resource, which is located next to file below the common data-representation class source_sink. Many of the methods that require data accept instances of source_sink, making resources a suitable candidate.

Below is the preferred way to specify and use an icon.

resource(my_icon,       image,  image('my_icon.xpm')).

        ...,
        send(Button, label, image(resource(my_icon))),
        ...,

The directive pce_image_directory/1 adds the provided directory to the search-path for images (represented in the class-variable image.path), as well as to the image/1 definition of file_search_path/2.

Please note that MS-Windows formatted image files can currently not be loaded through resource objects. The Windows API only provides functions to extract these objects from a single file, or nested as Windows resources in a .dll or .exe file.

Right now, it is advised to translate the images into .xpm format using the following simple command:

?- send(image('myicon.ico'), save, 'myicon,xpm', xpm).

This transformation is complete as the .XPM image format covers all aspects of the Microsoft image formats. For further details on image formats and manipulation, see section 10.10.