Index

Package: Resources

Description

package Resources is
Copyright (c) 2012 Kevin Wellwood All rights reserved. This source code is distributed under the Modified BSD License. For terms and conditions, see license.txt.

Classes

Resource_File

type Resource_File is tagged limited private;
A Resource_File represents a resource file loaded in memory. The contents of the file can be accessed via various methods. Once a Resource_File is closed, its backing data should no longer be relied upon. If the file data is required after the Resource_File must be closed, a copy of the contents should be made. Resource files are cached to avoid the cost of searching and reading from disk each time file is needed but the details of the cache and how/when it is purged are private.

Types

A_Resource_File

type A_Resource_File is access all Resource_File'Class;

Constants & Global variables

RESOURCE_ERROR

RESOURCE_ERROR,
    RESOURCE_FORMAT_ERROR : exception;

RESOURCE_FORMAT_ERROR

RESOURCE_FORMAT_ERROR : exception;

Subprograms & Entries

Get_Address

function Get_Address
( this: not null access Resource_File'Class ) return Address;
Returns the address of the resource file's data. The length of the data can be determined by calling Size.

Get_Filename

function Get_Filename
( this: not null access Resource_File'Class ) return String;
Returns the filename of the resource.

Get_Id

function Get_Id
( this: not null access Resource_File'Class ) return String;
Returns an identifying string comprised of the original filepath and group name used to find the resource. Useful for debugging purposes but not absolute identification.

Get_File

function Get_File
( this: not null access Resource_File'Class ) return A_Allegro_File;
Returns a new Allegro_File reference to the resource. Be sure to close the returned handle before unloading the resource.

Get_Stream

procedure Get_Stream
( this: not null access Resource_File'Class;
strm: out A_Buffer_Stream );
Returns a new read-only stream backed by the resource contents. Be sure to close the stream before unloading the resource.

Size

function Size
(this: not null access Resource_File'Class ) return Unsigned_32;
Returns the size of the file in bytes;

Release

procedure Release
( resource: in out A_Resource_File );
Releases the reference to the resource. Resource files are reference counted so be sure to call this when finished with a Resource_File.

Load_Resource

function Load_Resource
( filepath: String;
group: String;
keep: Boolean := False ) return A_Resource_File;
Searches for and loads a resource file, returning a reference to it. The search order for resource files is as follows: 1. filepath (If filepath is an absolute file path) 2. working_dir/filename 3. working_dir/group/filename 4. working_dir/group.zip/filename 5. user_dir/filename (user_dir is defined by Application) 6. media_dir/filename (media_dir is defined by "media" preference) 7. media_dir/group/filename 8. media_dir/group.zip/filename (Where 'filename' is the filename taken from 'filepath'.) NULL will be returned if the file is not found or otherwise can't be accessed. Resource files are reference counted, so you must call Unload_Resource when finished with the Resource_File. If 'keep' is True, the resource will be kept in memory even after no references remain. This is useful for keeping the most frequently used resources cached in memory for the life of the application.

Preload_Resource

procedure Preload_Resource
( filepath: String;
group: String );
Loads a resource into memory in the same way as Load_Resource except the reference will not be returned and the internal reference count will begin at zero. Use this to prefetch resources from disk. No load errors are reported by this procedure.

Write_Path

function Write_Path
( filepath: String;
group: String ) return String;
Attempts to find resource 'filepath' and then returns an absolute path that can be used to overwrite or override the resource. The same search algorithm as Load_Resource will be used. If the resource is found outside of an archive, its absolute path will be returned. If the resource is found inside an archive, then the returned path will point to a file of the same name in the same directory as its archive, effectively allowing the new file to override its archived version. If this location is not writable (entirely possible for installed applications) then the caller should fallback to the current working directory. If that fails, fallback to the user directory returned by Application.Get_User_Directory. If the resource is not found, then the returned path will point to a file of the same name in the current working directory. If this location is not writable (entirely possible for installed applications) then the caller should fallback to the user directory .