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 the platform default file and the personal configuration file.

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.

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

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 this section .

<?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>

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.

<?xml version="1.0"?>
 
<jmax>
  <preferences>
    <abstractionPath url="jmax://home/abstractions"/>
  </preferences>
</jmax>

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).

<?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>

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:

jmax://core/packages

• It is the place where the builtin packages are stored.

http://www.jmax-phoenix.org/repository

• A global package repository hosted by the jmax-phoenix.org site (the jMax Phoenix project site).

http://jmax.mycompany.com/repository

• 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.

<?xml version="1.0"?>
 
<jmax>
  <preferences>
    <defaultFont name="SansSerif" size="12"/>
  </preferences>
</jmax>

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.

<?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>

These are parameters for the DSP execution. Check 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.

<?xml version="1.0"?>
 
<jmax>
  <preferences>
    <ui name="ide">
  </preferences>
</jmax>

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.

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

<?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>

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.

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 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.

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.

<?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>

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.

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.