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