Package com.wolfram.jlink

Class MathCanvas

  • All Implemented Interfaces:
    java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible
    public class MathCanvas
extends java.awt.Canvas
implements java.io.Serializable
    MathCanvas is a class that gives programmers an easy way to display Mathematica graphics or typeset expressions. This class can be used in either Mathematica programs or Java programs. MathCanvas is the AWT counterpart to the Swing-based MathGraphicsJPanel (MathCanvas would have been better named MathGraphicsCanvas). Use a MathCanvas if you are writing an AWT program and a MathGraphicsJPanel if you are writing a Swing program.

    A typical use is in a Mathematica program where you want to display a window that contains a Mathematica graphic or typeset expression. To do this, you would create a MathCanvas, create a Frame to hold it (perhaps a MathFrame), then use the setMathCommand() method to specify a plotting command that will be used by the MathCanvas to create the image to display. One of the sample programs included with J/Link, and described in detail in the User Guide, demonstrates this.

    MathCanvas operates in one of two modes: it either evaluates a command in Mathematica to produce the image to display, or it displays a Java Image that you set directly with the setImage() method. In the latter case, the Mathematica command is ignored and no computations are performed.

    This class is a JavaBean.

    See Also:
    MathGraphicsJPanel, Serialized Form

    • Nested Class Summary

      • Nested classes/interfaces inherited from class java.awt.Canvas

        java.awt.Canvas.AccessibleAWTCanvas

      • Nested classes/interfaces inherited from class java.awt.Component

        java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int GRAPHICS
      Value to be used in setImageType() to specify that the image to be displayed is the graphics output of a plotting command, rather than the typeset result of an arbitrary computation.
      static int TYPESET
      Value to be used in setImageType() to specify that the image to be displayed is the typeset result of an arbitrary computation, rather than the graphics output of a plotting command.

      • Fields inherited from class java.awt.Component

        accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

      • Fields inherited from interface java.awt.image.ImageObserver

        ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

    • Constructor Summary

      Constructors 
      Constructor Description
      MathCanvas()
      The constructor that is typically called from Mathematica.
      MathCanvas​(KernelLink ml)
      You typically use this constructor when using this class in a Java program, because you need to specify the KernelLink that will be used.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.awt.Image getImage()
      Returns the image that is currently being displayed.
      int getImageType()
      Gives the image type this MathCanvas is currently set to display, either GRAPHICS or TYPESET.
      java.lang.String getMathCommand()
      Returns the Mathematica command that is used to generate the image to display.
      boolean getUsesFE()
      Indicates whether this MathCanvas is currently set to use the notebook front end to assist in graphics rendering.
      boolean getUsesTraditionalForm()
      Indicates whether this MathCanvas is currently set to return typeset results in TraditionalForm (vs. the default StandardForm).
      void paint​(java.awt.Graphics g)  
      void recompute()
      If a mathCommand is being used to create the image to display, this method causes it to be recomputed to produce a new image.
      void repaintNow()
      Forces an immediate repainting of the image.
      void setImage​(java.awt.Image im)
      Allows you to directly specify an Image to display, rather than evaluating the mathCommand.
      void setImageType​(int type)
      Specifies whether the canvas should display an image produced from a graphics function, or the typeset result of a computation.
      void setLink​(KernelLink ml)
      Sets the link that will be used for computations.
      void setMathCommand​(java.lang.String cmd)
      Specifies the Mathematica command that is used to generate the image to display.
      void setUsesFE​(boolean useFE)
      Specifies whether to use the services of the Mathematica front end in rendering the image to display.
      void setUsesTraditionalForm​(boolean useTradForm)
      Specifies whether typeset output is to be rendered in TraditionalForm or StandardForm.
      void update​(java.awt.Graphics g)  

      • Methods inherited from class java.awt.Canvas

        addNotify, createBufferStrategy, createBufferStrategy, getAccessibleContext, getBufferStrategy

      • Methods inherited from class java.awt.Component

        action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, revalidate, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setMixingCutoutShape, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • GRAPHICS

        public static final int GRAPHICS
        Value to be used in setImageType() to specify that the image to be displayed is the graphics output of a plotting command, rather than the typeset result of an arbitrary computation.
        See Also:
        setImageType(int), Constant Field Values

      • TYPESET

        public static final int TYPESET
        Value to be used in setImageType() to specify that the image to be displayed is the typeset result of an arbitrary computation, rather than the graphics output of a plotting command.
        See Also:
        setImageType(int), Constant Field Values

    • Constructor Detail

      • MathCanvas

        public MathCanvas()
        The constructor that is typically called from Mathematica.

      • MathCanvas

        public MathCanvas​(KernelLink ml)
        You typically use this constructor when using this class in a Java program, because you need to specify the KernelLink that will be used. Alternatively, you can use the no-arg constructor and later call setLink() to specify the link.
        Parameters:
        ml - The link to which computations will be sent.

    • Method Detail

      • setLink

        public void setLink​(KernelLink ml)
        Sets the link that will be used for computations. This method is only called in Java programs (the correct link back to the kernel is automatically established for you when using this class from Mathematica).
        Parameters:
        ml -

      • setImageType

        public void setImageType​(int type)
        Specifies whether the canvas should display an image produced from a graphics function, or the typeset result of a computation. The possible values are GRAPHICS and TYPESET. The default is GRAPHICS. This method does not trigger an update of the image--you must call setMathCommand() or recompute() to see the effects of the new setting.
        Parameters:
        type - the type of output you want, either GRAPHICS or TYPESET

      • getImageType

        public int getImageType()
        Gives the image type this MathCanvas is currently set to display, either GRAPHICS or TYPESET.

      • setUsesFE

        public void setUsesFE​(boolean useFE)
        Specifies whether to use the services of the Mathematica front end in rendering the image to display. The default is false. Some reasons why you might want to set this to true: 
             - You want your graphics to contain typeset expressions (e.g., in a PlotLabel)
     - The front end generally does a nicer job than the alternative method
 Some reasons why you might want to leave this false:
     - It is simpler and more direct to not use the front end if you do not need it
     - The front end needs to be running (usually not a problem if you are using
       this class from a Mathematica program); it will be launched if it is not
       already running. There some implications for this that are discussed in the
       section on Mathematica graphics in Part 2 of the User Guide.
        If you use setImageType() to specify TYPESET, then the front end will always be used, no matter what you specify in setUsesFE(). This method does not trigger an update of the image--you must call setMathCommand() or recompute() to see the effects of the new setting.
        Parameters:
        useFE -

      • getUsesFE

        public boolean getUsesFE()
        Indicates whether this MathCanvas is currently set to use the notebook front end to assist in graphics rendering.

      • setUsesTraditionalForm

        public void setUsesTraditionalForm​(boolean useTradForm)
        Specifies whether typeset output is to be rendered in TraditionalForm or StandardForm. The default is false (uses StandardForm). This is only relevant when setImageType() is used to specify typeset output (as opposed to graphics output). This method does not trigger an update of the image--you must call setMathCommand() or recompute() to see the effects of the new setting.
        Parameters:
        useTradForm -

      • getUsesTraditionalForm

        public boolean getUsesTraditionalForm()
        Indicates whether this MathCanvas is currently set to return typeset results in TraditionalForm (vs. the default StandardForm). This is only relevant when setImageType() has been used to specify typeset output (as opposed to graphics output).

      • setMathCommand

        public void setMathCommand​(java.lang.String cmd)
        Specifies the Mathematica command that is used to generate the image to display. For graphics output, this will typically be a plotting command, such as "Plot[x,{x,0,1}]". For typeset output, any expression can be given; its result will be typeset and displayed. Note that it is the result of the expression that is displayed, so do not make the mistake of ending the expression with a semicolon, as this will make the expression evaluate to Null. This is especially important with graphics--many Mathematica expressions will produce plots as a side effect, but you must supply an expression that evaluates to a Graphics expression (or Graphics3D, SurfaceGraphics, etc.)

        You may find it more convenient to define the command in Mathematica as a function and then specify only the function call in setMathCommand(). For example, when using this class from a Mathematica program, you might do: 

             plotFunc[] := Plot[...complex plot command...];
     myMathCanvas@setMathCommand["plotFunc[]"];
        Parameters:
        cmd -

      • getMathCommand

        public java.lang.String getMathCommand()
        Returns the Mathematica command that is used to generate the image to display.

      • setImage

        public void setImage​(java.awt.Image im)
        Allows you to directly specify an Image to display, rather than evaluating the mathCommand. Once setImage() is called, the mathCommand is ignored and no computations are performed until the next call to setMathCommand().

        Use setImage() when you have created an Image in Mathematica or Java yourself. An example of this is if you manually create a Java bitmap image from a Mathematica array. This is demonstrated in the User Guide.

        Parameters:
        im - the Image to display
        See Also:
        setMathCommand(String)

      • getImage

        public java.awt.Image getImage()
        Returns the image that is currently being displayed.

      • recompute

        public void recompute()
        If a mathCommand is being used to create the image to display, this method causes it to be recomputed to produce a new image. Call recompute() if your mathCommand depends on values in Mathematica that have changed since the last time you called setMathCommand() or recompute().

      • repaintNow

        public void repaintNow()
        Forces an immediate repainting of the image. Similar to the standard repaint() method, except that with repaint(), the painting may be delayed if the user-interface thread is very busy. This method is intended to be called from Mathematica code, most likely after setMathCommand(), setImage(), or recompute(). Because several calls between Mathematica and Java are typically required to establish a new image to display, and these calls are comparatively time-consuming, on slower machines it may be the case that calls to repaint() do not trigger painting to occur often enough to provide smooth visual feedback (for example, when the image is being recomputed as the mouse is being dragged). The repaintNow() method is provided for such circumstances.

      • update

        public void update​(java.awt.Graphics g)
        Overrides:
        update in class java.awt.Canvas

      • paint

        public void paint​(java.awt.Graphics g)
        Overrides:
        paint in class java.awt.Canvas