com.wolfram.jlink
Class MathListener

java.lang.Object
  com.wolfram.jlink.MathListener

All Implemented Interfaces:

java.util.EventListener

Direct Known Subclasses:

MathActionListener, MathAdjustmentListener, MathComponentListener, MathContainerListener, MathFocusListener, MathItemListener, MathKeyListener, MathMouseListener, MathMouseMotionListener, MathPropertyChangeListener, MathTextListener, MathVetoableChangeListener, MathWindowListener

public abstract class MathListener
extends java.lang.Object
implements java.util.EventListener

This abstract class is the parent class of all the MathXXXListener classes, which let you trigger a call into Mathematica on the occurrence of a particular event. Developers are encouraged to subclass it for their own "listener" classes that need to call into Mathematica. It handles virtually all of the complexity in creating a listener-type class, including the interaction with Mathematica. Examine the source code for any of the MathXXXListener classes to see how you can subclass this class for your own needs.

Constructor Summary

MathListener()
The constructor that is typically called from Mathematica.

MathListener(KernelLink ml)
Call this version only when you know for sure what link should be used for UI-triggered computations.

MathListener(java.lang.String[][] handlers)
This form of the constructor lets you skip having to make a series of setHandler() calls.

Method Summary

protected Expr	callMathHandler(java.lang.String meth, java.lang.Object[] args) Derived classes call this method from their event handler methods.
protected void	callVoidMathHandler(java.lang.String meth, java.lang.Object[] args) Just like callMathHandler(), except it discards the result of the computation.
protected java.lang.String	getHandler(java.lang.String methName) Allows subclasses to get the name of the Mathematica function assigned to handle the given method.
protected KernelLink	getLink() Gives the link that will be used by this MathListener for computations.
boolean	setHandler(java.lang.String meth, java.lang.String func) Associates the specified Mathematica function with the specified method from the any of the "listener" interfaces implemented by the class.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MathListener

public MathListener()

The constructor that is typically called from Mathematica.

MathListener

public MathListener(KernelLink ml)

Call this version only when you know for sure what link should be used for UI-triggered computations. This is typically only done in a standalone Java program, where there is only one link. It is actually preferable in that case to set StdLink to your link by calling StdLink.setLink() and then use the MathListener constructor that takes no args, as it will pull the link to use out of StdLink.

Parameters:

ml - The link to which computations will be sent when events notifications arrive.

MathListener

public MathListener(java.lang.String[][] handlers)

This form of the constructor lets you skip having to make a series of setHandler() calls. Use this constructor from Mathematica code only.

Parameters:

handlers - An array of {meth, func} pairs associating methods in the derived class with Mathematica functions.

Method Detail

setHandler

public boolean setHandler(java.lang.String meth,
                          java.lang.String func)

Associates the specified Mathematica function with the specified method from the any of the "listener" interfaces implemented by the class.

Parameters:

meth - The method in the "listener" interface (for example, "actionPerformed").

func - The Mathematica function to execute.

Returns:

true if the specified method exists in the interface, false otherwise.

callMathHandler

protected Expr callMathHandler(java.lang.String meth,
                               java.lang.Object[] args)

Derived classes call this method from their event handler methods. It performs the call into Mathematica, invoking the Mathematica function associated (via a previous call to setHandler()) with the given event handler method, and passing it the arguments supplied. The return value is an Expr giving the result of the computation. Don't forget to call dispose() on this Expr after you are done with it. This method will block until the kernel is in a state where it is receptive to calls that _originate_ in Java (meaning that they are not part of a chain of calls that includes a call from Mathematica into Java). Such computations typically arise on the user-interface thread, as a result of some user action (like clicking a button). You need to make sure that the kernel can handle such computations before calling this method. Any of the following is sufficient to guarantee that callMathHandler() will not block:

 - the kernel is running DoModal[]
 - kernel sharing (via ShareKernel[] or ShareFrontEnd[]) is turned on, and the kernel is not busy with some other computation
 - the kernel executes ServiceJava[]
 - somewhere on the stack is a call from Mathematica into Java
 - the program is standalone, not being scripted from a Mathematica session

Parameters:

meth - the name of the event handler method that is being invoked (e.g., "actionPerformed", "windowClosing", "mousePressed", etc.)

args - the arguments to be passed to the Mathematica handler function. The arguments will be sent individually, not as a list. To pass primitive types like integers, wrap them in their corresponding wrapper classes (e.g., new Integer(i)).

Returns:

an Expr giving the result of the computation.

callVoidMathHandler

protected void callVoidMathHandler(java.lang.String meth,
                                   java.lang.Object[] args)

Just like callMathHandler(), except it discards the result of the computation. This is a convenience function for the common case when you are not interested in the Expr result of the call to the handler function in Mathematica.

Parameters:

meth - the name of the event handler method that is being invoked (e.g., "actionPerformed", "windowClosing", "mousePressed", etc.)

args - the arguments to be passed to the Mathematica handler function. The arguments will be sent individually, not as a list. To pass primitive types like integers, wrap them in their corresponding wrapper classes (e.g., new Integer(i)).

Since:

J/Link version 2.0

See Also:

callMathHandler(String, Object[])

getLink

protected KernelLink getLink()

Gives the link that will be used by this MathListener for computations. Note that the link can change over time, depending on whether the mainLink or uiLink is to be used. If the programmer has manually set a link in the ctor, then that link will always be returned.

getHandler

protected java.lang.String getHandler(java.lang.String methName)

Allows subclasses to get the name of the Mathematica function assigned to handle the given method. This would be used if a subclass wanted to call the handler method manually, instead of delegating to the callMathHandler() method.

Since:

J/Link version 2.0