vmm.core
Class View

java.lang.Object
  vmm.core.View

All Implemented Interfaces:

java.util.EventListener, javax.swing.event.ChangeListener, Decorateable, Parameterizable

Direct Known Subclasses:

Mandelbrot.MandelbrotView, ODE_2D.ODEView, PlaneCurveParametric.PlaneCurveParametricView, RepeatedSegmentFractal.RSFView, View3D

public class View
extends java.lang.Object
implements Parameterizable, Decorateable, javax.swing.event.ChangeListener

A View represents one of possibly several views of an Exhibit. A View displays its Exhbit in a Display. These three classes are the central classes in VMM. Drawing takes place when the View's render(Graphics2D, int, int) method is called. Note that this might potentially be called to draw the Exhibit to other destinations besides a Display, such as to the graphics device associated with a printer.

This top-level View class might be used directly for simple two-dimensional Exhibits, but it is also likely to be used as a base class for customized Views for particular Exhibits or types of Exhibits. In particular, a specialized View class will be used for 3D views.

The View class contains several methods that can be used for drawing, such as drawCurve(Point2D[]), setColor(Color), and drawPixel(double, double).

Note that to work correctly with the XML save/restore facility defined in SaveAndRestore, a subclass of View must have a parameterless constructor, and it must be an independent class or a public nested class.

Field Summary

protected ActionRadioGroup	backgroundCommands Used for setting the background color of this View, this contains three commands for black background, white background, and custom background.
protected Animation	buildAnimation
protected boolean	buildingImageForFilmstrip This variable was introduced to handle a specific special case: when an image is created asynchronously over a period of time, as in ray-traced views of implicit surfaces.
protected java.awt.Graphics2D	currentGraphics When an exhibit is being drawn, this variable is set to the graphics context where the exhibit is being drawn.
protected java.util.ArrayList<Decoration>	decorations Decorations that have been added to this view.
protected boolean	directOffscreenDrawing This is set to a true by beginDrawToOffscreenImage() when a direct off-screen drawing operation is initiated.
protected java.awt.image.BufferedImage	fullOSI An offscreen image that is used for drawing.
protected boolean	needsRedraw Used to determine when the off-screen image needs to be redrawn.
protected int	offscreenImageType The type parameter used for creating athe offscreen image -- this is reset in View3DLit when black and white image is selected.
protected java.util.ArrayList<Parameter>	parameters Parameters that have been added to this View.
protected AbstractActionVMM	showAxesAction The action for setting the showAxisProperty, which is one one of the commands returned by getViewCommands().

Constructor Summary

View()

Method Summary

void	addDecoration(Decoration d) Add a decoration that will appear in this View only.
void	addExtraXML(org.w3c.dom.Document containingDocument, org.w3c.dom.Element viewElement) This method is called when an XML representation of this view is being constructed by the SaveAndRestore class to give the View a chance to add any extra infomation that is not saved by default.
protected void	addParameter(Parameter param) Associate a parameter with this view.
boolean	beginDrawToOffscreenImage() This method, along with endDrawToOffscreenImage(), allow you to draw directly to this view's off-screen image, if there is one.
void	clearDecorations() Remove all decorations from this View.
protected void	clearOSI() Fills the offscreen image with the background color of this View.
protected Axes2D	createAxes() Create an "Axes" decoration that can be added to this view.
protected void	createOSI(int width, int height) This method is called whenever an off-screen image needs to be created.
protected void	doDraw(java.awt.Graphics2D g) This method is called by the render method when the Exhibit in this View needs to be redrawn.
void	drawCurve(java.awt.geom.Point2D[] points) Draws a curve through all the points in an array by calling drawCurve(points,points.length)
void	drawCurve(java.awt.geom.Point2D[] points, int pointCount) Draws a curve in the current drawing context.
void	drawCurve(java.awt.geom.Point2D[] points, int pointIndexStart, int pointIndexEnd) Draws a curve in the current drawing context.
void	drawDot(java.awt.geom.Point2D pt, double diameter) Draws a dot of specified diameter centered at a specified point.
void	drawLine(double x1, double y1, double x2, double y2) Draws a line in the current drawing context.
void	drawLine(java.awt.geom.Point2D pt1, java.awt.geom.Point2D pt2) Draws a line in the current drawing context.
void	drawLineDirect(int x1, int y1, int x2, int y2) Draws a line in the current color between points that are specified using pixel coordinates.
void	drawPixel(double x, double y) Draws a point by turning on a single pixel.
void	drawPixel(java.awt.geom.Point2D pt) Draws a point by turning on a single pixel.
void	drawPixelDirect(java.awt.Color color, int x, int y) Sets the pixel with pixel coordinates (x,y) to be a specified color.
void	drawPixels(java.awt.geom.Point2D[] points, int pointIndexStart, int pointIndexEnd) Draws a list of pixels in the current drawing context, where the pixels are specified in object coordinates.
void	drawString(java.lang.String s, double x, double y) This can be called during drawing to draw a string at a specified point, given in window (real x,y) coordinates.
void	drawString(java.lang.String s, java.awt.geom.Point2D xyCoords) This can be called during drawing to draw a string at a specified point, given in window (real x,y) coordinates.
void	endDrawToOffscreenImage() This method, along with beginDrawToOffscreenImage(), allow you to draw directly to this view's off-screen image, if there is one.
void	fillRectDirect(int x, int y, int width, int height) Draws a filled-in rectangle in the current color, where the rectangle is specified in pixel coordinates.
void	finish() This method is called by the Display that contains this View, just before the view is removed from the display.
protected void	finishOSIDraw() This is called when drawing to the off-screen image is finished, to give it a chance for clean-up.
void	forceRedraw() Force the Exhibit to be completely redrawn.
ActionList	getActions() Generates a list of "Action commands" that can be applied to this View.
ActionList	getActionsForViewAndExhibit() Returns a list containing Action commands for this View and for the Exhibit that is contined in this View.
ActionList	getAdditionalAnimations() This method returns a list of ActionItem that will be added to the Animation menu of the 3dxm applicaiton.
ActionList	getAdditionalAnimationsForViewAndExhibit() Returns the combined contents of the lists obtained from getAdditionalAnimations() and Exhibit.getAdditionalAnimationsForView(View).
boolean	getAntialiased() Returns the value of the antialiased property.
boolean	getApplyGraphics2DTransform() Returns the value of the applyGraphics2DTransform property.
java.awt.Color	getBackground() Gets the background color used when rendering this view.
java.awt.Color	getColor() Returns the drawing color of the current graphics context.
Decoration[]	getDecorations() Returns a list of decorations that have been added to this View
MouseTask	getDefaultMouseTask() Returns a MouseTask that can be installed in the Display attached to this View.
Display	getDisplay() Returns the Display where this View is installed.
Exhibit	getExhibit() Get the Exhibit that is shown in this View.
boolean	getFastDrawing() Tells whether the Exhibit should be drawn as quickly as possible.
java.awt.Color	getForeground() Get the foreground color used for rendering this view.
java.awt.image.BufferedImage	getImage(boolean alwaysCopy) Get a buffered image that contains the picture shown on this View's display.
java.lang.String	getName() Returns a name for this View.
Parameter	getParameterByName(java.lang.String name) Returns a paramter that has been added to this View and that has the specified name.
Parameter[]	getParameters() Returns an array containing all the parameters associated with this View.
boolean	getPreserveAspect() Returns the value of the preserveAspect property.
double[]	getRequestedWindow() Get the window that was originally requested in setWindow.
ActionList	getSettingsCommands() Generates a list of "Settings commands" that can be applied to this View.
ActionList	getSettingsCommandsForViewAndExhibit() Returns a list containing Settings commands for this View and for the Exhibit that is contained in this View.
boolean	getShowAxes() Returns the value of the showAxes property.
java.lang.String	getStatusText() This method is called by the display to determine what message to show in the status bar when this view is active.
java.lang.String	getTitle() Returns a human-readable title for this View that could, for example, be used in a menu that is presented to the user.
Transform	getTransform() Returns the transform that is used when drawing this View.
Parameter[]	getViewAndExhibitParameters() Returns an array of Parameters containing those that have been added to the Exhibit (if any) that is displayed in this view, followed by those that have been added to this view.
ActionList	getViewCommands() Returns a list of "view commands" that can be applied to this View.
double[]	getWindow() Returns a four-element array containing the limits of the window for this View in the xy-plane, assuming that an Exhibit has been installed in the View.
protected boolean	needsNewOSI(int width, int height) This is called by render to check whether a new offscreen image needs to be created, given the specified width and height of the drawing area.
void	parameterChanged(Parameter param, java.lang.Object oldValue, java.lang.Object newValue) This method will be called automatically when a parameter that has been added to this View is changed.
protected java.awt.Graphics2D	prepareOSIForDrawing() Prepare the offscreen image for drawing and return a graphics context for drawing to it.
protected void	putOSI(java.awt.Graphics2D g, int width, int height) This is called by render to copy the offscreen image to the screen.
void	readExtraXML(org.w3c.dom.Element viewInfo) This method is called when this View is being reconstructed from an XML representation by the SaveAndRestore class.
void	removeDecoration(Decoration d) Remove a specified decoration from this View, if present.
protected void	removeParameter(Parameter param) Removes a parameter from this View.
void	render(java.awt.Graphics2D g, int width, int height) This method is called to draw this View's Exhibit.
void	setAntialiased(boolean antialiased) If the antialiased property is true, then antialiasing is enabled in the Graphics2D objects that are used to draw this View's exhibit.
void	setApplyGraphics2DTransform(boolean applyGraphics2DTransform) If the applyGraphics2DTransform property is set to true, then a transformation will be applied to the Graphics2D objects that are used to draw this View's Exhibit.
void	setBackground(java.awt.Color c) Set the background color that will be used for rendering this view.
void	setColor(java.awt.Color c) This method will set the color in the current graphics context.
void	setDisplay(Display display) Sets the Display where this View is installed.
void	setExhibit(Exhibit exhibit) Set the Exhibit that is shown in this View.
void	setFastDrawing(boolean fast) Sets the fastDrawing property, which tells whether the Exhibit should be drawn as quickly as possible.
void	setFastDrawing(boolean fast, boolean redrawSynchronizedViews) Sets the fastDrawing property, which tells whether the Exhibt in this View should be drawn as quickly as possible.
void	setForeground(java.awt.Color c) Set the foreground color to be used for rendering this view.
void	setName(java.lang.String name) Sets the name for this view.
void	setPreserveAspect(boolean preserveAspect) If the preservAspect property is set to true, then the 2D window requested for the View is adjusted so that the shape of the rectanglar window in the xy-plane has the same aspect ratio as the rectangle of pixels to which the view is being drawn.
void	setShowAxes(boolean show) If set to true, an Axes decoration is added to the View.
void	setStrokeSizeMultiplier(int pixels) Sets the width of the stroke used for drawing lines and curves in the current graphics context to have a width equal to a specified number of pixels.
void	setTransform(Transform transform) Sets the transform for this view to a specified transform, with no error checking.
void	setWindow(double[] window) Sets the window in the xy-plane for this View.
void	setWindow(double xmin, double xmax, double ymin, double ymax) Sets the rectangular "window" in the xy-plane for this View.
void	stateChanged(javax.swing.event.ChangeEvent evt) A View listens for state change events that are generated when the Exhibit or Decoration that it is displaying is changed, or by the transform (that converts real coords to pixel coords).
void	takeExhibit(View view, boolean shareTransform) Sets the exhibit of this View equal to the same Exhibit that is displayed by another specified View.

Methods inherited from class java.lang.Object

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

Field Detail

buildAnimation

protected Animation buildAnimation

needsRedraw

protected boolean needsRedraw

Used to determine when the off-screen image needs to be redrawn. This is set to true when forceRedraw() is called, and it is checked and reset to false in render(Graphics2D, int, int).

fullOSI

protected java.awt.image.BufferedImage fullOSI

An offscreen image that is used for drawing.

currentGraphics

protected java.awt.Graphics2D currentGraphics

When an exhibit is being drawn, this variable is set to the graphics context where the exhibit is being drawn. When the exhibit drawing is finished, the value is set to null. This variable is used in some of the rendering methods that are provided by this class and its 3D subclass.

See Also:

render(Graphics2D, int, int)

parameters

protected java.util.ArrayList<Parameter> parameters

Parameters that have been added to this View.

decorations

protected java.util.ArrayList<Decoration> decorations

Decorations that have been added to this view.

buildingImageForFilmstrip

protected volatile boolean buildingImageForFilmstrip

This variable was introduced to handle a specific special case: when an image is created asynchronously over a period of time, as in ray-traced views of implicit surfaces. This variable is used only during morphing of implicit surfaces (or similar cases) to prevent the Display from grabbing an incomplete image and saving it to the Filmstrip of the morph that is being created. The value of this variable is set to true while the image is only partially complete, and is reset to false when the image is complete.

showAxesAction

protected AbstractActionVMM showAxesAction

The action for setting the showAxisProperty, which is one one of the commands returned by getViewCommands(). (This is created along with the View object and is non-null.)

backgroundCommands

protected ActionRadioGroup backgroundCommands

Used for setting the background color of this View, this contains three commands for black background, white background, and custom background. It is one of the objects returned by getViewCommands(). (This is created along with the View object and is non-null.)

directOffscreenDrawing

protected boolean directOffscreenDrawing

This is set to a true by beginDrawToOffscreenImage() when a direct off-screen drawing operation is initiated. It is reset to false when endDrawToOffscreenImage() is called (or when a normal drawing operation begins in render(Graphics2D, int, int)). A subclass could test its value to tell whether direct offscreen drawing is in progress.

offscreenImageType

protected int offscreenImageType

The type parameter used for creating athe offscreen image -- this is reset in View3DLit when black and white image is selected. It is not used at all in anaglyph stereo mode.

Constructor Detail

View

public View()

Method Detail

getName

public java.lang.String getName()

Returns a name for this View. By default, the name that is returned will be the same as the full class name of the class to which the View object belongs. However, a different name can be set using the setName method. The name is intended to be something that can be used internally to distinguish one view from other views of the same Exhibit. For a human-readable name, the getTitle method should be used instead of getName. (In practice, names are rarely used for views.)

See Also:

getTitle()

setName

public void setName(java.lang.String name)

Sets the name for this view.

See Also:

getName()

getTitle

public java.lang.String getTitle()

Returns a human-readable title for this View that could, for example, be used in a menu that is presented to the user. The title is obtained by using the name returned by getName as a key in the method I18n.tr(String). This allows for easy internationalization. Note that if the I18n.tr method does not find a translation for the name, then the title will be the same as the name. (In practice, titles are rarely used for views.)

See Also:

getName(), I18n.tr(String)

getDisplay

public Display getDisplay()

Returns the Display where this View is installed. If it is not installed in a Display, the return value is null.

See Also:

Display.install(View, Exhibit)

setDisplay

public void setDisplay(Display display)

Sets the Display where this View is installed. This method will ordinarily be called only by the install method in the Display class, which is used to install a View into a Display. It is not meant to be called directly (since that would bypass a lot of the set-up performed automatically by the install method).

See Also:

Display.install(View, Exhibit)

getExhibit

public Exhibit getExhibit()

Get the Exhibit that is shown in this View. If no Exibit is currently associated with the view, then the return value is null.

setExhibit

public void setExhibit(Exhibit exhibit)

Set the Exhibit that is shown in this View. If the View is already showing an Exhibit, it is first removed from the View. When an Exhibit is installed, the transform associated with the View is set to the default transform of the Exhibit. If there is a Display associated with the View, its repaint method is called. This setExhibit method will be called automatically when an Exhibit is installed in a Display; although it might be called directly, that would be much less usual since it would by-pass all the set-up that is done automatically by the Display's install method.

If the exhibit is non-null, then the foreground and background colors of the view are set to the default foreground and background colors of the exhibit. If the exhibit is null, then the view's foreground and background are set to black and white.

Note when overriding this method: You should almost certainly start by saying "if (exhibit == getExhibit()) return". That is, in general, this method should do nothing when the exhibit that is being installed is already installed.

Parameters:

exhibit - The exhibit to be installed in this View. The value can be null. In that case, no Exhibit will be associated with the View after the method executes. If exhibit is already installed in this View, then no changes are made.

See Also:

Display.install(View, Exhibit)

finish

public void finish()

This method is called by the Display that contains this View, just before the view is removed from the display. It gives the view a chance to clean up. The method in this top-level view class does nothing. It is not likely that this method will be called directly.

takeExhibit

public void takeExhibit(View view,
                        boolean shareTransform)

Sets the exhibit of this View equal to the same Exhibit that is displayed by another specified View. This has the same effect as setExhibit(Exhibit), except that instead of taking the colors and transform from the default properties of the Exhibit, they are copied from the specified View.

Parameters:

view - The view whose Exhibit is to be copied. After the method is called, both views will be drawing the same exhibit. If null, then the exhibit of this view will also be set to null.

shareTransform - If true, the two views will share the same Transform, so that changes made to the transform in one will also result in a change in the other.

getStatusText

public java.lang.String getStatusText()

This method is called by the display to determine what message to show in the status bar when this view is active. This message is used when there is no animation or one-shot mouse task active and the default mouse task's getStatusText returns null. If the return value is null, then the title of the exhibit is used as the status string (or, if there is no exhibit, then the string "No Exhibit" is used (in the English version)).

Returns:

returns null to use the default string.

getShowAxes

public boolean getShowAxes()

Returns the value of the showAxes property.

See Also:

setShowAxes(boolean)

setShowAxes

public void setShowAxes(boolean show)

If set to true, an Axes decoration is added to the View. When set to false, the decoration is removed. The decoration is actually whatever is returned by the createAxes().

createAxes

protected Axes2D createAxes()

Create an "Axes" decoration that can be added to this view. A subclass should override this to return an object of the appropriate class for the view. Note that this assumes that Axes3D will be a subclass of Axes2D.

getDefaultMouseTask

public MouseTask getDefaultMouseTask()

Returns a MouseTask that can be installed in the Display attached to this View. This method is called automatically by the Display class when a View is intalled, and it should not be necessary to call it directly. A sub-class of View can override this to provide an appropriate MouseTask that will let the user interact with the View; the method can return null if there should be no default mouse interaction.

Returns:

The value returned in the top-level View class is a BasicMouseTask2D, which allows dragging and zooming of the 2D window.

See Also:

MouseTask

getApplyGraphics2DTransform

public boolean getApplyGraphics2DTransform()

Returns the value of the applyGraphics2DTransform property.

See Also:

setApplyGraphics2DTransform(boolean)

setApplyGraphics2DTransform

public void setApplyGraphics2DTransform(boolean applyGraphics2DTransform)

If the applyGraphics2DTransform property is set to true, then a transformation will be applied to the Graphics2D objects that are used to draw this View's Exhibit. After the transformation is applied, real-valued xy-coordinates can be used for drawing the Exhibit instead of pixel coordinates. The default value of the property is true. Subclasses that want to use direct pixel coordinates should set it to false. (For cases where direct pixel coordinates are used only part of the time, see Transform.getUntransformedGraphics().)

Note: When this property is true, a stroke size is also set in the graphics context used to draw the exhibit. If the preserveAspect property is also true, which is the default, then the stroke size is one pixel width. However, if preserveAspect is set to false, the stroke size is set to the smaller of the pixel width and pixel height.

getPreserveAspect

public boolean getPreserveAspect()

Returns the value of the preserveAspect property.

See Also:

setPreserveAspect(boolean)

setPreserveAspect

public void setPreserveAspect(boolean preserveAspect)

If the preservAspect property is set to true, then the 2D window requested for the View is adjusted so that the shape of the rectanglar window in the xy-plane has the same aspect ratio as the rectangle of pixels to which the view is being drawn. The adjusted 2D window is the smallest window that will show the entire ranges of x and y values that were requested. The default value of the preserveAspect property is true.

See Also:

setWindow(double, double, double, double), setApplyGraphics2DTransform(boolean), Transform.setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean)

getAntialiased

public boolean getAntialiased()

Returns the value of the antialiased property.

See Also:

setAntialiased(boolean)

setAntialiased

public void setAntialiased(boolean antialiased)

If the antialiased property is true, then antialiasing is enabled in the Graphics2D objects that are used to draw this View's exhibit. The default value is false.

Parameters:

antialiased -

setWindow

public void setWindow(double xmin,
                      double xmax,
                      double ymin,
                      double ymax)

Sets the rectangular "window" in the xy-plane for this View. This is ignored unless an Exhibit has been installed in the View. When an Exhibit is installed, the window is set to that Exhibit's default window. Note that it is not enforced that xmax must be greater than xmin and that ymax must be greater than ymin. The actual range of values shown in the drawing area might be adjusted if the preserveAspect property is true, but the window specified here is guaranteed to be visible in the drawing area.

Parameters:

xmin - The lower limit of x-values in the xy-plane.

xmax - The upper limit of x-values in the xy-plane.

ymin - The lower limit of y-values in the xy-plane.

ymax - The upper limit of y-values in the xy-plane.

See Also:

Exhibit.getDefaultWindow(), setPreserveAspect(boolean)

setWindow

public void setWindow(double[] window)

Sets the window in the xy-plane for this View. The limits are set to (window[0], window[1], window[2], window[3]).

Parameters:

window - If non-null, must be an array containing at least four doubles. If the value is null, this method does nothing. A non-null value with fewer than four elements will cause an array index out of bounds exception.

See Also:

setWindow(double, double, double, double)

getWindow

public double[] getWindow()

Returns a four-element array containing the limits of the window for this View in the xy-plane, assuming that an Exhibit has been installed in the View. If no Exhibit has been installed, the return value is null. The four elements of the array are the xmin, xmax, ymin, and ymax of the rectangle, in that order. The values here might be different from those specified in setWindow, if the preserveAspect property is true; the actual value adjustment is made only when the Exhibit is drawn.

See Also:

setWindow(double, double, double, double), getRequestedWindow(), setPreserveAspect(boolean)

getTransform

public Transform getTransform()

Returns the transform that is used when drawing this View. This is the transform that is applied to xy-points (or, in 3D views, to xyz-points) to convert them to pixel coordinates for drawing on the screen. This transform is initially obtained by calling an exhibit's Exhibit.getDefaultTransform(View) method when that exhibit is installed in this View. Note that the transform is not necessarily completely valid unless a drawing operation is in progress during a call to render(Graphics2D, int, int).

This is not guaranteed to be valid in all respects unless a drawing operation is in progress. However, the window in the xy-plane and the 3D projection, if any, are valid.

setTransform

public void setTransform(Transform transform)

Sets the transform for this view to a specified transform, with no error checking. This is meant mainly for use in the SaveAndRestore class.

getRequestedWindow

public double[] getRequestedWindow()

Get the window that was originally requested in setWindow. This might differ from the values returned by getWindow if the preserveAspect property is true.

See Also:

setWindow(double, double, double, double), getWindow()

getBackground

public java.awt.Color getBackground()

Gets the background color used when rendering this view.

See Also:

setBackground(Color)

setBackground

public void setBackground(java.awt.Color c)

Set the background color that will be used for rendering this view. If the specified color is null, then the default color (white) is used. Note that the background color is automatically reset when an exhibit is installed into this View. If the exhibit is non-null, then the background color is set using Exhibit.getDefaultBackground(); if a null exhibit is installed, the background color is set to white. So, this method is only for adjusting the background color while an exhibit is displayed. Changing the background color will cause a redraw.

In addition to setting the background color, this method will set the foreground color to either black or white, depending on whehter the background color is light or dark. It is possible to change the foreground color to something else after setting the background.

getForeground

public java.awt.Color getForeground()

Get the foreground color used for rendering this view.

See Also:

setForeground(Color)

setForeground

public void setForeground(java.awt.Color c)

Set the foreground color to be used for rendering this view. If the specified color is null, then the default (black) is used. The foreground color is set automatically when a new exhibit is installed or when the background color is changed by calling setBackground(Color). As a result, this method will rarely be used.

setFastDrawing

public void setFastDrawing(boolean fast,
                           boolean redrawSynchronizedViews)

Sets the fastDrawing property, which tells whether the Exhibt in this View should be drawn as quickly as possible. Most programmers will not need to set this property, but should test it with getFastDrawing() when the usual rendering method takes a long time. (Note that the "fastDrawing" property is shared by any "synchronized" views, and the actual variable that represents this property is stored in the Transform object that is shared by the synchronized views.)

When the value of fastDrawing is changed by this method, the view will be redrawn. Any synchronized views will also be redrawn, unless the redrawSynchronizedViews parameter is false. (This method was introduced to be used during resizing of a DisplayXM in the 3DXM application, where only one view should be redrawn.)

See Also:

setFastDrawing(boolean)

setFastDrawing

public void setFastDrawing(boolean fast)

Sets the fastDrawing property, which tells whether the Exhibit should be drawn as quickly as possible. The property actually applies to any views that are "synchronized" with this view (because they share its transform). Most programmers will not need to set this property, but should test it with getFastDrawing() when the usual rendering method takes a long time.

When the value of fastDrawing is changed by this method, this view and any synchronized views will be redrawn.

getFastDrawing

public boolean getFastDrawing()

Tells whether the Exhibit should be drawn as quickly as possible. Exhibits and Decorations can check the setting of this fastDrawing property if they ordinarily take a long time to draw. If their ordinary drawing is fast, they don't have to worry about it. Fast drawing might be used, for example, during a mouse drag, zoom, or rotate operation. The fastDrawing property is set, for example in BasicMouseTask2D and BasicMouseTask3D during mouse manipulation of the exhibit.

addExtraXML

public void addExtraXML(org.w3c.dom.Document containingDocument,
                        org.w3c.dom.Element viewElement)

This method is called when an XML representation of this view is being constructed by the SaveAndRestore class to give the View a chance to add any extra infomation that is not saved by default. Any Parameters associated with the View are saved automatically, as are the transform and the applyGraphics2DTransform, antialiased, and preserveAspect properties. Decorations associated with the View are not saved automatically UNLESS they are marked with the VMMSave annotation. Property variables will also be saved automatically IF they are marked with VMMSave annotations.

The method in this top-level View class does nothing.

When a subclass overrides this method, it should start by calling super.addExtraXML(containingDocument,viewElement) to make sure that information from the superclass is saved.

Parameters:

containingDocument - The overall XML document that contains the view Element that is being created. This parameter is necessary because it is needed to create any nested subelements that are to be added to the view element.

viewElement - The XML element that is being constructed. This element already exists; the purpose of this method to add any extra information that would be needed to reconstruct this view object from the XML represenation.

See Also:

readExtraXML(Element)

readExtraXML

public void readExtraXML(org.w3c.dom.Element viewInfo)
                  throws java.io.IOException

This method is called when this View is being reconstructed from an XML representation by the SaveAndRestore class. The View object has already been created, and default information (parameters, colors, and transform) have been retrieved. This method is responsible for retrieving any data that was written by addExtraXML(Document, Element), except that properties written with SaveAndRestore.addProperty(Object, String, Document, Element) are retrieved automatically, and decorations written with SaveAndRestore.addDecorationElement(Document, Element, Decoration) are retrieved automatically. The method in this top-level View class does nothing.

In general, when a subclass overrides this method, it should be sure to call super.readExtraXML(viewInfo).

Parameters:

viewInfo - The <view> element from the XML file that contains the information about this view. Some methods from the SaveAndRestore class might be useful for getting the data.

Throws:

java.io.IOException - If an error is found, an exception of type IOException should be thrown. This will abort the whole processing of the XML file.

getParameters

public Parameter[] getParameters()

Returns an array containing all the parameters associated with this View. No parameters are defined by the View class itself. Subclasses can add parameters using the addParameter method. Note that in the array returned by this method, parameters are listed in the REVERSE of the order in which they were added to the View.

Returns:

An array containing the parameters that have been added to this view; these are the actual parameters, not copies. Changing a parameter will ordinarily cause the View to be redrawn to reflect the change. The return value is non-null. If there are no parameters, a zero-length array is returned.

getViewAndExhibitParameters

public Parameter[] getViewAndExhibitParameters()

Returns an array of Parameters containing those that have been added to the Exhibit (if any) that is displayed in this view, followed by those that have been added to this view. In addition, if the Exhibit is a UserExhibit, then the View parameters from the user exhibit are also added, between the Exhibit and the Exhibtit parameters.

See Also:

Exhibit.getParameters(), UserExhibit.Support.getFunctionParameters()

getParameterByName

public Parameter getParameterByName(java.lang.String name)

Returns a paramter that has been added to this View and that has the specified name. If name is null, or if there is no parameter with the specified name, then the return value is null.

addParameter

protected void addParameter(Parameter param)

Associate a parameter with this view. This method is protected, so it can only be called by a subclass. This View is set to be the owner of the Parameter. (In practice, parameters are rarely associated with views; they are much more likely to be associated with exhibits.)

Parameters:

param - The parameter to be added. If the parameter is null, it is ignored. If the parameter has already been added to the View, it is not added for a second time.

removeParameter

protected void removeParameter(Parameter param)

Removes a parameter from this View. The method is protected, so it can only be used by subclasses (and, in fact, it will only rarely be used).

Parameters:

param - The parameter to be removed. If the value is null or if the parameter is not associated with this View, then nothing is done.

parameterChanged

public void parameterChanged(Parameter param,
                             java.lang.Object oldValue,
                             java.lang.Object newValue)

This method will be called automatically when a parameter that has been added to this View is changed. It is not meant to be called directly. Note that in fact, this method simply calls forceRedraw.

Specified by:

parameterChanged in interface Parameterizable

Parameters:

param - The Parmeter whose value has been set.

oldValue - The previous value of the parameter.

newValue - The new, current value of the parameter. This is not necessarily guaranteed to be different from the old value (although it is for parameters definedin the VMM core).

See Also:

forceRedraw()

addDecoration

public void addDecoration(Decoration d)

Add a decoration that will appear in this View only. Of course, the decoration must be one that is compatible with the View's Exhibit. Note that adding or removing a Decoration from a View causes a call to forceRedraw.

Specified by:

addDecoration in interface Decorateable

Parameters:

d - The decoration to be added. If this is null or if it has already been added to the View, then nothing is done. The View is added as a ChangeListener to the decoration. This will cause the View to be automatically redrawn when the Decoration is changed.

removeDecoration

public void removeDecoration(Decoration d)

Remove a specified decoration from this View, if present.

Specified by:

removeDecoration in interface Decorateable

Parameters:

d - The decoration to be removed (if present).

clearDecorations

public void clearDecorations()

Remove all decorations from this View.

getDecorations

public Decoration[] getDecorations()

Returns a list of decorations that have been added to this View

Returns:

a non-null array, possibly of length zero, containing the decorations.

getViewCommands

public ActionList getViewCommands()

Returns a list of "view commands" that can be applied to this View. The commands must implement the ActionItem interface and will generally belong to one of the classes AbstractActionVMM, ToggleAction, ActionRadioGroup, or ActionList. Null items represent separators. The idea is that the list items will be added to a menu or otherwise presented to the user so that the user can invoke the commands (with ActionList items representing submenus). Null values can occur in the list; they are meant to become separaters in the menu.

In this top-level View class, the list contains a "Show/Hide Axes" Action, a null value, and an ActionRadioGroup with three items that can be used to set the background color.

In general, when overriding this method, a subclass should call super.getViewCommands() to obtain a list of commands from the superclass. It can then add additional commands or remove or disable commands that are in the list from the superclass.

getSettingsCommands

public ActionList getSettingsCommands()

Generates a list of "Settings commands" that can be applied to this View. The commands must implement the ActionItem interface and will generally belong to one of the classes AbstractActionVMM, ToggleAction, ActionRadioGroup, or ActionList. Null items represent separators. The idea is that the list items will be added to a menu or otherwise presented to the user so that the user can invoke the commands (with ActionList items representing submenus). Null values can occur in the list; they are meant to become separaters in the menu.

Subclasses that override this method should generally call super.getSettingsCommands() and add their commands to the list retured by that method. This top-level View class does not define any Settings commands; the return value is an empty non-null ArrayList.

getSettingsCommandsForViewAndExhibit

public ActionList getSettingsCommandsForViewAndExhibit()

Returns a list containing Settings commands for this View and for the Exhibit that is contained in this View. The Exhibit commands, if any, occur first in the list. This is a convenience method that simply combines the results of getSettingsCommands() and Exhibit.getSettingsCommandsForView(View). In addtion, if the exhibit is a UserExhibit, and if the exhbit allows the user data to be changed, then a "ChangeUserData" command is also included, between the other Exhibit commands and the View commands. If there is currently no Exhibit in the View, only the view commands are returned. There is presumably no need to override this method.

Note that of the three types of commands defined by Views and Exhibits ("Settings", "Action", and "View" commands), "View" commands are constructed entirely by Views, while "Action" commands and "Settings" commands are constructed by both.

getActions

public ActionList getActions()

Generates a list of "Action commands" that can be applied to this View. The commands must implement the ActionItem interface and will generally belong to one of the classes AbstractActionVMM, ToggleAction, ActionRadioGroup, or ActionList. Null items represent separators. The idea is that the list items will be added to a menu or otherwise presented to the user so that the user can invoke the commands (with ActionList items representing submenus). Null values can occur in the list; they are meant to become separaters in the menu.

Subclasses that override this method should generally call super.getActionss() and add their commands to the list retured by that method. This top-level View class does not define any Action commands; the return value is an empty non-null ArrayList.

getActionsForViewAndExhibit

public ActionList getActionsForViewAndExhibit()

Returns a list containing Action commands for this View and for the Exhibit that is contined in this View. The Exhibit commands, if any, occur first in the list. This is a convenience method that simply combines the results of getActions() and Exhibit.getActionsForView(View). If there is currently no Exhibit in the View, only the view commands are returned. There is presumably no need to override this method.

Note that of the three types of commands defined by Views and Exhibits ("Settings", "Action", and "View" commands), "View" commands are constructed entirely by Views, while "Action" commands and "Settings" commands are constructed by both.

getAdditionalAnimations

public ActionList getAdditionalAnimations()

This method returns a list of ActionItem that will be added to the Animation menu of the 3dxm applicaiton. The values in the list should ordinarily be commands (i.e. AbstractActionVMM) that run animations (although there is no way to enforce this restriction). These animations commands are in addition to the standard "Morph" and "Cyclic Morph" commands. Note that these commands are added to those returned by getAdditionalAnimations().

In this top-level View class, the return value is a an empty list (but not null). In general, when overriding this method, subclasses should call "super.getAdditionalAnimations()" to obtain a list of actions from the superclass. It can then add additional actions or remove or disable actions that are in the list from the superclass.

getAdditionalAnimationsForViewAndExhibit

public ActionList getAdditionalAnimationsForViewAndExhibit()

Returns the combined contents of the lists obtained from getAdditionalAnimations() and Exhibit.getAdditionalAnimationsForView(View). There should not be any need to override this method.

doDraw

protected void doDraw(java.awt.Graphics2D g)

This method is called by the render method when the Exhibit in this View needs to be redrawn. The default as defined here is simply to call the exhibit's render method. Subclasses can override this method if some other action is needed.

Drawing is likely to need information about the transform (including the rectangular area in the xy-plane that is being drawn and the rectangle of pixels in the graphics context where it is drawn) and the decorations that have been added to the view. This information is available from getTransform() and getDecorations().

Parameters:

g - The graphics context where the exhibit is to be drawn. The drawing area has already been cleared to the background color.

forceRedraw

public void forceRedraw()

Force the Exhibit to be completely redrawn. This is stronger than just repainting because it forces the off-screen image to be redrawn as well. Note that simply calling repaint on the Display where this View is rendered will NOT cause the off-screen image to be redrawn and so will not necessarily cause what is displayed on the screen to change. The system is designed so that this method or its equivalent will be called automatically in most cases, such as when Parameters of the View or Exhibit are changed or when a Decoration is added or removed or changed. It is also called when other properties defined in this top-level View classe are changed. Subclasses of View might need to call this method when changes are made that affect the appearance of the Exhibit.

stateChanged

public void stateChanged(javax.swing.event.ChangeEvent evt)

A View listens for state change events that are generated when the Exhibit or Decoration that it is displaying is changed, or by the transform (that converts real coords to pixel coords). This method is automatically called by the Exhibit, Decoration, or Transform when it is changed. It will not ordinarly be called directly. Note that in fact, this method simply calls forceRedraw(), which causes the View to be completely resdrawn.

Specified by:

stateChanged in interface javax.swing.event.ChangeListener

See Also:

forceRedraw()

render

public void render(java.awt.Graphics2D g,
                   int width,
                   int height)

This method is called to draw this View's Exhibit. This will most often be called from the paintComponent method of the Display class. The process of rendering a View is rather complicated because of the need to manage off-screen images and various properties of the View. Subclasses of View should probably not override this method. They should change the doDraw method, which is called by this method, instead.

While the exhibit is being rendered, this method sets the value of the protected variable currentGraphics to the graphics context in which the exhibit is being drawn. This variable is used implicitely for drawing in the rendering methods that are provided by the View class and its 3D subclass. This graphics context is set only for the duration of the call to the doDraw(Graphics2D) method in this class, and hence during rendering of an exhibit (in its Exhibit.doDraw(Graphics2D, View, Transform) method. It is also set during direct drawing to the off-screen image initiated by beginDrawToOffscreenImage(). At other times currentGraphics is null, and calling the rendering methods that use this graphics context at those times will result in an error.

Note that this render method always completely paints the rectangle in which it draws.

(In the rare case that creation of an offscreen image fails because of low memory, an error message is placed in the drawing area.)

Parameters:

g - The graphics context where the Exhibit is to be drawn. It is assumed that the upper left corner of the drawing area has coordinates (0,0). The off-screen image is simply drawn in g, except that when no exhibit exists, it is filled with the background color.

width - The width, in pixels, of the drawing area where the exhibit is to be drawn.

height - The height, in pixels, of the drawing area where the exhibit is to be drawn.

needsNewOSI

protected boolean needsNewOSI(int width,
                              int height)

This is called by render to check whether a new offscreen image needs to be created, given the specified width and height of the drawing area.

putOSI

protected void putOSI(java.awt.Graphics2D g,
                      int width,
                      int height)

This is called by render to copy the offscreen image to the screen. The width and height of the drawing area are given as parameters, although they is not used in the version of this method in class View.

createOSI

protected void createOSI(int width,
                         int height)

This method is called whenever an off-screen image needs to be created. This method sets the value of the protected variable fullOSI to the newly created image. (Subclasses should respect this.) The default is to create a new BufferedImage whose type is specified by the protected variable offscreenImageType. This is most likely what is desired. However, sub-classes can override this method if a different type of image is needed.

clearOSI

protected void clearOSI()

Fills the offscreen image with the background color of this View.

prepareOSIForDrawing

protected java.awt.Graphics2D prepareOSIForDrawing()

Prepare the offscreen image for drawing and return a graphics context for drawing to it. This method is called by render(Graphics2D, int, int) before it begins drawing to the offscreen image. It is also called by beginDrawToOffscreenImage(). The offscreen image exists before this is called. In the top-level View class, this applies the transform and (if approprieate) antialiasing to the OSI drawing context and sets the foregraund and background colors.

Note: It is important that the protected variable fullOSI point to a BufferedImage that contains the image that is shown on the screen. Subclasses that override this method should respect this. This is true in View3D, for example, even when the actual drawing is being done elsewhere during RED_GREEN_STEREO rendering.

Returns:

A graphics context for drawing to the off-screen image.

finishOSIDraw

protected void finishOSIDraw()

This is called when drawing to the off-screen image is finished, to give it a chance for clean-up. The method in the top-level view does nothing.

setColor

public void setColor(java.awt.Color c)

This method will set the color in the current graphics context. This method should only be used while drawing an exhibit or after beginDrawToOffscreenImage(). If called at other times, there is no effect.

Parameters:

c - the color to be used for subsequent drawing; if c is null, then the default foreground color of the View is restored.

getColor

public java.awt.Color getColor()

Returns the drawing color of the current graphics context. This method should only be used while drawing an exhibit or after beginDrawToOffscreenImage(). If called at other times, the return value is null.

setStrokeSizeMultiplier

public void setStrokeSizeMultiplier(int pixels)

Sets the width of the stroke used for drawing lines and curves in the current graphics context to have a width equal to a specified number of pixels. This method should only be used while drawing an exhibit or after beginDrawToOffscreenImage(). If called at other times, the call has no effect. Note that this just sets the stroke width to be a multiple of the default stroke size, as defined by the Transform. Calling this method with a parameter value of 1 will restore the default stoke width.

See Also:

Transform.getDefaultStrokeSize()

drawPixel

public void drawPixel(double x,
                      double y)

Draws a point by turning on a single pixel. This is done by transforming (x,y) to pixel coordinates, then using drawPixelDirect to set the color of the single pixel.

Parameters:

x - The x-coordinate of the point, in window (real xy) coodinates.

y - The y-coordinate of the point, in window (real xy) coodinates.

See Also:

drawPixelDirect(Color, int, int)

drawPixel

public void drawPixel(java.awt.geom.Point2D pt)

Draws a point by turning on a single pixel. This just calls drawPixel(pt.getX(),pt.getY()).

Parameters:

pt - The non-null point, in window (real xy) coodinates.

drawDot

public void drawDot(java.awt.geom.Point2D pt,
                    double diameter)

Draws a dot of specified diameter centered at a specified point. This is done by calling the Graphics2D fill() command for an appropriate Ellipse2D. The diameter is specified in pixels. Note that if the preserveAspectRatio is off for this View, then the dot will can be an oval rather than a circle.

drawPixels

public void drawPixels(java.awt.geom.Point2D[] points,
                       int pointIndexStart,
                       int pointIndexEnd)

Draws a list of pixels in the current drawing context, where the pixels are specified in object coordinates. This should only be called while drawing is in progress.

drawString

public void drawString(java.lang.String s,
                       double x,
                       double y)

This can be called during drawing to draw a string at a specified point, given in window (real x,y) coordinates. The font is NOT transformed, as it would be if you simply used the drawString method of a drawing context to which a transform has been applied. The point (x,y) is properly transformed from xy-coordinates to pixel coordinates, whether a transform has been applied ot the drawing context or not. After conversion, if necessary, the graphics context returned by Transform.getUntransformedGraphics() is used to draw the string.

See Also:

drawString(String, Point2D)

drawString

public void drawString(java.lang.String s,
                       java.awt.geom.Point2D xyCoords)

This can be called during drawing to draw a string at a specified point, given in window (real x,y) coordinates. The font is NOT transformed, as it would be if you simply used the drawString method of a drawing context to which a transform has been applied.

Parameters:

xyCoords - The non-null point containting the coordinates of the basepoint of the string in real xy-coordinates. This point is not modified.

See Also:

drawString(String, double, double)

drawLine

public void drawLine(double x1,
                     double y1,
                     double x2,
                     double y2)

Draws a line in the current drawing context. This should only be called while drawing is in progress. The line has endpoints (x1,y1) and (x2,y2), where the coordinates are in window (real xy) coordinates. This should only be called when a drawing operation is in progress.

drawLine

public void drawLine(java.awt.geom.Point2D pt1,
                     java.awt.geom.Point2D pt2)

Draws a line in the current drawing context. This should only be called while drawing is in progress.

Parameters:

pt1 - The first endpoint of the line, with coordinates given in the window (real xy) coordinates system.

pt2 - The second endpoint of the point, with coordinates given in the window (real xy) coordinates system.

drawCurve

public void drawCurve(java.awt.geom.Point2D[] points,
                      int pointIndexStart,
                      int pointIndexEnd)

Draws a curve in the current drawing context. The points on the curve are given in window (real xy) coordinates. This should only be called while drawing is in progress.

Parameters:

points - The curve is drawn through some or all of the points in this array. If the array is null, nothing is done. The curve is acutually just made up of lines from one point to the next. An element in the array can be null. In that case, one or two segments are missing from the curve -- the segments on either side of the missing point. Consecutive points are also not joined by a segment if the jump from one point to the next is too large.

pointIndexStart - The number of points in the array that should be used for the curve. A curve is drawn though points[pointIndexStart], point[pointIndexStart+1], ..., points[pointIndexEnd]. The value of pointIndexStart is clamped to lie in the range 0 to points.length-1.

pointIndexEnd - The number of points in the array that should be used for the curve. A curve is drawn though points[pointIndexStart], point[pointIndexStart+1], ..., points[pointIndexEnd]. The value of pointIndexEnd is clamped to lie in the range 0 to points.length-1. If pointIndexEnd is less than or equal to pointIndexStart, nothing is drawn.

drawCurve

public void drawCurve(java.awt.geom.Point2D[] points)

Draws a curve through all the points in an array by calling drawCurve(points,points.length)

Parameters:

points - The array of points on the curve. If this is null, nothing is done.

drawCurve

public void drawCurve(java.awt.geom.Point2D[] points,
                      int pointCount)

Draws a curve in the current drawing context. The points on the curve are given in window (real xy) coordinates. This should only be called while drawing is in progress.

Parameters:

points - The curve is drawn through some of all of the points in this array. If the array is null, nothing is done. The curve is acutually just made up of lines from one point to the next. An element in the array can be null. In that case, one or two segments are missing from the curve -- the segments on either side of the missing point. Consecutive points are also not joined by a segment if the jump from one point to the next is too large.

pointCount - The number of points in the array that should be used for the curve. A curve is drawn though points[0], point[1], ..., points[pointCount-1]. If pointCount is greater than points.length, then its value is changed to points.length.

drawPixelDirect

public void drawPixelDirect(java.awt.Color color,
                            int x,
                            int y)

Sets the pixel with pixel coordinates (x,y) to be a specified color. The pixel color is changed in the off-screen image, not on the screen immmediately. The current transformation is not applied to the coordinates.

Parameters:

color - the color for the pixel; if null, the current drawing color is used.

x - the horizontal pixel coordinate.

y - the vertical pixel coordinate.

drawLineDirect

public void drawLineDirect(int x1,
                           int y1,
                           int x2,
                           int y2)

Draws a line in the current color between points that are specified using pixel coordinates.

fillRectDirect

public void fillRectDirect(int x,
                           int y,
                           int width,
                           int height)

Draws a filled-in rectangle in the current color, where the rectangle is specified in pixel coordinates.

beginDrawToOffscreenImage

public boolean beginDrawToOffscreenImage()

This method, along with endDrawToOffscreenImage(), allow you to draw directly to this view's off-screen image, if there is one. This operation is allowed only if (1) An offscreen image exists, (2) the View has already been drawn to the screen at least once since its current exhibit was installed, and (3) no drawing operation is in progress (including a regular draw by the render method or a draw operation initiated by a previous call to this method that was not matched by a call to endDrawToOffscreenImage). If all these conditions hold, this method initiates a drawing operation and returns true. If any of them fail, it returns false and no drawing operation is initiated. To terminate the drawing operation, you must call endDrawToOffscreenImage. A drawing operation should not remain open for any length of time. It should complete before the method in which beginDrawToOffscreenImage is called.

During a drawing operation initiated by this method, drawing done using the draw methods in this class, such as drawCurve(Point2D[]), will draw to the off-screen image. This also applies to drawing operations in the View3D subclass and presumably in other subclasses. The point of this is to allow you to draw extra stuff incrementally on the off-screen canvas, without redrawing the whole thing from scratch each time.

After calling endDrawToOffscreenImage, you will probably want to call the repaint() method of this View's display to cause the changes to appear on the screen. Do NOT call forceRedraw(), since that will generate a call to render, which will erase the changes you just made!

Returns:

Returns true if the drawing operation was actually begun. If the return value is false, attemps to draw will not draw to the off-screen image and will probably cause errors.

endDrawToOffscreenImage

public void endDrawToOffscreenImage()

This method, along with beginDrawToOffscreenImage(), allow you to draw directly to this view's off-screen image, if there is one. See that method for more information. No error occurs if this is called when no draw-to-image operation is in progress.

getImage

public java.awt.image.BufferedImage getImage(boolean alwaysCopy)

Get a buffered image that contains the picture shown on this View's display. If the parameter alwaysCopy is false, then the View's off-screen image is returned (provided one has already been created). Otherwise, a new image is created and the View is rendered to this image by calling its render method. The return value can be null if this method is called when there is no Display associated with this view, or if there is no Exhibit associated with this View, or if this method is called before a picture has been drawn to the screen. It is possible that an OutOfMemoryError might occur when an attempt is made to create an image.

Note that if you need to draw to the offscreen image, you should use the facility provided by beginDrawToOffscreenImage(). You should not generally simply draw to the image returned by this method (even though that will work in some cases). This method was introduced mainly to make it possible to save the screen image to a file or to a "filmstrip" animation.

Parameters:

alwaysCopy - If this is false, it is possible that the image that is returned is the actual image that the View uses to store its content; this image will be modified whenever the view is redrawn. (alwaysCopy = true is used to get the frame for a filmstrip; alwaysCopy = false is used to get an image to save to a file)