resource.c
----------

History
-------
26th October 1992  J R C  Started

   This module is not used by DrawFile; however, it is usd by the test
programme ViewDraw.

   It provides functions to allow different parts (modules or shared
libraries) of an application to load resources into shared structures, and
access them in linear time.

   It uses the |lookup_| module to to this: |resource_| is the WIMP-specific
part of resource loading only.

   The structure provided by the |lookup_| module is a tale that supplies a
mapping between tokens (supplied as strings) and data pointers. This
facility is used in slightly different ways by the different resource types.

Messages files
-------- -----
   |Resource_messages| is used by an application to load a Messages file
into a lookup table. On successful completion, all the tokens in the file
will be in the lookup table and a buffer of messages will have been
allocated. Multiple messages files may be loaded into the same lookup table.
All will be subsequently deleted by a call to |resource_messages_delete|.

   The function works by reading the messages file into a buffer, using
MessageTrans to enumerate the tokens, and storing pointers to them in the
lookup table. Subsequent calls to |resource_messages| cause this block to be
|realloc|'d; the call to |resource_messages_delete| frees it.

   Access to the messages loaded so far is therefore provided by |lookup|:
this call is given a lookup table and a token, and it returns the pointer
stored in the table. In this case, it is a string pointer to the message,
and so should be cast to |char *| before use.

Sprites files
------- -----
   |Resource_sprites| is similar, but works for sprites instead. All the
sprites are loaded into a sprite area which is extended using |realloc| as
necessary.

   Multiple sprites files may be loaded into the same lookup table, and
subsequently deleted by |resource_sprites_delete|. The sprites are combined
using OS_SpriteOp 'merge sprite file', so duplicates are deleted.

   On return from |lookup|, a pointer should therefore be cast to
|osspriteop_header *|.

Templates files
--------- -----
   |Resource_templates| is alos similar, but it works on Templates files via
Wimp_{Open,Load,Close}Template. Again, multiple templates files may be
loaded into the same lookup table, and subsequently deleted by
|resource_templates_delete|. However, in this case, each template is loaded
into a separate |malloc| buffer: all are freed on deletion.

   Returns from |lookup| should be cast to |wimp_window *|.

Future development
------ -----------
   Obviously, this is all tied in with the concept of the Resource Editor.

   I think it would be a good idea to define a Menus resource file type
along the lines of the Templates one, and define |resource_menus| etc for
that file type. This would simply be a binary file containing the
|wimp_menu| structure needed by Wimp_CreateMenu.

   File formats of each type can refer to entries in files of the other
types: for example, a template in a Templates file can refer to a message in
the Messages file, or to a sprite in the Sprites file; a menu in the Menus
file could refer to a template in the templates file (or vice versa). In
general, the dependency graph is not acyclic between the different sorts of
file (though it must be at the token level).

   This implies that this extra looking up is done after all the files have
been opened (by |resource_<something>|): this would be a new function
|resource_initialise| called after all resource_<...>| calls have been made.
It could even be deferred until the token is actually looked up, but that
would mean that a common function (|lookup|) could no longer be used for all
file formats. This would allow (e g) the message tokens in an application
resources files to refer not only to text defined in the applications own
Messages file, but also to text defined by modules that the application was
going to use. This means that the resources exported by a module become part
of its programming interface; this seems entirely reasonable. It implies
that an application has to make some kind of initial call to a module that
it will use: this may be undesirable.

   (Maybe this whole module is a Bad Thing, since it encourages data from
all kinds of places to appear in the same table: it might be better for an
application to maintain its own resources only, and to let each of the
modules/shared libraries it uses take care of their own resources as they
wish. This wouod lose a lot of the flexibility described above, however.)
