(*
 * Title:    template.h
 * Purpose:  template file management
 *
 *)

(*
 * This file contains functions used for loading/manipulating templates
 * (typically set up using the template editor). The templates are assumed
 * to be held in a file "Templates" in the application's directory.
 * The dialogue box module of the "wimp" library, uses these templates when
 * creating dialogue boxes.
 *
 *)

#ifndef __template_h
#define __template_h

type template_ptr = ^template;
     template =
       record
         next : template_ptr;
         workspace : pointer;
         workspacesize : integer;
         font : string;
         name : packed array[1..11] of char;
         window : wimp_wind
       end;


(* ----------------------------- template_copy -----------------------------
 * Description:   Create a copy of a template.
 *
 * Parameters:    template *from -- the original template
 * Returns:       a pointer to a copy of "from".
 * Other Info:    Copying also includes fixing up pointers into workspace for
 *                indirected icons/title.  Also includes allocation of this
 *                space.
 *
 *)
function template_copy(from : template_ptr) : template_ptr; extern;


(* -------------------------- template_readfile ----------------------------
 * Description:   Reads the template file into a linked list of templates.
 *
 * Parameters:    char *name -- name of template file
 * Returns:       Non-zero if sprites are used in the template file.
 * Other Info:    Note that a call is made to resspr_area(), in order to
 *                fix up a window's sprite pointers, so you must have 
 *                already called resspr_init.
 *
 *)
function template_readfile(name : string) : boolean; extern;


(* ----------------------------- template_find -----------------------------
 * Description:   Finds a named template in the template list.
 *
 * Parameters:    char *name -- the name of the template (as given in FormEd)
 * Returns:       a pointer to the found template.
 * Other Info:    none.
 *
 *)
function template_find(name : string) : template_ptr; extern;                


(* ---------------------------- template_loaded ----------------------------
 * Description:   Sees if there is anything in the template list.
 *
 * Parameters:    void
 * Returns:       Non-zero if there is something in the template list.
 * Other Info:    none.
 *
 *)
function template_loaded : boolean; extern;


(* ---------------------------- template_use_fancyfonts --------------------
 * Description:   Provides a font usage array for loading templates which
 *                use fonts other than 'system font'
 *
 * Parameters:    void.
 * Returns:       void.
 * Other Info:    This function should be called once BEFORE template_init.
 *                It allocates a font usage array, which it uses to 'lose'
 *                any fancy fonts used, when your program exits.
 *                It installs a C exit handler to do this.
 *                This function is useful if your dialogue boxes use fonts
 *                other than system font.
 *
 *)
procedure template_use_fancyfonts; extern;

 
(* ---------------------------- template_init ------------------------------
 * Description:   Initialise ready for use of templates.
 *
 * Parameters:                             
 * Returns:       void.
 * Other Info:    Should be called before any ops which use templates
 *                (eg dialogue box creation).
 *                The amount of space used is optimised to be the least
 *                possible.
 *
 *)
procedure template_init; extern;


(* --------------------------- template_syshandle --------------------------
 * Description:   Get a pointer to the underlying window used to create a
 *                template.
 *
 * Parameters:    char *templatename.
 * Returns:       Pointer to template's underlying window (0 if template
 *                not found).
 * Other Info:    Any changes made to the wimp_wind structure will affect
 *                future windows generated using this template.
 *
 *)
function template_syshandle(name : string) : wimp_wind_ptr; extern;
 
#endif

(* end template.h *)
