home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Template < prev    next >
Encoding:
Text File  |  1996-05-21  |  7.6 KB  |  217 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Template.h
  12.     Author:  Copyright © 1992, 1993, 1994 John Winters and Jason Williams
  13.     Version: 1.05 (Dec 1994)
  14.     Purpose: Loading, caching, and retrieval of window templates
  15.  
  16. */
  17.  
  18.  
  19. #ifndef __Desk_Template_h
  20. #define __Desk_Template_h
  21.  
  22. #ifdef __cplusplus
  23.     extern "C" {
  24. #endif
  25.  
  26.  
  27. #ifndef __Desk_Sprite_h
  28.     #include "Desk.Sprite.h"
  29. #endif
  30.  
  31. #ifndef __Desk_LinkList_h
  32.     #include "Desk.LinkList.h"
  33. #endif
  34.  
  35.  
  36. extern void Desk_Template_Initialise(void);
  37.   /*
  38.    * Initialises the Template manager ready for use
  39.    * Make sure you call this function before any other Desk_Template_ calls
  40.    * --- In future, this call will be extended to include setting up
  41.    *     the things necessary to use outline fonts in your windows.
  42.    */
  43.  
  44.  
  45. extern Desk_window_block *Desk_Template_Find(const char *name);
  46.   /*
  47.    * Tries to find the named template, and return a pointer to it's 
  48.    * base Desk_window_block. This is so that you can alter the template
  49.    * original. Note that this *is* the original, so don't stuff it up!
  50.    * If you wish to USE the template, please use Template Clone!
  51.    */
  52.  
  53.  
  54. extern Desk_window_block *Desk_Template_Clone(const char *name, int maxtitlesize);
  55.   /*
  56.    * Makes a copy of the named template, and returns a pointer to the copy.
  57.    *
  58.    * "maxtitlesize" is the number of bytes that should be allocated
  59.    * for the title - this should be big enough to accomodate ANY title 
  60.    * string you expect to give to this window. This is because the only way
  61.    * to alter the size of this indirected field is to re-create the window
  62.    * which is usually an undesirable thing to do. (See below for a list of
  63.    * the possible values for this argument)
  64.    *
  65.    * A value of 0 for maxtitlesize will use the default value (currently 260)
  66.    * If the window's title icon is not indirected, this value is ignored
  67.    * (so most of the time, using 0 is a sensible thing to do)
  68.    *
  69.    * Returns NULL if the template can't be found
  70.    * Dies with an error if a serious error occurs (malloc failure, etc.)
  71.    *
  72.    * When you're finished with the clone, use Desk_Template_Free to release
  73.    * the memory it is using.
  74.    */
  75.  
  76.   /*  NOTE
  77.    *  The following values may be used for 'maxtitlesize':
  78.    *    TITLEDEFAULT   0     reserves 260 bytes, enough for a full pathname
  79.    *    TITLEMIN      -1     reserves the title as much room as set in the
  80.    *                           template file (title indirected data size)
  81.    *                           (the recommended value - especially for windows
  82.    *                           with constant title strings)
  83.    *    (any positive value) reserves 'maxtitlesize' bytes of storage for
  84.    *                           the indirected title data
  85.    */
  86.  
  87. #define Desk_template_TITLEDEFAULT (0)
  88. #define Desk_template_TITLEMIN     (-1)
  89.  
  90.  
  91. extern void Desk_Template_Free(Desk_window_block **windowdef);
  92.   /*
  93.    * Frees up the memory used by a Desk_Template_Clone'd template.
  94.    * If you try to Free a non-Clone'd template, it WILL blow up, so don't.
  95.    *
  96.    * Pass in a pointer to a (Desk_window_block *). The window definition's
  97.    * memory (including indirected title/icons) will be freed, and the
  98.    * (Desk_window_block *) will be set to NULL to ensure you don't try to use
  99.    * it now that it is invalid.
  100.    */
  101.  
  102.  
  103. extern void Desk_Template_Delete(const char *name);
  104.   /*
  105.    * Deletes the named template from the list of available templates, freeing
  106.    * any memory claimed by the template. This will "pull the rug out from
  107.    * under" any windows created using this template, and your program will
  108.    * crash if any such windows are open.
  109.    * However, any windows created using Desk_Template_Clone'd templates will
  110.    * be unaffected. (Moral of the story: Always use Clone)
  111.    * Pass in the identifier string of the template you swish to delete
  112.    */
  113.  
  114.  
  115. extern void Desk_Template_ClearAll(void);
  116.   /*
  117.    * Clears ALL currently held templates. (equivalent to you calling
  118.    * Desk_Template_Delete() for each template in turn)
  119.    *
  120.    * Also releases all fonts that were in use by the loaded templates.
  121.    */
  122.  
  123.  
  124. extern void Desk_Template_LoadFile(const char *leafname);
  125.   /*
  126.    * Loads all template definitions from the specified file.
  127.    * Due to the essential nature of templates, if any errors occur, this 
  128.    * reports to Desk_Error_ReportFatal(Internal)
  129.    * After loading a template file, use Desk_Template_Clone to get a copy
  130.    * of any of the templates for use.
  131.    * 
  132.    * Loading a second file will simply ADD the new templates to the template
  133.    * list. So long as there are no name clashes, you can then use any
  134.    * template from either file.
  135.    *
  136.    * Use Desk_Template_Delete/ClearAll if you don't want to keep old templates
  137.    * when loading in new ones.
  138.    *
  139.    * If you want to use outline fonts in windows, then remember to call
  140.    * Desk_Template_UseOutlineFonts() BEFORE you call Desk_Template_LoadFile() (see below)
  141.    */
  142.  
  143.  
  144. extern void Desk_Template_UseOutlineFonts(void);
  145.   /*
  146.    * Call this BEFORE calling Desk_Template_LoadFile() if you wish to use outline
  147.    * fonts (rather than the system font) in your windows. It allocates the
  148.    * font usage array, and also adds an atexit handler to lose all the fonts
  149.    * you are using when your program exits.
  150.    *
  151.    * NOTE that future versions of RISC OS *WILL* supply an outline font as the
  152.    * system font, so your program should offer a choice of system font OR
  153.    * outline font to the user.
  154.    */
  155.  
  156.  
  157. extern void Desk_Template_UseSpriteArea(Desk_sprite_area area);
  158.   /*
  159.    * This can be called before any Desk_Template_Find or Clone call to set the
  160.    * sprite area that will be used by all future Find/Clone'd templates.
  161.    * Set this to NULL (the default if you don't call this function) in order
  162.    * to use the WIMP sprite pool.
  163.    */
  164.  
  165.  
  166. extern void Desk_Template_LinkSpriteArea(const char *identifier, Desk_sprite_area area);
  167.   /*
  168.    * Sets the given single window template to use the given sprite area
  169.    */
  170.  
  171.  
  172.  
  173.  
  174.  
  175. /*
  176. The rest of this file is not for user consumption - the declarations are
  177. used only by the Desk_Template_ functions and Desk_Window_ModeChange().
  178. Desk_Window_ModeChange() needs to get inside the template data to modify
  179. fonts handles.
  180. */
  181.  
  182. /* Could have '#if defined( Desk__making_Window) || defined( Desk__making_Template)' here... */
  183.  
  184. typedef struct
  185. {
  186.   Desk_linklist_header header;
  187.   char            identifier[Desk_wimp_MAXNAME + 1];
  188.   Desk_window_block    *windowdef;
  189.   int             dataoffset;
  190.   int             templatesize;    /* size of window+icons+indirect data */
  191.   int             indirectsize;    /* size of expanded indirect data     */
  192.   char            *indirectdata;
  193. } Desk_template_record;
  194.  
  195.  
  196. #ifdef Desk__using_SDLS
  197.   extern Desk_linklist_header *Desk_Template__Ref_list( void);
  198.   extern Desk_font_array      **Desk_Template__Ref_fontarray( void);
  199. #endif
  200.  
  201. #if defined( Desk__using_SDLS) && !defined( Desk__making_Template)
  202.   #define Desk_template_list      (*Desk_Template__Ref_list())
  203.   #define Desk_template_fontarray (*Desk_Template__Ref_fontarray())
  204. #else
  205.   extern Desk_linklist_header Desk_template_list;
  206.   extern Desk_font_array      *Desk_template_fontarray;
  207. #endif
  208.  
  209.  
  210.  
  211. #ifdef __cplusplus
  212. }
  213. #endif
  214.  
  215.  
  216. #endif
  217.