com.wolfram.jlink
Class MathCanvas

java.lang.Object
  java.awt.Component
      java.awt.Canvas
          com.wolfram.jlink.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.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

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

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

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

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, 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, getPeer, 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, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, 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