/*
    ####             #    #     # #
    #   #            #    #       #          The FreeWare C library for 
    #   #  ##   ###  #  # #     # ###             RISC OS machines
    #   # #  # #     # #  #     # #  #   ___________________________________
    #   # ####  ###  ##   #     # #  #                                      
    #   # #        # # #  #     # #  #    Please refer to the accompanying
    ####   ### ####  #  # ##### # ###    documentation for conditions of use
    ________________________________________________________________________

    File:    Template.h
    Author:  Copyright  1992, 1993, 1994 John Winters and Jason Williams
    Version: 1.05 (Dec 1994)
    Purpose: Loading, caching, and retrieval of window templates

*/


#ifndef __dl_template_h
#define __dl_template_h

#ifdef __cplusplus
extern "C" {
#endif


#ifndef __dl_sprite_h
#include "Sprite.h"
#endif

#ifndef __dl_linklist_h
#include "LinkList.h"
#endif


extern void Template_Initialise(void);
  /*
   * Initialises the Template manager ready for use
   * Make sure you call this function before any other Template_ calls
   * --- In future, this call will be extended to include setting up
   *     the things necessary to use outline fonts in your windows.
   */


extern window_block *Template_Find(char *name);
  /*
   * Tries to find the named template, and return a pointer to it's 
   * base window_block. This is so that you can alter the template
   * original. Note that this *is* the original, so don't stuff it up!
   * If you wish to USE the template, please use Template Clone!
   */


extern window_block *Template_Clone(char *name, int maxtitlesize);
  /*
   * Makes a copy of the named template, and returns a pointer to the copy.
   *
   * "maxtitlesize" is the number of bytes that should be allocated
   * for the title - this should be big enough to accomodate ANY title 
   * string you expect to give to this window. This is because the only way
   * to alter the size of this indirected field is to re-create the window
   * which is usually an undesirable thing to do. (See below for a list of
   * the possible values for this argument)
   *
   * A value of 0 for maxtitlesize will use the default value (currently 260)
   * If the window's title icon is not indirected, this value is ignored
   * (so most of the time, using 0 is a sensible thing to do)
   *
   * Returns NULL if the template can't be found
   * Dies with an error if a serious error occurs (malloc failure, etc.)
   *
   * When you're finished with the clone, use Template_Free to release
   * the memory it is using.
   */

  /*  NOTE
   *  The following values may be used for 'maxtitlesize':
   *    TITLEDEFAULT   0     reserves 260 bytes, enough for a full pathname
   *    TITLEMIN      -1     reserves the title as much room as set in the
   *                           template file (title indirected data size)
   *                           (the recommended value - especially for windows
   *                           with constant title strings)
   *    (any positive value) reserves 'maxtitlesize' bytes of storage for
   *                           the indirected title data
   */

#define template_TITLEDEFAULT (0)
#define template_TITLEMIN     (-1)


extern void Template_Free(window_block **windowdef);
  /*
   * Frees up the memory used by a Template_Clone'd template.
   * If you try to Free a non-Clone'd template, it WILL blow up, so don't.
   *
   * Pass in a pointer to a (window_block *). The window definition's
   * memory (including indirected title/icons) will be freed, and the
   * (window_block *) will be set to NULL to ensure you don't try to use
   * it now that it is invalid.
   */


extern void Template_Delete(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 Clone)
   * Pass in the identifier string of the template you swish to delete
   */


extern 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.
   */


extern void Template_LoadFile(char *leafname);
  /*
   * Loads all template definitions from the specified file.
   * Due to the essential nature of templates, if any errors occur, this 
   * reports to Error_ReportFatal(Internal)
   * After loading a template file, use Template_Clone to get a copy
   * of any of the templates for use.
   * 
   * Loading a second file will simply ADD the new templates to the template
   * list. So long as there are no name clashes, you can then use any
   * template from either file.
   *
   * Use Template_Delete/ClearAll if you don't want to keep old templates
   * when loading in new ones.
   *
   * If you want to use outline fonts in windows, then remember to call
   * Template_UseOutlineFonts() BEFORE you call Template_LoadFile() (see below)
   */


extern void Template_UseOutlineFonts(void);
  /*
   * Call this BEFORE calling Template_LoadFile() if you wish to use outline
   * fonts (rather than the system font) in your windows. It allocates the
   * font usage array, and also adds an atexit handler to lose all the fonts
   * you are using when your program exits.
   *
   * NOTE that future versions of RISC OS *WILL* supply an outline font as the
   * system font, so your program should offer a choice of system font OR
   * outline font to the user.
   */


extern void Template_UseSpriteArea(sprite_area area);
  /*
   * This can be called before any Template_Find or Clone call to set the
   * sprite area that will be used by all future Find/Clone'd templates.
   * Set this to NULL (the default if you don't call this function) in order
   * to use the WIMP sprite pool.
   */


extern void Template_LinkSpriteArea(char *identifier, sprite_area area);
  /*
   * Sets the given single window template to use the given sprite area
   */





/*
The rest of this file is not for user consumption - the declarations are
used only by the Template_ functions and Window_ModeChange().
Window_ModeChange() needs to get inside the template data to modify
fonts handles.
*/

/* Could have '#if defined( _DeskLib_Window) || defined( _DeskLib_Template)' here... */

typedef struct
{
  linklist_header header;
  char            identifier[wimp_MAXNAME + 1];
  window_block    *windowdef;
  int             dataoffset;
  int             templatesize;    /* size of window+icons+indirect data */
  int             indirectsize;    /* size of expanded indirect data     */
  char            *indirectdata;
} template_record;


#ifdef _DeskLib_SDLS
  extern linklist_header *Template__Ref_list( void);
  extern font_array      **Template__Ref_fontarray( void);
#endif

#if defined( _DeskLib_SDLS) && !defined( _DeskLib_Template)
  #define template_list      (*Template__Ref_list())
  #define template_fontarray (*Template__Ref_fontarray())
#else
  extern linklist_header template_list;
  extern font_array      *template_fontarray;
#endif



#ifdef __cplusplus
}
#endif


#endif
