home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 2 / DATAFILE_PDCD2.iso / utilities2 / desklib / !DeskLib / h / Template < prev    next >
Encoding:
Text File  |  1993-07-13  |  6.1 KB  |  144 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 John Winters and Jason Williams
  13.     Version: 1.03 (13 Jul 1993)
  14.     Purpose: Loading, caching, and retrieval of window templates
  15.  
  16. */
  17.  
  18.  
  19. #ifndef __dl_template_h
  20. #define __dl_template_h
  21.  
  22.  
  23.   /* Template_Initialise --------------------------------------------------
  24.    * Initialises the Template manager ready for use
  25.    * Make sure you call this function before any other Template_ calls
  26.    * --- In future, this call will be extended to include setting up
  27.    *     the things necessary to use outline fonts in your windows.
  28.    */
  29. extern void Template_Initialise(void);
  30.  
  31.  
  32.   /* Template_Find --------------------------------------------------------
  33.    * Tries to find the named template, and return a pointer to it's 
  34.    * base window_block. This is so that you can alter the template
  35.    * original. Note that this *is* the original, so don't stuff it up!
  36.    * If you wish to USE the template, please use Template Clone!
  37.    */
  38. extern window_block *Template_Find(char *name);
  39.  
  40.  
  41.   /* Template_Clone -------------------------------------------------------
  42.    * Makes a copy of the named template, and returns a pointer to the copy.
  43.    *
  44.    * "maxtitlesize" is the number of bytes that should be allocated
  45.    * for the title - this should be big enough to accomodate ANY title 
  46.    * string you expect to give to this window. This is because the only way
  47.    * to alter the size of this indirected field is to re-create the window
  48.    * which is usually an undesirable thing to do. (See below for a list of
  49.    * the possible values for this argument)
  50.    *
  51.    * A value of 0 for maxtitlesize will use the default value (currently 260)
  52.    * If the window's title icon is not indirected, this value is ignored
  53.    * (so most of the time, using 0 is a sensible thing to do)
  54.    *
  55.    * Returns NULL if the template can't be found
  56.    * Dies with an error if a serious error occurs (malloc failure, etc.)
  57.    */
  58. extern window_block *Template_Clone(char *name, int maxtitlesize);
  59.  
  60.   /*  NOTE
  61.    *  The following values may be used for 'maxtitlesize':
  62.    *    TITLEDEFAULT   0     reserves 260 bytes, enough for a full pathname
  63.    *    TITLEMIN      -1     reserves the title as much room as set in the
  64.    *                           template file (title indirected data size)
  65.    *                           (the recommended value - especially for windows
  66.    *                           with constant title strings)
  67.    *    (any positive value) reserves 'maxtitlesize' bytes of storage for
  68.    *                           the indirected title data
  69.    */
  70. #define template_TITLEDEFAULT (0)
  71. #define template_TITLEMIN     (-1)
  72.  
  73.  
  74.   /* Template_Free --------------------------------------------------------
  75.    * Frees up the memory used by a Template_Clone'd template. Results are
  76.    * undefined if you free a non-Clone'd template or try to free it more
  77.    * than once. (i.e. don't do it!)
  78.    * Pass in a pointer to a (window_block *). The window definition's
  79.    * memory (including indirected title/icons) will be freed, and the
  80.    * (window_block *) will be set to NULL to ensure you don't try to use
  81.    * it now that it is invalid.
  82.    */
  83. extern void Template_Free(window_block **windowdef);
  84.  
  85.  
  86.   /* Template_Delete ------------------------------------------------------
  87.    * Deletes the named template from the list of available templates, freeing
  88.    * any memory claimed by the template. This will "pull the rug out from
  89.    * under" any windows created using this template, and your program will
  90.    * crash if any such windows are open.
  91.    * However, any windows created using Template_Clone'd templates will
  92.    * be unaffected. (Moral of the story: Always use Clone)
  93.    * Pass in the identifier string of the template you swish to delete
  94.    */
  95. extern void Template_Delete(char *name);
  96.  
  97.  
  98.   /* Template_ClearAll ----------------------------------------------------
  99.    * Clears ALL currently held templates. (equivalent to you calling
  100.    * Template_Delete() for each template in turn)
  101.    */
  102. extern void Template_ClearAll(void);
  103.  
  104.  
  105.   /* Template_LoadFile ----------------------------------------------------
  106.    * Loads all template definitions from the specified file.
  107.    * Due to the essential nature of templates, if any errors occur, this 
  108.    * reports to Error_ReportFatal(Internal)
  109.    * After loading a template file, use Template_Clone to get a copy
  110.    * of any of the templates for use.
  111.    * 
  112.    * Loading a second file will simply ADD the new templates to the template
  113.    * list. So long as there are no name clashes, you can then use any
  114.    * template from either file.
  115.    *
  116.    * Use Template_Delete/ClearAll if you don't want to keep old templates
  117.    * when loading in new ones.
  118.    *
  119.    * If you want to use outline fonts in windows, then remember to call
  120.    * Template_UseOutlineFonts() BEFORE you call Template_LoadFile() (see below)
  121.    */
  122. extern void Template_LoadFile(char *leafname);
  123.  
  124.  
  125.   /* Template_UseOutlineFonts ---------------------------------------------
  126.    * Call this BEFORE calling Template_LoadFile() if you wish to use outline
  127.    * fonts (rather than the system font) in your windows. It allocates the
  128.    * font usage array, and also adds an atexit handler to lose all the fonts
  129.    * you are using when your program exits.
  130.    *
  131.    * NOTE that future versions of RISC OS *WILL* supply an outline font as the
  132.    * system font, so your program should offer a choice of system font OR
  133.    * outline font to the user.
  134.    */
  135. extern void Template_UseOutlineFonts(void);
  136.  
  137.  
  138.   /* Future attractions:
  139.    * - Ability to save templates (Anyone want to write a template editor?)
  140.    * - New template format ('Glass') allowing much more powerful stuff
  141.    */
  142.  
  143. #endif
  144.