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