mxj~
Java in MSP
Description
The mxj~ object (and its Max equivalent mxj) instantiate specially-written Java classes and acts as a Max-level peer object, passing data that originates in Max to the Java object and vice versa.
Discussion
The form that an mxj~ object takes -- the number of inlets, outlets and the messages it understands -- is determined by the Java class that it instantiates. Unlike the Max mxj object, the mxj~ object is able to perform operations on signal vectors in an MSP processing chain. Using mxj~ requires that the host computer have a recent version of the Java Virtual Machine (JVM) installed. Macintosh users can ensure that they have the most up-to-date version of the JVM by running Software Update from the System Preferences.
By default, neither Mac M1 machines nor Windows XP have a version of the JVM installed. As of the writing of this document the most recent version of the JVM can be downloaded from this
link.
Max includes a directory called "java-doc", which can be found on Windows machines at
C:\Program Files\Common Files\Cycling '74\java-doc
and on Macintosh machines at
/Applications/Max*/java-doc
The following important subdirectories are in the java-doc directory:
"classes" - contains the source code and class files of the example Java classes that are included with Max.
"help" - contains the help files that are associated with the example Java classes. Exploring these patches is a good, quick way to see how mxj~ has extended and will extend the Max universe.
"doc/tutorial" - contains a step-by-step tutorial that leads you through the process of creating your first Java class to the application of advanced mxj~ programming techniques. The tutorial is in HTML format.
"doc/api" - contains html files that specify mxj~ 's Application Programming Interface (API). These pages will serve as an invaluable resource when you are coding your own Java classes.
"doc/ide" - contains example projects for some of the Integrated Development Environments (IDEs) we think you may want to use to create Java classes.
"doc/mxj~ examples" - contains example classes for signal processing
"lib" - contains the code libraries that the mxj~ object uses to bridge the worlds of Max and Java.
In addition, a file named "max.java.config.txt" is also located in the java directory. This file allows you to specify which diretories should be in Java's classpath - a concept roughly analogous to the Max search path.
Arguments
Java-class[symbol]
optional
The mxj~ object must be given the name of a valid Java class as the first argument. The Java class file must exist somewhere within the classpath, and it must be a class that was designed for use with the mxj~ object (the class must subclass com.cycling74.max.MaxObject). The number of inlets that an instance of mxj~ creates and the messages that it will respond to are determined by declarations made in the peer Java class.
attributes[list]
optional
The mxj~ object supports the definition of attributes within the Java code for a peer class. The attributes that are settable at the time of instantiation using the @ paradigm. For instance, if a particular class Foo defined an integer attribute called intBar, one could create an instance of the class with the attribute set to the value 74 by typing mxj~ Foo @intBar 74 in an object box.
Attributes
Common Box Attributes
annotation[symbol]
Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.
background[int]: 0
Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.
color[4 floats]
Sets the color for the object box outline.
fontface[int]
Sets the type style used by the object. The options are:
plain
bold
italic
bold italic
Possible values:
0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'
fontname[symbol]
Sets the object's font.
fontsize[float]
Sets the object's font size (in points).
Possible values:
'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'
hint[symbol]
Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.
ignoreclick[int]: 0
Toggles whether an object ignores mouse clicks in a locked patcher.
jspainterfile[symbol]
You can override the default appearance of a user interface object by assigning a JavaScript file with code for painting the object. The file must be in the search path.
patching_rect[4 floats]: 0. 0. 100. 0.
Sets the position and size of the object in the patcher window.
position[2 floats]
write-only
Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.
presentation[int]: 0
Sets whether an object belongs to the patcher's presentation.
presentation_rect[4 floats]: 0. 0. 0. 0.
Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.
rect[4 floats]
write-only
Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).
size[2 floats]
write-only
Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.
textcolor[4 floats]
Sets the color for the object's text in RGBA format.
textjustification[int]
Sets the justification for the object's text.
Possible values:
0 = 'left'
1 = 'center'
2 = 'right'
varname[symbol]
Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.
Messages
bang
Function depends on Java class instantiated
int
Function depends on Java class instantiated
- input
[int]
float
Function depends on Java class instantiated
- input
[float]
list
Function depends on Java class instantiated
- input
[list]
anything
Function depends on Java class instantiated
- input
[list]
benchmark
The word benchmark , followed by a zero or one and a number that specifies a posting interval (number of executions of the perform method), disables benchmarking the mxj~ object's perform method, posting into the Max Console. The default is zero (disabled)
- benchmark-flag
[int]
- post-interval
[int]
(mouse)
Double-clicking with the mouse on the mxj~ object displays its contents as text in an editing window which the user can modify.
exceptioncheck
The word exceptioncheck , followed by a zero or one, disables/enables Java exception checking in the mxj~ object's perform method. The default is zero (disabled).
- exception-flag
[int]
get
The word get followed by an attribute-name will post the attribute value in the Max window.
- attribute-name
[list]
viewsource
The viewsource message brings up a text editor window and loads the source code for the peer Java object. If the source code is not in the same directory as the peer class's .java file, a decompilation of the class file is attempted and the resulting decompiled source is presented. From within the editor window it's possible to make edits to the source, save the file, and recompile the class.
zap
When a zap message is sent to an mxj~ object with Java peer class Foo, the next mxj~ object that's instantiated with the same peer Java class Foo (ie typing "mxj Foo" in an object box) will cause the class to reload itself from disk. This is most useful in a programming context: if one makes a change to Foo.java and recompiles a new Foo.class the zap message allows one to create an instance of the new class without having to quit and restart the Max environment. Without sending the zap message Max would simply use the cached definition of the class that was loaded when a Foo object was instantiated prior to the changes being made.
Output
various
The number of outlets that an instance of mxj~ creates is determined by declarations made in the constructor of the peer Java class. The furthest outlet to the right may or may not be an info outlet whose sole responsibility is to report information about the attributes when queried.
See Also
| Name | Description |
|---|---|
| mxj | Execute Java in Max |