DeskLib 2.90a:Resource.h


Contents


Introduction and Overview

This header declares functions for handling Resource files inside our application directory (spritefiles, for instance), and functions for dealing with Choices files (user options) which work out the correct location for such files when loading and saving options.


Functions


Resource_Initialise

void Resource_Initialise(const char *respath);

This initialises the resource manager, setting resource_pathname to "<respath$dir>.", eg. if you have set "appname$dir" to point to your application directory you should pass in "appname".

This tells DeskLib where to look for your resources by prepending resource_pathname to a given leafname to create a full resource pathname. This adds very little code size to your program, and makes it a lot easier to change the resource directory at a later time.

Note that after calling this function, calls to Resource_InitialiseAuto will no longer have any effect.


Resource_InitialisePath

void Resource_InitialisePath(const char *respath);

This initialises the resource manager, setting resource_pathname to "respath:", eg. if you have set "appname:" to point to the directory (or directories) where your sprite files, templates, etc are stored, you should pass in "appname".

This tells DeskLib where to look for your resources by prepending resource_pathname to a given leafname to create a full resource pathname. This adds very little code size to your program, and makes it a lot easier to change the location of resources at a later time.

Using a path has the advantage of being able to reference more than one directory, so you can have a language-specific directory and a default directory for resources, and this will enable DeskLib to load language-specific files first if they exist, and fall back to the default files if they don't.

Note that after calling this function, calls to Resource_InitialiseAuto will no longer have any effect.


Resource_InitialiseAuto

BOOL Resource_InitialiseAuto(void );

This function attempts to automatically set up resorce_pathname based on the task name passed to Event_Initialise. (If Event_Initialise hasn't been called, the function returns FALSE.)

The function attempts to use the following locations, in descending order of preference (where "AppName" is the task name): 1) AppNameRes path [*] 2) AppName path 3) AppName.Resources directory 4) AppName directory

If none of these are found, the function returns FALSE.

This function should only be called once, it it is called more than once there will be no effect and it will return FALSE. You can still explicitly alter resource_pathname using Resource_Initialise or Resource_InitialisePath.

[*] As per ResFind: http://www.gag.de/software/ResFind/


Resource_LoadSprites

void Resource_LoadSprites(void );

This loads the program's "Sprites" file from the resource path, ready for use. You should only call this after you have initialised the Resource system. After loading the file, resource_sprites will point to the sprite area containing the sprites.

To use these sprites for your templates, use Template_UseSpriteArea(resource_sprites); after calling this function and before creating your windows.

If there is a problem loading the file, the error is reported with Error_ReportFatal.


Resource_ChoicesInit

void Resource_ChoicesInit(const char *groupdir, const char *appname, BOOL multiple);

This initialises the Choices system, setting up the appropriate global variables. This must be called before you use Resource_ChoicesPath.

You set 'appname' to the name of the owning application (yours!). This will be used as the name of a single choices file if 'multiple' is choices_SINGLE, or as the name of a directory containing your choices files if 'multiple' is choices_MULTIPLE. You can still use choices_MULTIPLE if you are using a single file, if you want that file placed in a subdirectory. If 'appname' is NULL, the application name (as passed to Event_Initialise) is used.

If you want to use a parent directory (such as "WWW" or "MidiWays") for your choices, you can pass this in as 'groupdir'. If this is NULL or a zero-length string no group dir will be used.

This is based on the function given by Justin Fletcher in his Choices doc, though with additional functionality for grouping multiple choices files.


Resource_ChoicesPath

void Resource_ChoicesPath(char *pathname, const char *leafname, BOOL write);

You pass in the leafname of the choices file you want to access, and whether you are reading the file or writing it. It returns the correct filename in the buffer pointed to by 'pathname', based on the way you have set up the system with Resource_ChoicesInit. You should make sure that the buffer is large enough to hold the resulting pathname.

As per the Choices specification, when reading, a choices file is looked for first on the "Choices:" path and then inside the application directory, but when writing, the file should be written in "<Choices$Write>" if available, or inside the application if not.

If the Choices system is in use and you have configured multiple files for your choices then the leafname given here is used as the filename inside your application's Choices directory. If you have configured a single choices file, then the *application name* is used as the leafname of your file. If you have specified a group directory (such as "WWW"), this is used as a "parent" directory to locate the file or files.

If the Choices system cannot be used, then for a single file the leafname is the name of the file inside your application directory, and for multiple files it is the leafname of a file inside a "Choices" directory inside your application directory.

If the Choices system cannot be used, the group directory is not used whether it is set or not.

Examples (appname is "MyApp" and leafname is "!Config").

With no groupdir and choices_SINGLE: "Choices:MyApp", or "<MyApp$Dir>.!Config" if that fails.

With no groupdir and choices_MULTIPLE: "Choices:MyApp.!Config" or "<MyApp$Dir>.Choices.!Config"

With groupdir="WWW" and choices_SINGLE: "Choices:WWW.MyApp" or "<MyApp$Dir>.!Config"

With groupdir="WWW" and choices_MULTIPLE: "Choices:WWW.MyApp.!Config" or "<MyApp$Dir>.Choices.!Config"


Macros


choices_SINGLE

#define choices_SINGLE      FALSE

Used with Resource_ChoicesInit()


choices_MULTIPLE

#define choices_MULTIPLE    TRUE

Used with Resource_ChoicesInit()


choices_READ

#define choices_READ        FALSE

Used with Resource_ChoicesPath()


choices_WRITE

#define choices_WRITE       TRUE

Used with Resource_ChoicesPath()


Variables


resource_pathname

extern char resource_pathname[32];

This string is used as a prefix for all pathnames in DeskLib that load resource files (eg. Template_LoadFile). It is set to either "<Name$Dir>." or "Name:", depending on how you initialise the resource manager.


resource_sprites

extern sprite_area resource_sprites;

This variable points to a sprite area containing sprites belonging to your task. If you have not loaded any with Resource_LoadSprites, it will point to the wimp sprite area.