vmm.core
Class Exhibit

java.lang.Object
  vmm.core.Exhibit

All Implemented Interfaces:

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

Direct Known Subclasses:

Exhibit3D, Mandelbrot, ODE_2D, PlaneCurve, RepeatedSegmentFractal

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

An Exhibit represents a mathematical object that can be drawn on the screen. An Exhibit is rendered by a View, which drawns the Exhibit in a Display. An Exhibit emits ChangeEvents when it changes in a way that requires redrawing. View objects listen for these events to decide when to do a redraw. The infrastructure for generating these events and for setting up event listening is built into the Exhibit, View, Display, Decoration and Parameter classes so that ordinary programmers will not have to worry about it.

Exhibit s declared as an abstract class, since it doesn't make sense to use it directly. However, it does not contain any abstract methods. Concrete subclasses should provide some way of drawing an actual Exhibit, most likely by overriding the doDraw method (but possibly by creating a specialized View class to do the drawing or by some other technique).

Concrete subclasses can use the addParameter, setDefaultWindow, setDefaultForeground, and setDefaultBackground to customize the Exhibit. The subclass can override the getActionsForView, getViewCommandsForView, getSettingsCommandsForView, getCreateAnimation, getMorphingAnimation, and createAxes methods, in addtion to doDraw and possibly computeDrawData.

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

Field Summary

protected java.util.ArrayList<Decoration>	decorations Decorations that have been associated with this Exhibit (presumably through the addDecoration(Decoration) method).
protected boolean	exhibitNeedsRedraw This variable is set to true when the Exhibit changes in a way that needs redrawing.
protected boolean	isMorphing
protected View	morphingView
protected java.util.ArrayList<Parameter>	parameters Parameters that have been associated with this Exhibit (presumably by the addParameter(Parameter) method).
protected Transform	previousTransform Used to record the Transform that is used when the Exhibit is drawn, so that it can be compared with the Transform used the next time the Exhibit is drawn.

Constructor Summary

Exhibit()

Method Summary

void	addChangeListener(javax.swing.event.ChangeListener listener) Add a ChangeListener to this Exhibit.
void	addDecoration(Decoration d) Add a decoration that will appear in all Views of this Exhibit.
void	addExtraXML(org.w3c.dom.Document containingDocument, org.w3c.dom.Element exhibitElement) This method is called when an XML representation of this exhibit is being constructed by the SaveAndRestore class to give the exhibit a chance to write any extra infomation that is not saved by default.
protected void	addParameter(Parameter param) Associate a parameter with this Exhibit.
void	addView(View view) Adds a view to the list of views that are displaying this Exhibit.
void	clearDecorations() Remove all decorations from the Exhbiit.
protected void	computeDrawData(View view, boolean exhibitNeedsRedraw, Transform previousTransform, Transform newTransform) Recompute any cached data in the Exhibit that might have changed since it was computed.
protected void	computeDrawDataHook(View view, Transform transform) Called by render to compute the draw data for the exhibit.
protected void	doDraw(java.awt.Graphics2D g, View view, Transform transform) Do the actual drawing of the exhibit.
protected void	doDrawHook(java.awt.Graphics2D g, View view, Transform transform) Called by render to this exhibit.
protected void	fireExhibitChangeEvent() Sends a ChangeEvent to registered ChangeListeners.
void	forceRedraw() This method forces the Exhibit to be completely redrawn by marking it as needing to be redrawn and sending a change event to any ChangeListeners that have beeen registered with the Exhibit, presumably just to any Views that are showing this Exhibit.
ActionList	getActionsForView(View view) This method returns a list of ActionItem that can be applied to a View that contains this Exhibit.
ActionList	getAdditionalAnimationsForView(View view) This method returns a list of ActionItem that will be added to the Animation menu of the 3dxm applicaiton.
View[]	getAlternativeViews() This method returns additionAal View objects that can be used to view this Exhibit, in addition to the view returned by getDefaultView().
Animation	getBuildAnimation(View view) Returns a "build animation" for this Exhibit, or null if no build animation is to be used.
Animation	getCreateAnimation(View view) This method is called to "create" the Exhibit.
Decoration[]	getDecorations() Returns a list of decorations that have been added directly to this exhibit.
java.awt.Color	getDefaultBackground() Returns the default background color desired by this Exhibit.
java.awt.Color	getDefaultForeground() Returns the default foreground color desired by this Exhibit.
Transform	getDefaultTransform(View view) Returns a default Transform object to be used in the specified View.
View	getDefaultView() This method returns a default View object for viewing this Exhibit.
double[]	getDefaultWindow() Returns a four-element array rerpresening the default Window in the xy-plane in which this Exhibit wants to be displayed.
int	getFramesForMorphing() Tells how many frames are to be used by a morphing animation, as returned by getMorphingAnimation(View, int).
BasicAnimator	getMorphingAnimation(View view, int looping) This method is meant to produce a "morph" animation for this Exhibit, by animating any applicable animateable parameters.
java.lang.String	getName() Returns a name for this Exhibit.
Parameter	getParameterByName(java.lang.String name) Returns a paramter that is associated with this Exhibit and that has the specified name, if there is one.
Parameter[]	getParameters() Returns an array containing all the parameters associated with this Exhibit.
ActionList	getSettingsCommandsForView(View view) Returns a list of "settings commands" that can be applied to this Exibit, when displayed in the specified View.
java.lang.String	getTitle() Returns a human-readable title for this Exhibit that could, for example, be used in a menu that is presented to the user.
boolean	getUseFilmstripForMorphing() Returns the value of the useFilmstripForMorping property.
java.util.ArrayList<View>	getViews() Returns a list of Views that are displaying this Exhibit.
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 Exhibit is changed.
void	readExtraXML(org.w3c.dom.Element exhibitInfo) This method is called when this exhibit is being reconstructed from an XML representation by the SaveAndRestore class.
void	removeChangeListener(javax.swing.event.ChangeListener listener) Remove a ChangeListener from this Exhibit.
void	removeDecoration(Decoration d) Remove a specified Decoration, if present.
protected void	removeParameter(Parameter param) Removes a parameter from this Exhibit.
void	removeView(View view) Removes a view from the list of views that are displaying this Exhibit.
void	render(java.awt.Graphics2D g, View view, Transform transform, java.util.ArrayList<Decoration> extraDecorations) This method is called by the View class when it needs to redraw the Exhibit.
void	setDefaultBackground(java.awt.Color c) Set the default background color for this Exhibit.
void	setDefaultForeground(java.awt.Color c) Set the default foreground color for this Exhibit.
void	setDefaultWindow(double[] window) Sets the default window in the xy-plane for viewing this Exhibit, using xy-limits from an array.
void	setDefaultWindow(double xmin, double xmax, double ymin, double ymax) Set the default window in the xy-plane for viewing this Exhibit.
void	setFramesForMorphing(int framesForMorphing) Set the number of frames to be used in a moprphing animation, as returned by getMorphingAnimation(View, int).
void	setName(java.lang.String name) Sets the name for this view.
void	setUseFilmstripForMorphing(boolean useFilmstripForMorphing) Sets the value of the useFilmstripForMorphing property.
void	stateChanged(javax.swing.event.ChangeEvent evt) Sends a change event, presumably in response to a change in one of the Decorations that have been added to this Exhibit.

Methods inherited from class java.lang.Object

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

Field Detail

isMorphing

protected boolean isMorphing

morphingView

protected View morphingView

parameters

protected java.util.ArrayList<Parameter> parameters

Parameters that have been associated with this Exhibit (presumably by the addParameter(Parameter) method). This variable will ordinarly be manipulated through the addParameter method and other parameter-related methods defined in this class rather than directly.

decorations

protected java.util.ArrayList<Decoration> decorations

Decorations that have been associated with this Exhibit (presumably through the addDecoration(Decoration) method). This variable will ordinarily be manipualted through methods defined in this class rather than directly.

exhibitNeedsRedraw

protected boolean exhibitNeedsRedraw

This variable is set to true when the Exhibit changes in a way that needs redrawing. This is done when the forceRedraw() method is called, and it should only be set to true by calling that method, which also arranges for the actual redrawing to be done. The value of this variable is passed into the computeDrawData(View, boolean, Transform, Transform) method, where it should be checked to determine whether the Exhibit has changed.

previousTransform

protected Transform previousTransform

Used to record the Transform that is used when the Exhibit is drawn, so that it can be compared with the Transform used the next time the Exhibit is drawn. This is passed into the computeDrawData(View, boolean, Transform, Transform) method, and it should not be necessary for ordinary subclasses to use this variable directly.

Constructor Detail

Exhibit

public Exhibit()

Method Detail

getName

public java.lang.String getName()

Returns a name for this Exhibit. By default, the name that is returned will be the same as the name of the class to which the Exhibit 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 Exhibit from other Exhibits. For a human-readable name, the getTitle() method should be used instead of getName().

setName

public void setName(java.lang.String name)

Sets the name for this view. In general, the default name, consisting of the full class name of the Exhibit object, should be sufficient.

See Also:

getName()

getTitle

public java.lang.String getTitle()

Returns a human-readable title for this Exhibit that could, for example, be used in a menu that is presented to the user. The title is always obtained by using the name returned by getName as a key into the default resource bundle. This allows for easy internationalization. Note that if no resource bundle is found or if the resource bundle does not contain the specified key, then the value returned by getTitle() will be the same as the value returned by getName.

See Also:

getName(), I18n.tr(String)

getFramesForMorphing

public int getFramesForMorphing()

Tells how many frames are to be used by a morphing animation, as returned by getMorphingAnimation(View, int).

setFramesForMorphing

public void setFramesForMorphing(int framesForMorphing)

Set the number of frames to be used in a moprphing animation, as returned by getMorphingAnimation(View, int). The value must be greater than 1. Values less than or equal to 1 are ignored. The default value is 50.

getUseFilmstripForMorphing

public boolean getUseFilmstripForMorphing()

Returns the value of the useFilmstripForMorping property.

See Also:

setUseFilmstripForMorphing(boolean)

setUseFilmstripForMorphing

public void setUseFilmstripForMorphing(boolean useFilmstripForMorphing)

Sets the value of the useFilmstripForMorphing property. If this property is true, then a morphing animation for this exhibit will be set to create a filmstrip, so that each frame of the animation only needs to be computed once.

See Also:

TimerAnimation.setUseFilmstrip(boolean)

addExtraXML

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

This method is called when an XML representation of this exhibit is being constructed by the SaveAndRestore class to give the exhibit a chance to write any extra infomation that is not saved by default. Any Parameters associated with the exhibit are saved automatically. Note that Decorations associated with the exhibit are NOT saved automatically UNLESS the decoration class is marked with a VMMSave annotation. Property variables will also be saved automatically IF they are marked with VMMSave annotations.

The method in this top level class does nothing.

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

Parameters:

containingDocument - The overall XML document that contains the exhibit 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 exhibit element.

exhibitElement - 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 exhibit object from the XML represenation.

See Also:

readExtraXML(Element)

readExtraXML

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

This method is called when this exhibit is being reconstructed from an XML representation by the SaveAndRestore class. The Exhibit object has already been created, and default information (parameters and decorations) 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 saved with SaveAndRestore.addDecorationElement(Document, Element, Decoration) are retrieved automatically. The method in this top-level Exhibit class does nothing.

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

Parameters:

exhibitInfo - The <exhibit> element from the XML file that contains the information about this exhibit. 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.

See Also:

addExtraXML(Document, Element)

addChangeListener

public void addChangeListener(javax.swing.event.ChangeListener listener)

Add a ChangeListener to this Exhibit. Change events are sent when the exhibit needs to be redrawn. This is set up automatically in the VMM core. It should not be necessary for ordinary programmers to call or to override this method.

Parameters:

listener - The listener to be added to the exhibit. If the value is null, nothing is done.

removeChangeListener

public void removeChangeListener(javax.swing.event.ChangeListener listener)

Remove a ChangeListener from this Exhibit. Change events are sent when the exhibit needs to be redrawn. This is set up automatically in the VMM core. It should not be necessary for ordinary programmers to call or to override this method.

Parameters:

listener - The listener to be removed. If it is not currently registered with the Exhibit, then nothing is done.

fireExhibitChangeEvent

protected void fireExhibitChangeEvent()

Sends a ChangeEvent to registered ChangeListeners. A sub-class should call either this method or the forceRedraw method when the Exhbit is changed and needs to be redrawn. The change event is propagagted to the Views that are displaying this Exhibit, which will respond by redrawing. The difference between fireExhibitChangeEvent and forceRedraw is that forceRedraw will force recomputation of cached data in the exhibit by setting the value of the variable exhibitNeedsRedraw to true. The fireExhibitChangeEvent method does not do this.

If the exhibit is being "morphed", the change event might be propagated only to the view in which the morphing is being displayed and to other views, if any, in the same display. This will be at least true if the getMorphingAnimation method in this class is called with a non-null View parameter. This is to prevent other views of the exhibit from redrawing themselves when parameters change during a morph.

See Also:

forceRedraw(), getMorphingAnimation(View, int)

stateChanged

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

Sends a change event, presumably in response to a change in one of the Decorations that have been added to this Exhibit. An Exhibit listens for change events from Decorations that have been added to the Exhibit. The Exhibit responds by firing a change event in turn, which will go to any Views that are displaying the Exhibit. This will cause the Views to redraw. This method is not meant to be called directly.

Specified by:

stateChanged in interface javax.swing.event.ChangeListener

See Also:

addDecoration(Decoration)

getParameters

public Parameter[] getParameters()

Returns an array containing all the parameters associated with this Exhibit. Note that when this is a UserExhibit, the array returned by this method does not include the function parameters associated with the user exhibit; see UserExhibit.Support.getFunctionParameters(). No parameters are defined by the Exhibit class itself. Subclasses should add parameters using the addParameter(Parameter) 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 Exhibit.

Returns:

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

getParameterByName

public Parameter getParameterByName(java.lang.String name)

Returns a paramter that is associated with this Exhibit and that has the specified name, if there is one. If the 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 Exhibit. This method is protected, so it can only be called by a subclass. This Exhibit is set to be the owner of the Parameter, so that the Exhibit will be notified when the Parameter changes. A Parameter change will cause the Exhibit to be redrawn.

Parameters:

param - The parameter to be added. If the parameter is null, it is ignored. Adding a parameter for a second time has no effect.

See Also:

getParameters()

removeParameter

protected void removeParameter(Parameter param)

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

Parameters:

param - The parameter to be removed. If the value is null or if the parameter is not associated with this Exhibit, 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 Exhibit is changed. It should not ordinarily be called directly. Note that in fact, this method simply calls forceRedraw. This method is defined in the <@link Parameterizable} interface.

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()

getActionsForView

public ActionList getActionsForView(View view)

This method returns a list of ActionItem that can be applied to a View that contains this Exhibit. If the view parameter is null, it should return actions that are appropriate in any View. View is presumably one that is displaying this Exhibit.

The items in the returned list must implement the ActionItem interface and generally belong to one of the classes AbstractActionVMM, ToggleAction, ActionRadioGroup, or ActionList. Null items represent separators.

In this top-level Exhibit class, the return value is a list that contains one object of type AbstractActionVMM. The action represents the "Create" command, which is meant to run the "create animation" of the Exhibit.

In general, when overriding this method, subclasses should call "super.getActionsForView()" 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.

getSettingsCommandsForView

public ActionList getSettingsCommandsForView(View view)

Returns a list of "settings commands" that can be applied to this Exibit, when displayed in the specified View.

The items in the returned list must implement the ActionItem interface and 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).

In this top-level Exhibit class, the list contains several commands that call up dialogs where the user can change various settings. (These include: "Set Parameters", "Set Morphing", "Set Number of Frames", and "Set Visible Ranges".) Note that for these commands, the View parameter is used simply to get the View's Display, which is used as the parent of the dialog.

In general, when overriding this method, subclasses should call "super.getSettingsCommandsForView()" 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.

getAdditionalAnimationsForView

public ActionList getAdditionalAnimationsForView(View view)

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 View.getAdditionalAnimations().

In this top-level Exhibit class, the return value is a an empty list (but not null). In general, when overriding this method, subclasses should call "super.getAdditionalAnimationsForView()" 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.

Parameters:

view - The view in which the animations will be run.

addView

public void addView(View view)

Adds a view to the list of views that are displaying this Exhibit. This method is called by the view when the exhibit is added to the view; it is not meant to be called directly.

Parameters:

view - The view that that is about to start displaying this Exhibit.

See Also:

View.setExhibit(Exhibit)

removeView

public void removeView(View view)

Removes a view from the list of views that are displaying this Exhibit. This method is called by the view when the exhibit is removed from the view; it is not meant to be called directly.

Parameters:

view - The view that is no longer displaying this exhibit.

getViews

public java.util.ArrayList<View> getViews()

Returns a list of Views that are displaying this Exhibit. The return value can be null.

addDecoration

public void addDecoration(Decoration d)

Add a decoration that will appear in all Views of this Exhibit. Of course, the decoration must be one that is compatible with this Exhibit. Note that adding and removing decortions will fire ChangeEvents that will cause the Exhibit to be redrawn. However, it will not force recomputation of cached data for the Exhibit. (This is, it does not call forceRedraw().)

Specified by:

addDecoration in interface Decorateable

Parameters:

d - The decoration to be added. If this is null or has already been added to the Exhibit, then nothing is done. The Exhibit is added as a ChangeListener to the Decoration. When the decoration sends a ChangeEvent to the Exhibit, it will in turn send a change event to any Views that are showing the Exhibit, which will cause the Views to be redrawn.

removeDecoration

public void removeDecoration(Decoration d)

Remove a specified Decoration, if present.

Specified by:

removeDecoration in interface Decorateable

Parameters:

d - The decoration to be removed. If this is null or or has not been added to this Exhibit then nothing is done.

See Also:

addDecoration(Decoration)

clearDecorations

public void clearDecorations()

Remove all decorations from the Exhbiit.

See Also:

addDecoration(Decoration)

getDecorations

public Decoration[] getDecorations()

Returns a list of decorations that have been added directly to this exhibit.

Returns:

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

getDefaultView

public View getDefaultView()

This method returns a default View object for viewing this Exhibit. The method in this top-level Exhibit class returns an object belonging to the generic top-level View class. This method will often be overidden in subclasses to return a more appropriate View. The return value of this method should always be non-null.

getAlternativeViews

public View[] getAlternativeViews()

This method returns additionAal View objects that can be used to view this Exhibit, in addition to the view returned by getDefaultView(). A return value of null indicates that there are no alternative views of this Exhibit. (It seems like alternative views will be very rare.)

If there are alternative views of an Exhibit, then it is a good idea that each view be assigned a name (using View.setName(String)) that can be used to distinguish among the views. This is important for the 3dxm shell program, since it presents the names of the views to the user in a menu. Both the default view and the alternative views should have names.

Returns:

An array containing alternative views for this exhibit. In the top-level Exhibit class, the return value is null.

getDefaultWindow

public double[] getDefaultWindow()

Returns a four-element array rerpresening the default Window in the xy-plane in which this Exhibit wants to be displayed. The default value is the array (-5,5,-5,5). This can be changed with the setDefaultWindow method. The four values in the array are the minumin x-value, the maximum x-value, the minimumn y-value, and the maximum y-value, in that order. In the View class, when an Exhibit is installed in a View, the View's window is set to the Exhibit's default window.

setDefaultWindow

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

Set the default window in the xy-plane for viewing this Exhibit.

See Also:

getDefaultWindow()

setDefaultWindow

public void setDefaultWindow(double[] window)

Sets the default window in the xy-plane for viewing this Exhibit, using xy-limits from an array. The array must be non-null and must contain at least 4 elements, or an exception will be thrown. This method just calls setDefaultWindow(window[0],window[1],window[2],window[3]).

See Also:

getDefaultWindow()

getDefaultTransform

public Transform getDefaultTransform(View view)

Returns a default Transform object to be used in the specified View. The View calls this method when the Exhibit is installed in the View. The Transform object that is returned should be a newly created object, since the View will use and modify the object that is returned, not a copy.

Parameters:

view - The View is provided as a parameter since there might be several types of View appropriate for a given exhibit, and they might require different Transforms. In particular, for example, a 3D View will require a 3D Transform.

Returns:

In this top-level Exhibit class, the Transform that is returned is a 2D Transform created by calling "new Transform(xmin,xmax,ymin,ymax)" where the values of xmin, xmax, ymin, and ymax are taken from the array returned by getDefaultWindow.

See Also:

getDefaultWindow(), Transform.Transform(double, double, double, double)

getDefaultBackground

public java.awt.Color getDefaultBackground()

Returns the default background color desired by this Exhibit. The value in this class is Color.white, but can be changed by calling setDefaultBackground.

This method is called in the Display class to set the background color when a new exhibit is installed. It is not likely to be called directly.

setDefaultBackground

public void setDefaultBackground(java.awt.Color c)

Set the default background color for this Exhibit. This would ordinarily be called in the constructor of a sub-class. Note that setting a default background color with this method automatically sets the default foreground color to black or white, depending on the default background color. If you want a different default foreground color, call setDefaultForeground(Color) after callind setDefaultBackground.

Parameters:

c - The default background color. If this is null, the default (white) is used.

getDefaultForeground

public java.awt.Color getDefaultForeground()

Returns the default foreground color desired by this Exhibit. The value in this class is Color.black but can be changed by calling setDefaultForeground.

This method is called in the Display class to set the foregournd color when a new exhibit is installed. It is not likely to be called directly.

setDefaultForeground

public void setDefaultForeground(java.awt.Color c)

Set the default foreground color for this Exhibit. This would ordinarily be called in the constructor of a sub-class. Note that setting a default background color with setDefaultBackground(Color) automatically sets the default foreground color to black or white, depending on the default background color. If you want a different default foreground color, call setDefaultForeground after calling setDefaultBackground.

Parameters:

c - The default foreground color. If this is null, the default (black) is used.

getCreateAnimation

public Animation getCreateAnimation(View view)

This method is called to "create" the Exhibit. It should return an animation that will show the process of creating the Exhibit, whatever that means. The animation is run when the Exhibit is first shown on the screen (in the 3dxm shell program) and when the "Create" action command is invoked. If the return value is null, then there is no creation animation for this exhibit. If the return value is non-null, then it can be expected that the animation will be installed in the View's Display.

Parameters:

view - A View that is displaying this Exhibit. The animation, if any, that is returned by this method will be installed in the View's display. If the view is null, than a creation animation that can run independently of a view could be returned.

Returns:

A creation animation for the given View of this Exhibit. The return value can be null to indicate that no creation animation is to be run.

getMorphingAnimation

public BasicAnimator getMorphingAnimation(View view,
                                          int looping)

This method is meant to produce a "morph" animation for this Exhibit, by animating any applicable animateable parameters. The parameters can come from the Exhibit, from the View, and, in the case of a UserExhibit from the function parameters of the user exhibit. If there are no Animateable parameters, the return value is null. Otherwise, the return value is a BasicAnimator to which all of the Exhibit's Animateable parameters have been added. The number of frames in the animation returned by this method is the value of the "framesForMorphing" property. Subclasses might want to override this method to provide more complex morphing animations, but they should follow the same pattern. In particular, any parmeter values that are changed during the animation should be restored to their original values when the animation ends.

Parameters:

view - The view that the animation will be shown in, if any. If the value is null, then the animation will not be associated with any particular view. In that case, the Morphing animation will animate the Exhibit in all Views in which it appears, since it operates by changing parameters of the exhibit. If the View is non-null, then only the specified View will receive changeEvents from the Exhibit while the morph is in progress.

looping - This must be one of the values BasicAnimator.ONCE, BasicAnimator.LOOP, or BasicAnimator.OSCILLATE. The value is passed, without any error checking, to the animation's setLooping method.

See Also:

TimerAnimation.setLooping(int), setFramesForMorphing(int)

getBuildAnimation

public Animation getBuildAnimation(View view)

Returns a "build animation" for this Exhibit, or null if no build animation is to be used. A build animation is a very special animation that shows a bit-by-bit drawing of an Exhibit over a period of time. It uses the off-screen canvas facility provided by View.prepareOSIForDrawing(). An example of this is displaying a surface by drawing patches of the surface in back-to-front order.

This method is called by the render(Graphics2D, View, Transform, ArrayList) method before calling computeDrawData(View, boolean, Transform, Transform). If the return value is non-null, then the build animation is installed in the view as an alternative to drawing the exhibit directly. However, no build animation is installed if an animation is already in progress in the view's display, or if the View.getFastDrawing() method of the view returns true, or if the View is not using an off=screen image.

An Exhibit that has a build animation does not need a separate creation animation, since the build animation will be invoked automatically when the object is first drawn and when the Create command is given.

Parameters:

view - The view into which the build animation will be installed.

Returns:

The return value in this top-level Exhibit class is null.

forceRedraw

public void forceRedraw()

This method forces the Exhibit to be completely redrawn by marking it as needing to be redrawn and sending a change event to any ChangeListeners that have beeen registered with the Exhibit, presumably just to any Views that are showing this Exhibit. Note that Views will be forced to redraw their off-screen images. This method is called automatically when a Parameter that has been added to this Exhibit is changed. Note that calling this method will cause data cached in the Exhibit to be recomputed. In fact, this method simply sets exhibitNeedsRedraw to true and then calls fireExhibitChangeEvent().

render

public void render(java.awt.Graphics2D g,
                   View view,
                   Transform transform,
                   java.util.ArrayList<Decoration> extraDecorations)

This method is called by the View class when it needs to redraw the Exhibit. (Subclasses of the View class might not call this method -- a View class that is created just for a particular type of Exhibit might draw the Exhibit directly.) This method will not ordinarily be called directly, now will it be overridden in most subclasses.

The method in this class does the following: First, it calls the Exhibit's computeDrawData method and then the computeDrawData method of any decoration that has been associated with the View or with the Exhibit. Then, it calls the doDraw method of the Exhibit and Decorations; these are called in the order of the Decorations' layers with the Exhibit being considered as lying in layer number 0. Subclasses will ordinarily override code>computeDrawData and/or doDraw, rather than overriding this method.

Parameters:

g - The graphics context where the exhibit is to be drawn. The drawing area has already been cleared to the background color (assuming that this method is called from the render method in the top-level View class).

view - The View that is drawing the Exhibit; this object contains other information that might be of use, such as the Display, if any, associated with the View.

transform - Contains information about the rectangular area in the xy-plane that is being drawn and about the rectangle of pixels in the graphics context where it is drawn. Note that at least for the top-level View class, transform.getX() and transform.getY() can be assumed to be zero.

extraDecorations - Decorations that were added to the View that is being drawn; the value can be null.

See Also:

forceRedraw(), computeDrawData(View, boolean, Transform, Transform), doDraw(Graphics2D, View, Transform), getBuildAnimation(View), View.render(Graphics2D, int, int)

computeDrawDataHook

protected void computeDrawDataHook(View view,
                                   Transform transform)

Called by render to compute the draw data for the exhibit. This method just calls computeDrawData(View, boolean, Transform, Transform) and then records the prvious transform for use in the next call. This method is called by render(Graphics2D, View, Transform, ArrayList). It exists only as a hook to be overridded in the Exhibit3D class and probably will not be used except for that or perhaps other compex subclasses.

doDrawHook

protected void doDrawHook(java.awt.Graphics2D g,
                          View view,
                          Transform transform)

Called by render to this exhibit. This method just calls doDraw(Graphics2D, View, Transform) This method is called by render(Graphics2D, View, Transform, ArrayList). It exists only as a hook to be overridded in the Exhibit3D class and probably will not be used except for that or perhaps other compex subclasses.

computeDrawData

protected void computeDrawData(View view,
                               boolean exhibitNeedsRedraw,
                               Transform previousTransform,
                               Transform newTransform)

Recompute any cached data in the Exhibit that might have changed since it was computed. This method is called (indirectly through computeDrawDataHook) by the render method before it calls doDraw. Its purpose is to give the Exhibit a chance to recalculate any data that it needs in order to draw itself. Not all Exhibits will need to "cache" computed data in this way. The method in this top-level exhibit class does nothing.

Parameters:

view - The View that is drawing the Exhibit.

exhibitNeedsRedraw - This parameter is set to "true" if the Exhibit's forceRedraw() method has been called since the last redraw. If it is true, then presumably the appearance of the Exhibit has changed, so any cached data should be recomputed.

previousTransform - The Transform object that was used the last time the Exhibit was drawn. This can be null if the Exhibit is being drawn for the first time.

newTransform - The Transform object that is being used for this drawing of the Exhibit. Transform objects contain data about the window in the xy-plane where the Exhibit is being drawn and about the pixel coordinates on the drawing area. The two Transform objects are provided in case any cached data depends on the xy-window or on the pixel coordinates. Note that the Transform might have changed even if exhibitNeedsRedraw is false.

See Also:

render(Graphics2D, View, Transform, ArrayList), forceRedraw(), doDraw(Graphics2D, View, Transform)

doDraw

protected void doDraw(java.awt.Graphics2D g,
                      View view,
                      Transform transform)

Do the actual drawing of the exhibit. This method is called (indirectly through doDrawHook) by render to draw the Exhibit. The computeDrawData method is called by render before it calls this method, so any cached data should be valid by the time this method is called. The method in this class does nothing. Subclasses should override this method, unless they provide some other technique for drawing the Exhibit.

Parameters:

g - The graphics context where the Exhibit is being drawn. It has already been cleared to the background color (assuming that drawing is being done in the usual way, as defined in the top-level View class).

view - The View that is drawing the Exhibit; this object contains other information that might be of use, such as the Display, if any, associated with the View.

transform - Contains information about the rectangular area in the xy-plane that is being drawn and about the rectangle of pixels in the graphics context where it is drawn. Note that at least for the top-level View class, transform.getX() and transform.getY() can be assumed to be zero.

See Also:

render(Graphics2D, View, Transform, ArrayList), computeDrawData(View, boolean, Transform, Transform)