How to create a custom User Interface

jMax Phoenix allows to define easily new user interface organisation using the XML configuration files. This page document the way this can be done.

Before getting in the details, it is important to define a few basic concepts.

• User interface component: we use this term to identify a single user interface element, as a patch editor, a browser, a tool, etc.
• Style : The various possible used interface are organised around main styles, that define the ways jMax organise the various ui component. Currently, there are two style defined, the multiwindow style, where each ui component get its own windows, and multisplit, where all the ui component are organised in a single window.
• Container : in the multisplit style, the application window is divided in a number of contiguous sub-windows, called containers able to contains and organise other ui components. Currently, three containers are defined: simple, that can contains only one component; desktop that include multiple components as independent windows within a virtual desktop; tabbed that stack multiple components and use tabs to switch from one to the other.
• Layout : is a geometrical division of the main window area in sub-areas, that can hosts containers. In jMax, the layout is defined as a row (or a column) of areas, each of it can be a container recursively defined as a column (or row) of areas.
• Tool : a tool is a user interface component that is instantiated only once. For example, the find panel, the patch browsers and so on are tools.
• Editor : an editor is a user interface component associated to some data instance, and can be instantiated once for each data instance present. For example, the patch editor, or a sequencer editor, that can exists for each patch or sequencer loaded.

In jMax Phoenix, a user interface configuration is a description of the style to use, a description of the layout and containers, if appropriate, and the description of the tools to open, and a description of the menus available in the user interface.

Layout and containers can only be described for the multisplit style.

Open editors are not technically part of the user interface configuration, they are opened by the package providing the patch and object data to open, but in practice a package may define a user configuration and open a patch in it (see below for a complete example).

The following is a complete example of a basic configuration.

<ui name="exampleUI"
    documentation="An example of UI configuration"
    style="multisplit"
 
    <layout>
      <row>
        <container name="leftArea" weight="0.1" type="simple"/>
        <colum weight="0.9">
          <container name="workspace" weight="0.8" type="desktop"/>
          <container name="bottomArea" weight="0.2" type="simple"/>
        </column>
      </row>
     </layout>
 
    <tool name="Console" container="bottomArea"/>
    <tool name="Project Browser" container="leftArea"/>
 
    <menu name="Tools">
       <tool name="Find Panel"/>
    </menu>
</ui>

The following list explains each XML element referring to the example.

• ui : Define a user interface style. It have a number of sub elements, described below, and the following attributes.
  • name : the name of the user interface style. It is used in the preferences to select this user interface at startup.
  • documentation : a one line text describing the user interface
  • style : can be multisplit for a splitted, single window user interface, or multiwindow for a classical multiple windows user interface.
• layout : subelement of ui. Must be present when the style is multisplit; it defines the layout of the single window. Its content is a tree composed by rows, columns and containers, that are leafs of the tree. At each level of the tree, the available space is divided between the node children, according to their weight attribute.
  • row : sub element of layout. Divide the space assigned to it in a row of components; each component can be either a column, a row or a container. It support the following attributes.
    • weight : a float value between 0 and 1. Request to the parent a fraction of the available space corresponding to the weight. Can be omitted if this is the only child of the parent.
  • column : sub element of layout. Divide the space assigned to it in a column of components; each component can be either a column, a row or a container. It support the following attributes.
    • weight : a float value between 0 and 1. Request to the parent a fraction of the available space corresponding to the weight. Can be omitted if this is the only child of the parent.
  • container : sub element of layout : host a container in the space assigned to it. Attributes are the following.
    • weight : a float value between 0 and 1. Request to the parent a fraction of the available space corresponding to the weight. Can be omitted if this is the only child of the parent.
    • name : the name of this container. The name is used to identify the container when opening tools or patches. Some names have a special meaning, see below.
    • type : the type of the container. It can be simple, desktop or tabbed.
• tool : sub element of ui. open a tool in a container. It support the following attributes.
  • name : The name of the tool. Tool names are provided by the tool implementation and cannot be changed. A user package including a Java module may declare more Tools. The list of available tools depends on the jMax version, and is defined below.
  • container : The container where to open the tool.
• menu : define a global menu. Note that currently only the “Tools” menu can be defined in this way. It support the following attributes.
  • name : the name of the menu. Current release support only the name “Tools”. Other menus can be defined but they will be ignored.
  • tool : sub element of menu. Specify a tool to be added to the Tools menu.
    • name : the name of the tool.

Two container names have a special meaning:

• statusBar : identify a builtin container included in the Window status bar. Only tools appropriate for the tool bar should be opened in this container.
• workspace : if the user interface define a container called workspace, patches opened by the File→Open menu item will be opened in this container. This container will also works as default container for patches opened from packages without specifing the container.

• Registry : a browser of the internal jMax Registry. Typically used only for debug, but it can help to understand how the configuration system works.
• Fpe Panel : a panel giving infomation on floating point errors occurred in the patch.
• Find Panel : a panel allowing to search patches for keywords.
• Dsp Status : a small tool showing the DSP status, and allowing to switch dsp on and off. Designed for the status bar.
• Control Panel : a panel giving control and visibility on a number of dsp related information.
• Console : the traditional Max console.
• Project Browser : the patcher/packages browser.
• Object Chooser : the object chooser/selector browser.

The following xml snippet correspond to the shipped classic user interface style. You probably prefer to study this snippets looking at the screen shots in userinterface.

  <ui name="classic"
      documentation="The classic jMax UI style"
      style="multiwindow">
 
    <!-- the tool tag open the tool -->
 
    <tool name="Console"/>
 
    <!-- tools with unspecified containers will just be added to the menu -->
 
    <menu name="Tools">
      <tool name="Console"/>
      <tool name="Project Browser"/>
      <tool name="Fpe Panel"/>
      <tool name="Find Panel"/>
      <tool name="Control Panel"/>
      <tool name="Console"/>
    </menu>
  </ui>

The following xml snippet correspond to the IDE Desktop style.

  <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="Project 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 >

The following xml snippet correspond to the Tabbed IDE Desktop style.

  <ui name="tabbedIde"
      documentation="An IDE like style with a tabbed workspace"
      style="multisplit">
 
    <layout>
      <row>
	<leaf name="browserArea" weight="0.1" type="simple" />
	<column weight="0.9">
	  <leaf name="workspace" weight="0.8" type="tabbed"/>
	  <leaf name="toolArea"  weight="0.2" type="tabbed"/>
	</column>
      </row>
    </layout>
 
    <tool name="Console" container="toolArea"/>
    <tool name="Project Browser" container="browserArea"/>
    <tool name="Dsp Status" container="statusBar"/>
 
    <!-- tools with unspecified containers will just be added to the menu -->
 
    <menu name="Tools">
      <tool name="Fpe Panel"/>
      <tool name="Find Panel"/>
      <tool name="Control Panel"/>
      <tool name="Console"/>
    </menu>
  </ui>

For an example of application dependent UI, check the customide example under docs/examples in the jMax Phoenix distribution.