As jMax and other Max environments share a common paradigm, part of the graphic appearance is the same, and using jMax patch editor will be easy for a user that already has experience with another version of Max.

In jMax Phoenix the patch editor has been cleaned up, the various mouse and keyboard interaction has been changed for coherency with modern standards, and a contextual menu has been added.

As a consequence, the editor is simpler to use for anybody that use any standard graphical user interface, but if you were used to the jMax UI, you may need to take a look to this document.

Since the jMax patch editor is also the frame work for some graphical controllers it supports two modes: edit and lock.

Edit mode : the toolbar is shown and objects can be added, connected, and edited. in the patcher window.

Lock mode : the patch can not be edited and the graphical controllers are active.

The two modes select different backgrounds for the patcher editor, by default a marble texture for edit mode and a gradient for lock mode.

The edit/lock button, that is the first button of the toolbar, indicate the current mode, and can be used to switch from one mode to the other.

It is also possible to switch mode using the CTRL-E key or using the contextual menu. Note that customised application may not show the toolbar in lock mode; in this case the alternative ways of switching mode can be used to switch to edit mode.

In edit mode, a graphical controller can be activated by clicking on it with the ALT key pressed.

The toolbar is shown at the top of the windows; the toolbar is always visible in edit mode, and it is usually visible in lock mode (but can be hided by custom applications).

In lock mode the toolbar contains at the left the lock/edit button, and at the extreme right, only for bnon top level patchers, a button to open its parent patcher.

In edit mode a palette for adding objects is added; the exact content of the palette is release specific and depends on the installed packages, and can be configured using the installation, user or package XML configuration file.

Refer to the object reference and help patch for further information about the objects.

To add an object, click first on the palette on the object you want to add, and then click on the patcher in the place you want to add the object. To add multiple objects, keep the control key pressed while clicking on the position you want to add the object in; as long as the CTRL key is pressed, you can add new objects of the same type.

Keying a function key will also create an object under the mouse position. The F1 key will create the first object in the tool bar, F2 will create the second object and so on.

Connecting two objects can be is done by clicking on an outlet or an inlet, then dragging or moving the mouse to an inlet or outlet. The connection is done when releasing (if dragging) or clicking (if moving) on an inlet (resp. an outlet).

To do multiple connections to/from the same inlet/outlet, use clicking and not dragging, and keep the control key pressed while clicking on the outlet/inlet to connect. As long as the CTRL key is pressed, you can add more connection to the same inlet/outlet.

To delete a connection you can select it and delete with Cut or with the Delete key; you can delete all the connections starting or ending to an inlet/outlet by typing Delete while the inlet/outlet is highlighted.

Selecting an object or a connection works in the way most users would expect.

Clicking on an object select it. Shift clicking or control clicking on an object will add the object to the selection or remove it if it was already there.

Dragging a rectangle will select the objects that intersect with the rectangle. Dragging a rectangle with the Shift or Ctrl modifier will add to the selection the objects that intersect with the rectangle or remove them if already there.

Normally, if the source and destination of a connection are selected, the connection is automatically selected.

You can select a single connecting by clicking on it, and you can add or remove a single connection to the selection by SHIFT-clicking or CTRL-clicking on it.

Copy/cut/paste is obtained either via the “Edit” menu, the contextual menu, or via menu shortcuts. The position of the pasted object(s) is always offsetted down and right from the original copied object(s).

Editing text inside objects is done by clicking on a selected object. I.e. to edit an object text, first click once to select it, than reclick to edit the text (just like changing the filename on a OS desktop).

The text cursor will be positionned at the click's position. Selecting one word can be done by double-click in text, selecting whole text can be done by triple-click in text.

Text editing can be terminated either by clicking outside the object, or by typing the “End” or the key. The ENTER key will end editing on the single line objects and add a new line on a multi line object like the message box.

While editing a standard jMax object, a completion menu will popup under the object, listing the existing objects that match the typed name. Clicking on the menu will complete the object name and continue the editing.

Moving a selection is obtained with the usual click-and-drag behavior. One moved, an object will remain selected.

Resizing can be started from the right or bottom side of the object by dragging from the resize sensibility area (cursor is changed to resize cursor when mouse is in this area).

Resizing is always constrained: horizontal only for text objects and number/float boxes; both direction together for the squared objects like bang, toggle, inlet and outlet; horizontal OR vertical for the slider, depending on the chosen area.

Right clicking on the background or on a selected object will popup a contextual menu, including operations on the selection like opening, cut/copy/paste, align, and a couple of patcher level operations like Select all or lock/unlock.

If only one object is selected, the menu allows to open the object property inspector. Currently only a few objects support a property inspector. Also, in the short term future, the property inspector will be part of the ui framework, and not dynamically popped up, and this menu item will disappear.

Help on a selection of objects can be obtained via the help menu, or via F1 key (the “Help … on object” menu shortcut).

The help menu gives also access to summary patches, that present an overview of the objects offered by a package.

Mousing over objects and objects inlets and outlets will produce short messages documenting the object and the inlets/outles on the status bar.

The patcher error signal errors in objects by painting them in a different color (currently, red); typing Ctrl-Z will give, for each error object, a short explanation message; if the selection is active, the message will be shown only for the selected error objects.

Warning: on a short term future release, the error message will be shown in the status bar while mousing over the object.

The patcher object, which can be instantiated from the objet palette in the toolbar, can be used in order to group objects to a subpatcher embedded in the patcher. A patcher object can behave like any other object, it can have in- and outlets and can be parameterized by arguments.

The first value typed to the patcher object (a symbol) is it's name. Double clicking on the patcher object opens another patcher window where the content of the patcher can be edited. Inlets and outlets can be added inside with the inlet and outlet object from the palette in the toolbar.

The inlets and outlets of a patcher are numbered, starting from 0. The index correspond to the position of the inlet or outlet on the patcher object. A new inlet (outlet) object instantiated gets the lowest index which is not used yet by another inlet (outlet). Copying an inlet (outlet) creates an inlet (outlet) with the same index.

A patcher may contain several inlets (outlets) having same number. In this case, they receive the same data (in undefined order) from the same connection connected to the patcher object.

The index of an inlet (outlet) index can be changed via a pop-up menu obtained by double-clicking on the object.

The inlet (outlet) object with the greatest index determines the number of inlets (outlets) of the patcher (which is it's index plus one).

(Note that the index of an inlet or outlet is a characteristic of this object and not a function of the it's geometric position in the patch like in MAX/ISPW)

Please refer to the language section of this documentation for further information about patchers, variables and templates.

Comment usually show simple unformatted text.

jMax Phoenix do not support iconic comments; generic support for images and other document in a patcher will be reintroduced in a future release.

You can change the color used to flash a button, using a pop-up menu that you can get by double clicking on the button.

Opening the editor associated to an object is done by a double-click on the object. The object class determines what editor will be loaded (i.e. the patcher editor for a patcher or a template instance, the table editor for a table, the explode editor for an explode, etc.)

The following keyboard commands are currently available:

For copy, cut, paste and duplicate actions, selection can be either objects or text if an object is being edited.

There are a number of mechanism that try to help in critical situations like crashes.

First of all, when jMax save a file, it first rename the original file adding a .backup postfix to its name, and then generate the new copy; this guarantee you to be able to backup to the state of last save (be carefull: the state of last save is not necessarly the initial state of the editing session).

Also, in case of crashes of the DSP engine (fts), the system will try to save all the loaded files and templates, in auto-save files, whose name is generated by appending two '%' character to the original file name; since these files are generated under a critical situation, it is not guaranteed that their content is correct, but in many case they can save the day; please note that an unexpected crash can be generated by a bug in the system or by a bug in an external object, for example during its developement.

In case of crashes of the Java Virtual Machine, it may happen that the computational engine do not crash, and continue to run alone; in this case, you may manually cause a crash in order to get the auto-save files.

In order to do this, you need to know the process id (pid) of the running process called fts; you can find it out using the unix ps command; then, you may kill the process using the unix command kill; refer to the relative manual pages for details.

The lexical conventions of jMax differ slightly from that ones of ISPW Max. Objects loaded from original ISPW patches are converted on the fly to the jMax syntax.

The following ISPW Max objects have been modified in order to provide a compatible behavior:

expr: The object now accepts only one argument, a symbol, that include the complete text of the expression. In general double quotes must be used at the beginning and end of the expression.

message box The message box uses a single quote instead of backslash. It now accepts variables $name.