module resource

The resource module exports some utility functions for finding, loading and cacheing various types of resources. By default, resource files are looked for in a directory named Resources alongside the .py file of the progam's main module, but that can be changed by assigning to the resource_dir module variable.

Resource names are specified in a platform-independent manner using a series of pathname components. Specific resource types are looked for by default in subdirectories of the resources directory as follows:

Images	resources/images
Fonts	resources/fonts
Sounds	resources/sounds
Text	resources/text
Cursors	resources/cursors

The subdirectory can in some cases be overridden using the prefix parameter to the relevant resource-loading function.

Each type of resource has a cache. The first time a resource with a given name is requested, it is loaded and placed in the cache; subsequent requests for the same name will return the cached object.

Default Fonts

Various widgets default to using members of the Bitstream Vera font family (specifically the Vera and Vera Bold typefaces). These are not distributed with this package; if you want to use the defaults, you will have to obtain these fonts yourself and put them in the fonts directory indicated above.

The default fonts can be overridden by modifying the theme. See The Theme System for details.

Variables

resource_dir: Pathname of the directory in which to look for resource files. Initialized to a directory called resources in the same directory as the resource.py file.

optimize_images: If true, images loaded with get_image() will have convert_alpha() called on them by default. Defaults to true.

Functions

resource_path(name, ...): Constructs a resource pathname from the module variable resource_dir and the given pathname components.
resource_exists(name, ...): Returns true if a resource exists with the given pathname components.

get_image(name, ... , border = 0, optimize = optimize_images, noalpha = False, rle = False, prefix = "images"): Loads the specified image from the images directory or returns it from the cache. If border is specified, a border of that number of pixels is stripped from around the image (making it 2 * border pixels smaller in each direction). If optimize is true, convert_alpha() is called on the image. If noalpha is true, any alpha channel is stripped from the image. If rle is true, the image is run-length encoded to improve blitting speed.

For some of the options to work correctly, you must have initialized the PyGame screen before calling get_image().
get_font(size, name, ..., prefix = "fonts"): Loads the specified font or returns it from the cache.
get_sound(name, ..., prefix = "sounds"): Loads the specified sound or returns it from the cache.

If the sound is unable to be loaded for any reason, a warning message is printed and a dummy sound object with no-op methods is returned. This allows an application to continue without sound in an environment where sound support is not available.
load_sound(path): Loads a sound from the file specified by path, or returns it from the cache. Like get_sound(), returns a dummy sound object if the sound cannot be loaded.

get_text(name, ..., prefix = "text"): Loads the contents of a text file as a string or returns it from the cache. The file is opened in universal newlines mode.

get_cursor(name, ..., prefix = "cursors"): Loads a cursor from an image file or returns it from the cache. The cursor is returned as a tuple of arguments suitable for passing to the PyGame function set_cursor().

The image must be no larger than 16x16 pixels and should consist only of the colours black (0, 0, 0), white (255, 255, 255), blue (0, 0, 255) and cyan (0, 255, 255). Blue and cyan are used to indicate the position of the hotspot, with blue if the hotspot is over a black or transparent pixel, and cyan if it is over a white pixel. The hotspot defaults to the top left corner. If the image has an alpha channel, it should consist of fully opaque or fully transparent pixels.

---