jMax jMax documentation

the explode editor

The aim of the explode editor editor is to represent the data contained in an explode object. It is activated with a double-click on the corresponding object in the patcher.

The data contained in an explode is essentially a collection of events, caracterized by a starting time and a set of MIDI parameters. Every event consists of:

  • starting time, in msec
  • duration in msec
  • pitch as MIDI note (0-128)
  • velocity as MIDI velocity (0-128)
  • channel as MIDI channel (0-16)

The explode editor allow the visualization of events under a "piano-roll" representation.

A setting panel, that can be retrieved by selecting the options->settings menu, allows the user to choose the association between the score parameters and the graphic parameters of the events.

The toolbar

It contains the tools selectable by the user: every tool as an associated icon and name, and once selected, it is active until next tool's selection.

The toolbar has a floating behaviour: it can be dragged away from the status bar, so that it can stand into an independent window. When floating, the toolbar can be dragged again in the place from where it was extracted.

The toolbar in explode is unique, i.e. there is just one explode toolbar active in every moment; if a second explode window is opened while the toolbar is anchored into a window, the toolbar will be moved in the second window. This (sort of non-standard) UI behaviour is under testing, and will be eventually fine-tuned in the next releases.

Selecting a new tool in the toolbar results in selecting the same tool for all the currently opened explode windows. The new icon's tool is also shown in the status bar of every window.

See later for a description of the tool's behaviour.

The status bar

This component, placed in the top of the window, show the following informations:

  • the currently active tool
  • The tool's messages (depending on the tool, it can be coordinates, or offsets, or other informations meaningfull for the current operation)
  • a set of fields for the editing of single parameters of (a group of) events: time, pitch, duration, velocity, channel.

The value fields indicate the parameters of the curently selected event, if one (and just one) is selected. In the other cases, the fields are empty. Entrering a value in a field (i.e. typing a value and hit the return/enter key) changes the value of the specified parameter for all the current selected events.

The score panel

The central area of the window contains the piano roll representation of the events in the data base. The vertical grid indicates time values along the x-axis, while the horizontal grid indicates parameter values (for the 0-127 parameters). As we will see later in the settings panel paragraph, the parameter associated to the y axis can be choosen by the user, as well as almost every other graphic parameter of the events.

In the left side of the window, a vertical keyboard shows the pitch associated to an event, during moving, resizing and adding operations. This is true even when the y axis does not represent the pitch; moving an event along the y axis when this axis is associated with the velocity, will show in the keybord the pitch of the moving note (that of course will not move)...

Every event is represented as a line with the following graphic parameters:

  • An x position, always associated to the initial time of the event. This value takes into account the current zooming factor.
  • An y position, that can be associated to the pitch, duration, velocity, channel parameters via the setting panel. The default setting associates y to pitch.
  • A length, that can be associated in the usual way to pitch, duration, velocity, channel. The default setting associates the length to the duration.
  • A label, that can be associated in the usual way to pitch, duration, velocity, channel. The default setting associate the label to the pitch.
  • A color, that always represent the selected (red) or unselected (black) state of the event.
The tools

The initial, default tool for the explode editor is the selecter (the arrow).

Arrow tool

The tasks of the Arrow are the following:

  • Selection: clicking (and releasing) the mouse on an object selects it, and at the same time deselects all the other selected ones. SHIFT-click on an object adds it to the current selection. Click and drag the mouse starting in an empty area of the score deselects all the selected objects and draws a selection rectangle following the mouse movements. At mouse up, the objects that intersect the rectangle will be selected. SHIFT-select area does not deselect the currently selected ones: it just add the objects to the current selection.
  • Moving: clicking and dragging the mouse on a selected object dinamically moves the selected object(s). The move is always constrained to be vertical or horizontal: the first mouse move will identify the direction of move (see also the mover tools). Please note that since the y parameter (vertical) can be assigned to a parameter other then the pitch, moving an object along the y axis can be used to modify every parameter of an event (except the starting time). Moving cannot produce negative values (time for horizontal movements, or the ssigned parameter for the vertical movements). Upper clipping is implemented just for the channel parameter, whose maximum value is 15.

Adder tool

This tool, whose icon is a little note, allows entering new notes in the explode data base. The status bar reports the current position of the mouse in terms of starting time and y parameter, after having made all the necessary coordinate conversions and zooms.

Clicking in the score with the adder tool adds a note of the specified time, y-parameter values.

Since just two parameters can be specified in a mouse click (x, y positions), the newly added note will have just two parameters specified: the remaining will be assigned use the following default values

  • Pitch = 64
  • Velocity = 64
  • Duration = 100 msec
  • channel = 0

Example:

In the default configuration where x parameter = time, y parameter = pitch, length parameter = duration and label parameter = pitch, adding a new note will produce an event in the score with

  • time = <x of the click>
  • pitch = <y of the click>
  • duration = 100
  • velocity = 64
  • channel = 0

Eraser tool

The icon of this tool is a little blue eraser gum. The status bar reports the current mouse coordinates (time, y parameter).

Clicking on an event with the eraser deletes it from the data base. If the note was selected, the click erases all the selection (please remember that in explode the undo/redo is unlimited...)

Vertical and Horizontal mover tools

These tools are used to move selections of objects. Their icons are double vertical/horizontal red arrows with a black circle (a little note) in the middle. The only difference between a mover tool and the moving capability of the arrow tool is the direction of movement, that is fixed for these specific movers.

Resizer tool

This tool allows the resizing (changing the length) of a selection of object. Its icon is a thick horizontal black line with two red arrows at both ends.

The resizer, as well as the arrow, is a selection based tool; it allows the user to specify a selection of objects (as explained in the Arrow tool paragraph) on which to perform the resize operation.

Clicking on a selected event dynamically resizes the lenght of every event in the selection. Please note that since the lenght parameter can be assigned to a parameter other then the duration, changing the length of an event can be used to modify every parameter of an event (except the starting time). Resizing cannot produce negative values for the length.

Note also that, since the length and the y can be assigned to the same parameter (example, the velocity), resizing an event could result in changing also its y position, and vice-versa...

Zoomer tool

This tool allows the changing of the x zoom factor of the current representation. A click everywhere in the score multiply the current zoom factor by two, while an ALT-click divide the zoom factor by the same amount. Note that a more fine tuned zoom can be achieved via the zoom slider at the bottom of the window.

Zoom and scroll sliders

Since the x-axis is always associated with time, scrolling the score panel always means moving the initial time of the representation's window. The little zoom slider on the right allows the specification of a x zoom factor, whose range is bottom limited at 1%. The zoom affects the x conversion algorithm and it is not a time zooming; the length of the represented events will change after a zoom even if this length is not associated to the duration. This behaviour will be eventually revised in future versions.

The settings panel

This panel is composed by a set of rows of radio buttons, where each row represents a graphic parameter, and each column an event's (score) parameter. The aim of this panel is to specify wich parameters will be represented with which graphic appearence. Only one "score" parameter (pitch, duration, velocity, channel) can be represented by a given graphic parameter (y, lenght, label) . On the other side, the same score parameter can be represented by more then one graphic parameter.

In this version, only the "Cancel" button in the panel is active, because the modifications are reported immediately in the score and there's no need to explicitly "apply" them.