Using the xmub library
======================

Concept
-------

The xmub library enables you to specify resources in the resource file
using keywords instead of the real resource values. These keywords are
then replaced with the actual values at run-time.
The translations for the keywords come from a separate file, which can
be different for each application. In this file, resource translations
are specified in named sets, and when the user starts the application,
he selects one or more of these sets to be used for resource
replacement.

File format
-----------

The resource file for the application is written in the normal format,
but resources that shall be replaced at run-time are specified with
keywords instead of their real values.

Example:

MyApp*background:	PaletteBg
MyApp*foreground:	PaletteFg

The mapping file contains the translations for the different keywords.
It is written in the X resource file format, and specifies the name
of a resource set and the keywords. The example below contains two
resource sets, "Arizona" and "Alaska", with translations for the
keywords in the above resource file, plus a default palette that is
used if none of the defined sets is selected.

Arizona.PaletteBg:	sand
Arizona.PaletteFg:	white
!
Alaska.PaletteBg:	snow
Alaska.PaletteFg:	navy blue
!
*.PaletteBg:		blue
*.PaletteFg:		white

An application can have its own resource mapping file, if special
keywords are used, or use the general system mapping file. The mapping
facility looks for a file with the name 'app_class'.map in a
pre-defined path (see the documentation for
xmubResGetMappingFileName). If no such file is found, it looks for the
file "xresource.map" in the same locations. The file search may be
overridden by setting the environment variable XRESOURCE_MAP_FILE to
the mapping file.
Note that without a mapping file, the system does not function
correctly!


Supporting it in the program
----------------------------

The library provides different functions for manipulating the
databases and for adding files, merging databases etc, but there are
also convenience functions if you don't want to mess with the
internals.

The description starts with how to use the individual functions, the
convenience functions are described later on.

The run-time mapping of resources requires that the display database
be set up, and must so be performed after XtOpenDisplay. As some
resources that are mapped may affect the top widget, the mapping must
take place before the first widget is created.

The general steps are the following:

- Set up the locale, the application context and open the display.

- Initialize the resource mapping facility:

    ref = xmubResInitialize( display );

- Add the mapping file. This is done with the function
  xmubResAddMapFile.
  This function may be called several times to add mappings from
  different files, but if called with NULL for a file_name, it will
  add the default file.

- Replace the resources with xmubResReplace or xmubResReplaceKeywords.
  xmubResReplaceKeywords gives the programmer full control over which
  keywords to replace and leave out, and whether to replace substrings
  or not. xmubResReplace has a simpler interface and is recommended
  for use, since it contains defaults that enable the user to control
  substring replacement via the resource file.
  The function runs two passes. The first pass replaces only whole
  definitions, and no substrings. If the application resource 
  substringResources is defined, a second pass is run. This pass takes
  the resources defined in substringResources and replaces substrings
  in those definitions. The resource substringDelimiters defines the 
  characters that are recognized as substring delimiters.

  Example:

  MyApp*substringResources:	layout fontList
  MyApp*substringDelimiters:	,:()

  With the definition above, xmubResReplace would replace substrings
  only in resource specifications ending with "layout" or "fontList".
  The characters ",:()" would be recognized as substring delimiters.
  If a valid keyword would occur as part of a labelString, it would
  not be replaced.

  Unless there are compelling reasons to use xmubResReplaceKeywords,
  stick to xmubResReplace. If you don't, try to implement the user
  functionality in the example anyway. This enables the user to
  control the replacement.

- Merge the replaced resource into the display database with
  xmubResMergeMappedResources.


To simplify things, the convenience function xmubInitResourceMapping
has been created. It initializes the resource mapping facility, reads
in the default file, replaces the keywords according to the
xmubResReplace description, and merges the replacements into the
display database. 

Since the requirement is that the function must be called after the
display is opened, but before the first widget is created,
XtAppInitialize cannot be used. We provide the convenience function
xmubAppInitialize, which does everything that XtAppInitialize does,
plus that the resource mapping is done at the right place.
The function that is called internally is xmubInitResourceMapping.

Resources and options
---------------------

The names of the resource sets that are used must be defined in an
array that is supplied to the mapping facility. It contains name and
class of the application resources that are used to define resource
sets. A default array is supplied in xmub_resource_sets. It contains
the definitions 
  { { "palette", "Palette" }, { "fmap", "Fmap" } }

As these are application resources, they may be set in different ways.
To enable the definition on the command line, options have to be added
to the XtOpenDisplay call. A default array is provided for this,
xmub_options. It contains the mapping from "-palette" to the resource
"*palette" and from "-fmap" to the resource "*fmap".




   
