used for loading resources More...

Public Member Functions
	closeResourceFile (int refNum)
	stop searching a file or folder for resources More...

Image	getImage (string imageName)
	load an image by name from the resources More...

ImageStrip	getImageStrip (string imageName)
	load an image strip by name from the resources More...

string	getLanguage ()
	return the current active language More...

BinaryString	getResource (string resourceName)
	get an untyped resource by name More...

string	getResourcePaths ()
	get the paths that will be searched for resources More...

number	getResourceSize (string resourceName)
	get the size of a resource by name More...

string	getString (int id, int substring=-1)
	fetch a numbered string from the resources More...

number	openResourceFile (string filename)
	add a zip file or a directory to the resource search path More...

ResourceManager	setLanguage (string inLanguage)
	set the currently active language for More...

Related Functions
(Note that these are not member functions.)
	getResourceManager
	get the singleton instance of the ResourceManager used by the pdg framework More...

	res
	the singleton instance of the ResourceManager More...

Detailed Description

used for loading resources

Note: API Stability: 2 - Unstable. The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable. Backwards-compatibility will be maintained if reasonable.

Overview

The Resource Manager lets you conveniently load localized strings, images, and custom resources from a collection of folders and zip files. Resource locations are searched for specific resources starting with the most recently added, so it's easy to support modules, plugins or expansion packs that override standard resources.

The Resource Manager also makes localization easier by automatically loading strings from the correct localized file, and falling back to the default if no localized string was found. There are also utility functions provided for string assembly that works for localized strings, even if the order of substitution items is different in various localization.

Strings Resource File Format

The strings.txt and strings-{lang}.txt files must be UTF-8 format, with one string per line. Each line must have a resource number, followed by a tab (ASCII 09) character, then the string or string list. For string lists, the individual strings are separated by the vertical bar character (|). Comment lines are allowed, and must start with #. Blank lines are also allowed.

Example File:

# this is a comment line

10  This is a test string
20  This is string ID 20
30  Here is a string list|with multiple parts|each section can be fetched separately|getString(30, 3) gets this section

Member Function Documentation

closeResourceFile ( int refNum )

stop searching a file or folder for resources

Given the refNum returned by a previous call to openResourceFile() for a file or folder, it removes that file or folder from the search list for resources.

Parameters

refNum the reference number for the file or folder

getImage ( string imageName )

load an image by name from the resources

Load an image by name from the resources. Returns an Image object. If the resource doesn't exits, false is returned, so you can check for the image loading with:

var img = pdg.res.getImage('myImage.png');
if (img === false) {
                console.log('image not found!');
} else {
                port.drawImage([0,0], img);  // draw the image
}

Parameters

imageName The name under which the image is stored in the resources

Returns: an Image object, or false if not found

See Also: getImageStrip()

getImageStrip ( string imageName )

load an image strip by name from the resources

Parameters

imageName The name under which the image strip is stored in the resources

Returns: the named ImageStrip, or false if no found

See Also: getImage()

getLanguage ( )

return the current active language

Returns the last value passed in to setLanguage(). By convention, this would be a 2 character language code, such as "en", "fr", "de" or "es". If there was no prior call to setLanguage() this will return an empty string.

Returns: the currently active language

getResource ( string resourceName )

get an untyped resource by name

Get a resource by name. The resource is returned as a block of data in a MemBlock object. If the resource doesn't exits, false is returned, so you can check for the resource loading with:

var res = pdg.res.getResource('myRes');
if (res === false) {
    console.log('resource not found!');
} else {
    // do something with the resource
}

Parameters

resourceName the name of the resource

Returns: a MemBlock with the resource data, or false if not found

Note: the entire resource is loaded into memory, so you might want to check the size before loading it using getResourceSize() if you are concerned about how large it could be.

See Also: getResourceSize()

getResourcePaths ( )

get the paths that will be searched for resources

Get a semicolon (;) separated list of the paths and zip files that will be searched for resources. They are listed in the order searched.

Returns: a string with the paths and files

See Also: openResourceFile(); closeResourceFile()

getResourceSize ( string resourceName )

get the size of a resource by name

Get the total number of bytes needed to load a particular named resource. If the resource does not exist this will return zero (0).

Parameters

resourceName the name of the resource to check

Returns: the size in bytes of the resource

getString	(	int	id,
		int	substring = `-1`
	)

fetch a numbered string from the resources

Get a string by resource number from the first resource file it can be found in. Files are searched in the reverse order they were added, and if a language is set using setLanguage() it will search that localized version first, then fall back to the non-localized string next.

Parameters

id	the string id number to find
substring	optionally fetch a particular substring from a string list.

Returns: the desired string, or an empty string if not found

Note: in order to locate strings, they must be stored in a strings.txt file (or strings-{lang}.txt for localized strings), either inside the resource zip file or at the top level of the resource directory. See the Detailed Description section for ResourceManager above for details on the strings.txt format.

See Also: setLanguage(); openResourceFile()

openResourceFile ( string filename )

add a zip file or a directory to the resource search path

Add a zip file or a resource directory to the list of locations searched for resources. Returns a resource file reference number, which can be passed to closeResourceFile() to remove it from the list.

Parameters

filename the name of a zip file; or the name of a directory that contains non-zip resources

Returns: a resource file reference number

Note: the ref number returned is not a file system ref number, and cannot be used for any file system operations. It can only be passed to closeResourceFile()

See Also: closeResourceFile()

setLanguage ( string inLanguage )

set the currently active language for

Set the language that should be used when searching for string resources.

By convention, inLanguage should be a 2 character language code, such as "en", "fr", "de" or "es", however it can be anything you want. This does nothing to affect previously loaded strings, it only applies to new calls to getString().

Parameters

inLanguage the new language to treat as active

See Also: getLanguage(); getString()

Note: This works by getString() calls searching for strings-{lang}.txt instead of strings.txt. If the string is not found, it will try strings.txt as well.

Friends And Related Function Documentation

getResourceManager

Returns: ResourceManager singleton object

Public Member Functions

Related Functions

Detailed Description

Overview

Strings Resource File Format

Member Function Documentation

Friends And Related Function Documentation

User Comments