Package 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

    Constructors 
    Constructor Description
    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

    Modifier and Type Method Description
    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 Details

    • 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 Details

    • 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