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

    File:    Resource.h
    Author:  Copyright  1992, 1993, 1994 Jason Williams
    Version: 1.02 (Dec 1994)
    Purpose: Resource file (files within user application directory)
             management functions
    Mods:    Julian Smith 20 Mar 1995
             Added function veneers to global vars if _desklib_DLL is
             defined.
*/


#ifndef __dl_resource_h
#define __dl_resource_h

#ifdef __cplusplus
extern "C" {
#endif


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


#ifdef _DeskLib_SDLS
  extern char        *Resource__Ref_pathname( void);
  extern sprite_area *Resource__Ref_sprites ( void);
#endif

#if defined( _DeskLib_SDLS) && !defined( _DeskLib_Resource)
  #define resource_pathname Resource__Ref_pathname()
  #define resource_sprites  (*Resource_Ref_sprites())
#else
  extern char resource_pathname[64];
/*
 * This string is used as a prefix for all pathnames in that load resource
 * files. It is set up by either of the following calls, to be either
 *   "<Name$Dir>."
 * or
 *   "Name:"
 * It is prepended to a leafname (e.g. <Floob$Dir>.Sprites or Floob:Sprites)
 * by some Desklib modules in order to find the resources.
 */

  extern sprite_area resource_sprites;
#endif




extern void Resource_Initialise(char *respath);
  /*
   * Initialises the resource manager. Pass in the name of your application
   * (e.g. if you have set <appname$Dir>, pass in "appname")
   * This tells all DeskLib modules where to look for your resources
   * by setting resource_pathname to "<Appname$Dir>." - this is prepended
   * to all leafnames to create full resource pathnames.
   * This pathname is used by various DeskLib modules (Template, Msgs, etc)
   * -it adds very little code size to your program, and saves you the
   * work of doing the pathname yourself. It also makes changing the
   * resource directory at a later development stage far easier.
   *
   * This also calls dll_NameApp if the caller is a DLL client
   *
   * See also the ALTERNATIVE call, Resource_InitialisePath()
   * OR see Resource_SetResDir().
   */


extern void Resource_InitialisePath(char *respath);
  /*
   * Initialises the resource manager.
   *
   * If you prefer to use a path variable for your resources (for easier
   * setting of language resources), then you can initialise the resources
   * by calling this function.
   * (Instead of setting the resource prefix to "<AppName$Dir>.", it will
   *  set it to "AppName:", where "AppName" is the 'respath' parameter)
   *
   * See also the ALTERNATIVE call: Resource_Initialise()
   */


extern void Resource_SetResDir(char *subdir);
  /* If, after calling Resource_Initialise(), your actual resources are
   * located in:
   *   <App$Dir>.[country]
   * or:
   *   <App$Dir>[.subdir].[country]
   * Then you can use this function to set that up correctly.
   *
   * The "[country]" is the country directory specified in your current
   * Territory module (ie, "France", "Germany"...). If the given resource
   * directory cannot be found, it will fall back to "UK", so your application
   * will ALWAYS work if a "UK" resource is present, and you or your users
   * can expand this at a later date simply by adding resource directories
   * relevant to their territory.
   *
   * If, like me, you like to keep your resources inside a sub-directory
   * (I call mine "Resources"), then simply set the subdir parameter when
   * calling this function.
   *
   * For example:
   *   Resource_Initialise("TestApp");
   *     // -> resources are now looked for in "<TestApp$Dir>".
   *   Resource_SetResDir("");
   *     // Territory is 'France'.
   *     // -> resources are now looked for in "<TestApp$Dir>.France".
   *     // (or "<TestApp$Dir>.UK" if <TestApp$Dir>.France doesn't exist)
   *
   * Or:
   *   Resource_Initialise("TestApp");
   *     // -> resources are now looked for in "<TestApp$Dir>".
   *   Resource_SetResDir("Resources");
   *     // Territory is 'UK'.
   *     // -> resources are now looked for in "<TestApp$Dir>.Resources.UK".
   *
   * YOU MUST CALL Resource_Initialise() BEFORE CALLING THIS FUNCTION.
   *
   * This was added for the DeskLib 2.30 [RM/32] release, and is NOT
   * present in the original version of DeskLib 2.30.
   */

extern void Resource_LoadSprites(void);
  /*
   * Loads the programs 'Sprites' file from the resource path, ready for use.
   * Notes: Call this only after you have Resource_Initialise
   *        To use these sprites for your templates, call
   *          Template_UseSpriteArea(resource_sprites);
   *        after calling this function.
   * If you do not call this function, the 'resource_sprites' area will
   * indicate the wimp sprite area.
   */


#ifdef __cplusplus
}
#endif


#endif
