DeskLib 2.90a:Template.h


Contents


Introduction and Overview

This header provides a set of functions for loading, caching and retrieving window templates from Template files.


Functions


Template_Find

window_block * Template_Find(const char *name);

This tries to find the named template. If it finds it, it returns a pointer to the original template definition so you can alter it. To actually use the template, call Template_Clone.

If it cannot find the template, it returns NULL.


Template_Clone

window_block * Template_Clone(const char *name, int maxtitlesize);

This makes a copy of the named template and returns a pointer to it. If it cannot find the template, it returns NULL.

'maxtitlesize' is the number of bytes to reserve for the window's title. This should be set large enough to hold any title you intend to give to the window, because the only way to extend it is to delete the window and recreate it. Possible 'special' values for 'maxtitlesize' are template_TITLEDEFAULT which will allocate 260 bytes (enough for a pathname and an asterisk), and template_TITLEMIN which will allocate the space set in the template file.

When you are finished with the clone, use Template_Free to release the memory it is using.


Template_Free

void Template_Free(window_block **windowdef);

This frees the memory used by a template cloned with Template_Clone. It must *only* be used with such templates, never on an original template or it *will* crash your application or worse.

Pass in a pointer to a pointer to a window block - this allows the function to set the pointer to NULL so you won't try an use it after freeing it. It freed all the memory used by the window including indirected data. This means that all such data should have been allocated with malloc or else the icons deleted before calling this function.


Template_Delete

void Template_Delete(const char *name);

Deletes the named template from the list of available templates, freeing any memory claimed by the template. This will "pull the rug out from under" any windows created using this template, and your program will crash if any such windows are open.

However, any windows created using Template_Clone'd templates will be unaffected. (Moral of the story: Always use Template_Clone)

Pass in the identifier string of the template you wish to delete.


Template_ClearAll

void Template_ClearAll(void );

Clears ALL currently held templates. (equivalent to you calling Template_Delete() for each template in turn)

Also releases all fonts that were in use by the loaded templates.


Template_LoadFile

void Template_LoadFile(const char *leafname);

This loads all template definitions from the given file (which should be on the resource_pathname for your task) into the Template cache. You can call this function more than once - the new templates will be added to the template cache. If any errors occur, they go to Error_ReportFatal or similar, as they tend to be unfixable.

After loading the file, use Template_Clone to get a copy of any of the templates for use by giving the name as specified in the file. If you don't want to keep old templates around after you've finished with them call Template_Delete or Template_ClearAll. If you want to use outline fonts in your windows make sure you call Template_UseOutlineFonts *before* loading the file.

Note: earlier versions of DeskLib required an explicit call to Template_Initialise before using this function. This is no longer required.


Template_UseOutlineFonts

void Template_UseOutlineFonts(void );

Call this before calling Template_LoadFile if you wish to use outline fonts in your windows. This is used less often now that RISC OS has a desktop font which is used automatically anyway. It allocates a font usage array and adds an atexit handler to free fonts you are using when your program quits.


Template_UseSpriteArea

void Template_UseSpriteArea(sprite_area area);

This function sets the sprite area which will be used for all future calls to Template_Find or Template_Clone. Set this to 1 to use the Wimp sprite pool (this is the default setting).


Template_LinkSpriteArea

void Template_LinkSpriteArea(const char *identifier, sprite_area area);

This sets the given single window template to use the given sprite area. Set this to 1 to use the Wimp sprite pool (this is the default setting).


Macros


template_TITLEDEFAULT

#define template_TITLEDEFAULT (0)

This will cause the window creation function to allocate 260 bytes for the window title, so it will be able to hold a pathname (generally assumed to be 256 bytes or smaller) with a little space for an asterisk to mark altered contents or similar.


template_TITLEMIN

#define template_TITLEMIN     (-1)

This will cause the window creation function to allocate the same amount of memory for the window title as was set in the template file. This is the recommended default for windows whose titles will not be changed.