====== The Content of the configuration files ======

This section give an overview of the main configuration file, that you can
find in ''jmax/config/jmax.xml''.
In most of the case, you will not need to modify it, you'll extend
the configuration declared in the personal ''~/.jmax.xml'' file.
The file is roughly divided in sections.

==== Include section ====


Include the platform default file and the personal configuration file.

==== Preference section ====

It include a number of preferences allowing an easy configuration of jMax.
Typically in this section we select between configuration objects defined
elsewhere, and give simple parameters.

Preferences can be defined/redefined in your personal configuration file
or in the main configuration file if appropriate; for example, in a machine
used by multiple users, setting the proxy (see below) in the main configuration
file make sense, because it is  configuration always needed by all 
the users.

The following are the elements supported.

<code xml>
<?xml version="1.0"?>

<jmax>
  <preferences>
    <require package="mypackage"/>
    <require package="otherpackage"
             url="jmax://home/myotherpackage.jpkg"
     />
    <require ladspa="ladspa-plugin"/>
  </preferences>
</jmax>
</code>

The require tag in the preferences section allows to specify resources to be loaded at init time.
Resources can be a package, identified by name, or specified with a full jmax URL, or a LADSPA library.

Please notes that packages specified in this section in your personal configuration file are loaded
before the user interface is created; this allows to specify here packages that define their own user
interface. The other way to load a package before the user interface start is to specify it in the jmax
command line.

Please not also that this is not the recommended way to load a ladspa plugin, even if it is the fastest
and simples for testing purpose. For a full discussion of the subject check [[ HandlingLADSPAPlugins | this section ]].


<code xml>
<?xml version="1.0"?>

<jmax>
  <preferences>
    <proxy host="myproxy.mycompany.com"
	   port="8080"
           nonProxyHosts="jmax.mycompany.com|jmax2.mycompany.com|*.intranet.mycompany.com" />
  </preferences>
</jmax>
</code>

Tell jmax to use a proxy for accessing network package repositories 
(see the chapter about using packages for details about loading 
packages from the web).
The ''host'' and ''port'' attribute give the host name and port number
for the connection to use, and the ''nonProxyHost'' attribute give
a list of patterns, separated by vertical bars; host names matching the
patterns are looked up locally on the network and not thru the proxy.
This xml tag just give access to the standard Java proxy parameters, that
can also be passed to the command line if needed. Check the Java virtual
machine documentation for futher details.

<code xml>
<?xml version="1.0"?>

<jmax>
  <preferences>
    <abstractionPath url="jmax://home/abstractions"/>
  </preferences>
</jmax>
</code>

Declare a directory where to load abstractions. Multiple declarations
are supported.

Please notes that this declaration is intended to support a rapid 
prototyping environment, but it is **not** encouraged on packaged
abstraction libraries. 

In packaged libraries, each abstraction should be individually declared,
with its documentation and tooltip. This also significatively improve
the loading time of a patch. See the package configuration page for further
details.

This declaration is typically included in the personal include file.
If you think of including this declaration in the main configuration
file in order to share a common abstraction library, then you should **really**
instead think of packaging the common abstraction library as a jMax
package, and putting it in a http local repository (see below).


<code xml>
<?xml version="1.0"?>

<jmax>
  <preferences>
    <packages>
      <path url="jmax://core/packages"/>
      <path url="http://www.jmax-phoenix.org/repository"/>
      <path url="http://jmax.mycompany.com/repository/"/>
    </packages>
  </preferences>
</jmax>
</code>

A jMax package is a packaged librariy of jMax resources, like
abstractions, objects, editors and so on.

The jMax Package system allows to look for packages in multiple
directories **and** in network repositories.

The ''packages'' tag in the ''preferences'' section allows to specify
package related preferences. Currently only one tag is supported ''path'' that
allows to add a place where to look for packages by specifing the ''url'' attribute;
this attribute may be a standard ''http'' URL or a jMax URL.

The above example specify three path: 
<file>jmax://core/packages</file>
  * It is the place where the builtin packages are stored.
<file>http://www.jmax-phoenix.org/repository</file>
  * A global package repository hosted by the ''jmax-phoenix.org'' site (the jMax Phoenix project site).
<file>http://jmax.mycompany.com/repository</file>
  * A company local repository, where locally developed packages can be shared.

This tag is specified on the main configuration file to include
the core packages (first tag of the example) only; the declaration for
the jMax Phoenix is included by commented out (waiting for actually having
a real repository, for now only the infrastructure is in place).

You may add new path in the main configuration file in case of
a multi user installation, or for preparing a master installation
for multiple machines, or you can add paths in the personal
configuration file, tipically to configure your personal development 
environment.

Please note that by changing the core path declaration, you may force
jMax Phoenix to do not use the builtin package set. If you know what you
are doing, this is fine, for example to substitute the builtin objects
with alternative implementations.


<code xml>
<?xml version="1.0"?>

<jmax>
  <preferences>
    <defaultFont name="SansSerif" size="12"/>
  </preferences>
</jmax>
</code>

This set the default font for the user interface.  Each editor may
then set its own font or use the default font.  The font name must be
a font understood by the Java virtual machine.  In order to have
portable font names, the Java virtual machine use logical font names,
that are remapped to actual fonts existing in the running environment.
While Java can use also actual font names, jMax Phoenix for the moment
limits himself to the logical font names. For a complete list,
check the ''Font'' menu under the patch editors.

The font is set in the main configuration file as a default, and
can be redefined in the personal configuration file if needed.

<code xml>
<?xml version="1.0"?>

<jmax>
  <preferences>
    <fts>
      <param name="samplig_rate" type="int" value="44100"/>
      <param name="vector_size"  type="int" value="256"/>
      <param name="fifo_size"    type="int" value="256"/>
    </fts>
  </preferences>
</jmax>
</code>

These are parameters for the DSP execution.
Check [[XXXXX|this section]] for full documentation.
They are set in the main configuration file to normal
defaults, and can be redefined in the personal configuration
file if needed.

<code xml>
<?xml version="1.0"?>

<jmax>
  <preferences>
    <ui name="ide">
  </preferences>
</jmax>
</code>


The ''ui'' tag in the ''preferences'' section select which user interface,
between those defined, is to be used by jMax Phoenix.

The global configuration file set a default value that can be modified by
the personal configuration file. This default value can be changed for
a multi user machine or for a master installation image.

Please note that this preference is currently taken in account only at
startup time, so if it is changed by a configuration file loaded after
start up (for example, a package configuration file) the change will
have no effect on the running user interface.


==== User Interface Section ====


The user interface section define a set of user interface configuration to be
used. Check the [[XXXX | user interface ]] section for details and
documentation of the syntax. Here we just give an example of an user 
interface definition.


<code xml>
<?xml version="1.0"?>

<jmax>
  <ui name="ide"
      documentation="An IDE like style with a virtual desktop workspace"
      style="multisplit">
    <layout>
      <row>
	<leaf name="browserArea" weight="0.1" type="simple" />
	<column weight="0.9">
	  <leaf name="workspace" weight="0.8" type="desktop"/>
	  <leaf name="toolArea"  weight="0.2" type="tabbed"/>
	</column>
      </row>
    </layout>

    <tool name="Console" container="toolArea"/>
    <tool name="Browser" container="browserArea"/>
    <tool name="Dsp Status" container="statusBar"/>

    <menu name="Tools">
      <tool name="Fpe Panel"/>
      <tool name="Find Panel"/>
      <tool name="Control Panel"/>
      <tool name="Console"/>
    </menu>
  </ui >
</jmax>
</code>

This XML fragment define a user interface configuration called ''ide'' (that is the default
configuration).

More user interface definition can be added either in the main configuration
file, or in the personal configuration file, for example for an application
specific user interface.

==== The core Package section ====

This section define the ''core'' package, that is the package loaded
at startup time.

The syntax of this section is the same as for all the other package declarations,
check the [[XXXX|relative documentation]].

The core package define the basic builtin objects, and load
a set of packages at startup.

In principle, the core package object declarations should not be
modified, but the ''require'' list can be modified if you want
a different set of packages loaded by default.

Please notes that package definitions cannot be modified after
the package has been loaded: as a result, the core package can be
customized by the user configuration file, but not by other packages.

==== Editors Sections ====


This section allows the configuration fo the various jMax editors.

The main configuration file include only the configuration of the 
patch editor, that it is than extended by the packages loading 
objects.

It include a first part that define graphic customisations (that
are not yet functional, neither stable, so are not documented),
and a second part defining the content of the patch editor
toolbar.

<code xml>
<?xml version="1.0"?>

<jmax>
  <editors>
    <patcher>
      <tool object="frobber"
	    icon="jmax://myPackage/images/redFrobber.gif"
	    message="Adding A Red Frobber"
	    toolTipText="A Red Frobbert>
	  <property name="color" type="string" value="red"/>
      </tool>	       		  
      <tool object="frobber"
	    icon="jmax://myPackage/images/blueFrobber.gif"
	    message="Adding A Blue Frobber"
	    toolTipText="A Blue  Frobbert>
	  <property name="color" type="string" value="blue"/>
      </tool>	       		  
    </patcher>
  </editors>
</jmax>
</code>

This XML fragment add two tools at the toolbar, 
inserting a red frobber and a blue frobber object (supposing to
know what a frobber is.

Each ''tool'' tag add a tool to the end of the toolbar.
Its ''object'' attribute describe the object to add; it can be
the string you would type within an object box. For example,
''int 10'' or ''trigger i i i'' are perfectly admissible descriptions.

The ''icon'' attribute specify the icon to use in the toolbar; 
since the same object can be added multiple times to the toolbar
with different arguments or properties, the toolbar do not reuse
the default icon object, but require to explictly specify the
icon to be used.

The ''message'' attribute is a string that will be shown in the 
status bar while adding the object.

The ''toolTipText'' attribute is the text that will be shown in 
a tooltip when mousing over the tool in the toolbar.

The ''property'' subtag allows to specify an arbitrary number
of properties for newly created object; in this case, we suppose
the frobber object understand the property ''color'', and we 
set its value to the string "red" or "blue". The semantic
of this property is completely object dependent, but there
are a number of standard properties, like font names
and font size, that can be also used. Check the object
documentation for details. Properties are usually persistent.

Please note that the syntax for declaring tools is subject to
changes, in case of evolutions of the toolbar.

Usually this configuration tag is only used in new packages
defining new objects. It may be used in the personal
configuration file for debugging purpose, for example.
If you really want to configure your environemnt deeply,
may be the best would be to define a configuration package and
load it at start-up time.

Modifying the main configuration file patch editor configuration
may make impossible to define basic objects. So, do it only
if you know what you are doing.


==== System Section ====


The system section configure a number of system mechanisms.
It is not documented, and you are not supposed to modify it.
It can actually be useful to add tags in the system
section only if you are developing Java extensions.

In this case, ask for help in the development mailing list.