PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Related Functions | List of all members
ResourceManager Class Reference

used for loading resources More...

Public Member Functions

 closeResourceFile (int refNum)
 stop searching a file or folder for resources
 
Image getImage (string imageName)
 load an image by name from the resources
 
ImageStrip getImageStrip (string imageName)
 load an image strip by name from the resources
 
string getLanguage ()
 return the current active language
 
BinaryString getResource (string resourceName)
 get an untyped resource by name
 
string getResourcePaths ()
 get the paths that will be searched for resources
 
number getResourceSize (string resourceName)
 get the size of a resource by name
 
string getString (int id, int substring=-1)
 fetch a numbered string from the resources
 
number openResourceFile (string filename)
 add a zip file or a directory to the resource search path
 
ResourceManager setLanguage (string inLanguage)
 set the currently active language for
 

Related Functions

(Note that these are not member functions.)

 getResourceManager
 get the singleton instance of the ResourceManager used by the pdg framework
 
 res
 the singleton instance of the ResourceManager
 

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
refNumthe 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
imageNameThe 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
imageNameThe 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
resourceNamethe 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
resourceNamethe 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
idthe string id number to find
substringoptionally 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
filenamethe 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
inLanguagethe 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
related

get the singleton instance of the ResourceManager used by the pdg framework

Returns
ResourceManager singleton object

User Comments