com.cycling74.max
Class MaxSystem

java.lang.Object
  extended by com.cycling74.max.MaxSystem

public class MaxSystem
extends java.lang.Object

Collection of functions relating primarily to interaction with the Max environment and other information about the environment mxj is executing within.


Field Summary
static int PATH_STYLE_COLON
          Used with the nameConform method.
static int PATH_STYLE_MAX
          Used with the nameConform method.
static int PATH_STYLE_NATIVE
          Used with the nameConform method.
static int PATH_STYLE_NATIVE_WIN
          Used with the nameConform method.The Windows backslash path style (not recommended for outletting, since the backslash is a special character in Max).
static int PATH_STYLE_SLASH
          Used with the nameConform method.The cross-platform path style used by Max 4.3 and later.
static int PATH_TYPE_ABSOLUTE
          Used with the nameConform method.Do not use a path type.
static int PATH_TYPE_BOOT
          Used with the nameConform method.A path relative to the boot volume
static int PATH_TYPE_C74
          Used with the nameConform method.A path relative to the Cycling 74 app support folder.
static int PATH_TYPE_IGNORE
          Used with the nameConform method.Do not use a path type.
static int PATH_TYPE_RELATIVE
          Used with the nameConform method.A path relative to the Max application folder.
 
Constructor Summary
MaxSystem()
           
 
Method Summary
static void defer(Executable fn)
          Defer the execution of fn to the low priority cue.
static void deferFront(Executable fn)
          Defer the execution of fn to the front of the low priority queue regardless whether or not the calling thread is the low or high priority thread(scheduler).
static void deferLow(Executable fn)
          Defer the execution of fn to the back of the low priority queue regardless whether or not the calling thread is the low or high priority thread(scheduler).
static void deferMedium(Executable fn)
          Defer the execution of fn to the back of the low priority queue if the calling thread is the high priority thread(scheduler).
static boolean doGetIsRuntime()
           
static void error(java.lang.String message)
          Post an error message to the Max console.
static java.lang.String[] getClassPath()
           
static java.lang.String getDefaultPath()
          Get the absolute path of the current default directory of the Max application.
static short getMaxVersion()
          Get the version number of the Max system.
static int[] getMaxVersionInts()
          A utility method to get the current version of max as an array of ints.
static java.lang.String getPreferencesPath()
          Get the absolute path of the preferences directory of the Max application.
static java.lang.String[] getSearchPath()
          Get the current Max search path list as an array of Strings where each String is an absolute path to a directory in the current Max search path.
static java.lang.String[] getSearchPathForContext()
          Get the contextual Max search path list as an array of Strings where each String is an absolute path to a directory in the contextual (project- or collective-specific) search path.
static java.lang.String[] getSystemClassPath()
           
static void hideCursor()
          Hide the cursor via native OS call.
static boolean inMainThread()
           
static boolean inMaxThread()
           
static boolean inTimerThread()
           
static boolean isOsMacOsX()
           
static boolean isOsWindows()
           
static boolean isRuntime()
           
static boolean isStandAlone()
           
static void loadObject(java.lang.String objname)
          Force loads a max external for things like Jitter Java support.
static java.lang.String locateFile(java.lang.String filename)
          Get the absolute path of first file named filename found in the MAX search path
static java.lang.String maxPathToNativePath(java.lang.String maxpath)
          Convert a max style path (vol:/path/to/some/file) to a path native to the current OS.
static java.lang.String nameConform(java.lang.String filename, int style, int type)
          change format of a path from one style/type to another.
static void nextWindowIsModal()
          This is a workaround for a bug in swing on OSX jaguar.
static java.lang.String openDialog()
          Shows an open file dialog using the Max API.
static java.lang.String openDialog(java.lang.String prompt)
          Shows an open file dialog using the Max API.
static void ouch(java.lang.String message)
          Put up an error window.
static void post(java.lang.String message)
          Post a message to the Max console.
static void registerCommandAccelerator(char c)
          The interaction between Max/MSP and Swing/AWT Frames is a bit complex on OS X.
static void registerCommandAccelerators(char[] c)
          The interaction between Max/MSP and Swing/AWT Frames is a bit complex on OS X.
static java.lang.String saveAsDialog(java.lang.String prompt, java.lang.String default_filename)
          Shows a save as..
static void schedule(Executable fn, double abs_time)
          Schedule the execution of fn at an absolute time in the future by the high priority thread.
static void scheduleDefer(Executable fn, double delay)
          Creates a clock to execute at some time in the future.
static void scheduleDelay(Executable fn, double delay)
          Schedule the execution of fn delay millis from now by the high priority thread.
static boolean sendMessageToBoundObject(java.lang.String sym_name, java.lang.String msg, Atom[] args)
          This method provides and easy way for mxj objects to communicate with other max objects or libraries written in C by passing messages.
static void showCursor()
          Show the cursor via native OS call.
static double sysTimerGetTime()
           
static void unregisterCommandAccelerator(char c)
          Unregister a command accelerator.
static void unregisterCommandAccelerators(char[] c)
          Unregister command accelerators.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PATH_STYLE_MAX

public static final int PATH_STYLE_MAX
Used with the nameConform method. As of version 4.3, Max's path style is the slash style. Max style paths are of the form vol:/path/to/file

See Also:
Constant Field Values

PATH_STYLE_NATIVE

public static final int PATH_STYLE_NATIVE
Used with the nameConform method. This is the path style native to the operating system.

See Also:
Constant Field Values

PATH_STYLE_COLON

public static final int PATH_STYLE_COLON
Used with the nameConform method. The Mac OS 9 path style used by Max 4.1 and earlier.

See Also:
Constant Field Values

PATH_STYLE_SLASH

public static final int PATH_STYLE_SLASH
Used with the nameConform method.The cross-platform path style used by Max 4.3 and later.

See Also:
Constant Field Values

PATH_STYLE_NATIVE_WIN

public static final int PATH_STYLE_NATIVE_WIN
Used with the nameConform method.The Windows backslash path style (not recommended for outletting, since the backslash is a special character in Max).

See Also:
Constant Field Values

PATH_TYPE_IGNORE

public static final int PATH_TYPE_IGNORE
Used with the nameConform method.Do not use a path type.

See Also:
Constant Field Values

PATH_TYPE_ABSOLUTE

public static final int PATH_TYPE_ABSOLUTE
Used with the nameConform method.Do not use a path type.

See Also:
Constant Field Values

PATH_TYPE_RELATIVE

public static final int PATH_TYPE_RELATIVE
Used with the nameConform method.A path relative to the Max application folder.

See Also:
Constant Field Values

PATH_TYPE_BOOT

public static final int PATH_TYPE_BOOT
Used with the nameConform method.A path relative to the boot volume

See Also:
Constant Field Values

PATH_TYPE_C74

public static final int PATH_TYPE_C74
Used with the nameConform method.A path relative to the Cycling 74 app support folder.

See Also:
Constant Field Values
Constructor Detail

MaxSystem

public MaxSystem()
Method Detail

defer

public static void defer(Executable fn)
Defer the execution of fn to the low priority cue. If the calling thread is the low priority thread fn is executed immediately. Defer places the task on the front of the low priority queue. In some instances this behavior can result in the reversal of scheduled tasks. In these cases use deferLow if that is not the desired behavior.

Parameters:
fn - is the instance of Executable to be executed by the low priority thread.

deferLow

public static void deferLow(Executable fn)
Defer the execution of fn to the back of the low priority queue regardless whether or not the calling thread is the low or high priority thread(scheduler). Thus ordering of tasks is always preserved.

Parameters:
fn - is the instance of Executable to be executed by the low priority thread.

deferMedium

public static void deferMedium(Executable fn)
Defer the execution of fn to the back of the low priority queue if the calling thread is the high priority thread(scheduler). Otherwise, execute fn immediately.

Parameters:
fn - is the instance of Executable to be executed by the low priority thread.

deferFront

public static void deferFront(Executable fn)
Defer the execution of fn to the front of the low priority queue regardless whether or not the calling thread is the low or high priority thread(scheduler).

Parameters:
fn - is the instance of Executable to be executed by the low priority thread.

schedule

public static void schedule(Executable fn,
                            double abs_time)
Schedule the execution of fn at an absolute time in the future by the high priority thread.

Parameters:
fn - is the instance of Executable to be executed by the scheduler thread.
abs_time - the absolute time when at which fn should be executed.

scheduleDelay

public static void scheduleDelay(Executable fn,
                                 double delay)
Schedule the execution of fn delay millis from now by the high priority thread.

Parameters:
fn - is the instance of Executable to be executed by the scheduler thread.
delay - the offset in millis from now at which fn should be executed.

scheduleDefer

public static void scheduleDefer(Executable fn,
                                 double delay)
Creates a clock to execute at some time in the future. When the clock executes, it calls defer (hence creating a qelem to execute at low priority).

Parameters:
fn - is the instance of Executable to be executed by the scheduler thread.
delay - the offset in millis from now at which fn should be executed.

inMaxThread

public static boolean inMaxThread()
Returns:
true if the calling thread is either the max main application (low priority) thread or the max scheduler(high priority) thread.

inTimerThread

public static boolean inTimerThread()
Returns:
true if the calling thread is the max scheduler (high priority) thread.

inMainThread

public static boolean inMainThread()
Returns:
true if the calling thread is the max main (low priority) thread.

showCursor

public static void showCursor()
Show the cursor via native OS call.


hideCursor

public static void hideCursor()
Hide the cursor via native OS call.


nextWindowIsModal

public static void nextWindowIsModal()
This is a workaround for a bug in swing on OSX jaguar. Swing dialogs cause the app to become stuck in a modal state. If you call this function before showing the showing dialog the app is able to recover properly.


sendMessageToBoundObject

public static boolean sendMessageToBoundObject(java.lang.String sym_name,
                                               java.lang.String msg,
                                               Atom[] args)
This method provides and easy way for mxj objects to communicate with other max objects or libraries written in C by passing messages. Objects must be bound to the s_thing of a global symbol generated via a call to gensym. Messages cannot be declared as A_CANT since typedmess is used for the dispatching. Returns true on success, false otherwise. IN C:
 
                void main(void)
                {
                        ...blah 
                        addmess((method)my_obj_setstate, "setstate", A_GIMME, 0)
                        ..blah
                }
         
                t_my_obj *x;
                blah blah...
                gensym("__my_special_lib__")->s_thing = (t_object *)x;
 
IN JAVA:
                private static final String LIBNAME = "__my_special_lib__";
                private static final int STATE_INIT = 0;
                private static final int STATE_ACTIVE = 1;
                
                blah blah..
                
                public void setBackendState()
                {
                        Atom[] args = new Atom[1];
                        args[0]= Atom.newAtom(STATE_INIT);
                        boolean res = MaxSystem.sendMessageToBoundObject(LIBNAME,"setstate",args);
                        ...
                }
 
Args can be null if message takes no arguments.

Parameters:
sym_name - the symbol to which the object is bound
msg - the message to pass
args - arguments to pass with the message
Returns:
true if message was sent successfully.

openDialog

public static java.lang.String openDialog()
Shows an open file dialog using the Max API.

Returns:
full path of file to open, returns null if cancelled.

openDialog

public static java.lang.String openDialog(java.lang.String prompt)
Shows an open file dialog using the Max API.

Parameters:
prompt - message to display in dialog.
Returns:
full path of file to open, returns null if cancelled.

saveAsDialog

public static java.lang.String saveAsDialog(java.lang.String prompt,
                                            java.lang.String default_filename)
Shows a save as.. file dialog using the Max API.

Parameters:
prompt - message to display in dialog.
default_filename - default file chosen when dialog is shown.
Returns:
full path of location to save to, returns null if cancelled.

locateFile

public static java.lang.String locateFile(java.lang.String filename)
Get the absolute path of first file named filename found in the MAX search path

Parameters:
filename - file to look for in Max search path
Returns:
absolute path of first file found named filname in Max search path.

getDefaultPath

public static java.lang.String getDefaultPath()
Get the absolute path of the current default directory of the Max application.

Returns:
The current default directory of the Max application.

getPreferencesPath

public static java.lang.String getPreferencesPath()
Get the absolute path of the preferences directory of the Max application.

Returns:
The preferences directory of the Max application.

getSearchPath

public static java.lang.String[] getSearchPath()
Get the current Max search path list as an array of Strings where each String is an absolute path to a directory in the current Max search path.

Returns:
The search path list of the Max application.

getSearchPathForContext

public static java.lang.String[] getSearchPathForContext()
Get the contextual Max search path list as an array of Strings where each String is an absolute path to a directory in the contextual (project- or collective-specific) search path.

Returns:
The contextual search path list of the current special context, if available.

nameConform

public static java.lang.String nameConform(java.lang.String filename,
                                           int style,
                                           int type)
change format of a path from one style/type to another.

Parameters:
filename - old path
style - path style
type - path type
Returns:
altered path String

maxPathToNativePath

public static java.lang.String maxPathToNativePath(java.lang.String maxpath)
Convert a max style path (vol:/path/to/some/file) to a path native to the current OS.

Parameters:
maxpath - the path to convert
Returns:
String that repesents path native to the current OS

sysTimerGetTime

public static double sysTimerGetTime()

getMaxVersion

public static short getMaxVersion()
Get the version number of the Max system. The version is encoded as follows: For example, if the lower bits are x406, this is Max version 4.0.6.

Returns:
encoded version of Max application.

isRuntime

public static boolean isRuntime()
Returns:
true if we are running inside of the max runtime as opposed to the Max/MSP application.

isStandAlone

public static boolean isStandAlone()
Returns:
true if we are running inside of a standalone app as opposed to the max runtime or Max/MSP.

getMaxVersionInts

public static int[] getMaxVersionInts()
A utility method to get the current version of max as an array of ints.

Returns:
three element integer array: [major, minor, update]

doGetIsRuntime

public static boolean doGetIsRuntime()

isOsWindows

public static boolean isOsWindows()
Returns:
true if we are running in Windows.

isOsMacOsX

public static boolean isOsMacOsX()
Returns:
true if we are running in OS X.

getSystemClassPath

public static java.lang.String[] getSystemClassPath()
Returns:
the system classpath i.e the immutable classpath as an array of Strings

getClassPath

public static java.lang.String[] getClassPath()
Returns:
sys and dynamic classpath as an array of Strings.

registerCommandAccelerators

public static void registerCommandAccelerators(char[] c)
The interaction between Max/MSP and Swing/AWT Frames is a bit complex on OS X. This method provides a workaround for Max/MSP allowing your Swing/AWT frame based interface to have a menu which responds to hotkeys. This is how the mxj editor accomplishes its behavior with regards to command-w closing an editor window and command-o opening a file open dialog etc. Max needs to know which menu items to disable on itself when your AWT/Swing interface is in focus. This method allows you to specify which command key accelerators max should disable in its own application menus when your custom AWT/Swing frame has focus.
 // from MXJEditor.java
 // call before frame is visible.
 private static final char[] __accs = new char[] { 'X', 'C', 'V', 'S', 'Z', 'O',
                'N', 'W', 'F', 'G', 'H', 'L', 'K', 'D' };
 com.cycling74.max.MaxSystem.registerCommandAccelerators(__accs);
 

Parameters:
c - array of command accelerators.

registerCommandAccelerator

public static void registerCommandAccelerator(char c)
The interaction between Max/MSP and Swing/AWT Frames is a bit complex on OS X. This method provides a workaround for Max/MSP allowing your Swing/AWT frame based interface to have a menu which responds to hotkeys. This is how the mxj editor accomplishes its behavior with regards to command-w closing an editor window and command-o opening a file open dialog etc. Max needs to know which menu items to disable on itself when your AWT/Swing interface is in focus. This method allows you to specify a command key accelerator that max should disable in its own application menus when your custom AWT/Swing frame has focus. For instance if you need to respond to cmnd - o(mac) or cntrl-o(pc) you would register char 'o'. That way your window would get the cmnd-o instead of the Max application which would cause Max to open a file open dialog.

Parameters:
c - command accelerator to disable when your AWT/Swing Frame has focus.

unregisterCommandAccelerators

public static void unregisterCommandAccelerators(char[] c)
Unregister command accelerators.

Parameters:
c - array of command accelerators

unregisterCommandAccelerator

public static void unregisterCommandAccelerator(char c)
Unregister a command accelerator.

Parameters:
c - the command accelerator

post

public static void post(java.lang.String message)
Post a message to the Max console.

Parameters:
message - the String to post in the Max console.

loadObject

public static void loadObject(java.lang.String objname)
Force loads a max external for things like Jitter Java support.

Parameters:
objname - the String of the max object name.

error

public static void error(java.lang.String message)
Post an error message to the Max console.

Parameters:
message - the String to post as an error to the Max console.

ouch

public static void ouch(java.lang.String message)
Put up an error window. Extremely annoying. Should probably never be used. I'm not even sure why we support it.

Parameters:
message - the text to display in the error window.