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.
Decorations that have been associated with this Exhibit (presumably through the addDecoration(Decoration) method).
This variable is set to true when the Exhibit changes in a way that needs redrawing.
Parameters that have been associated with this Exhibit (presumably by the addParameter(Parameter) method).
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.
Add a ChangeListener to this Exhibit.
Add a decoration that will appear in all Views of this Exhibit.
Associate a parameter with this Exhibit.
Adds a view to the list of views that are displaying this Exhibit.
Remove all decorations from the Exhbiit.
Called by render to compute the draw data for the exhibit.
Called by render to this exhibit.
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.
This method returns additionAal View objects that can be used to view this Exhibit, in addition to the view returned by getDefaultView().
Returns a "build animation" for this Exhibit, or null if no build animation is to be used.
Returns a list of decorations that have been added directly to this exhibit.
Returns the default background color desired by this Exhibit.
Returns the default foreground color desired by this Exhibit.
Returns a default Transform object to be used in the specified View.
This method returns a default View object for viewing this Exhibit.
Returns a four-element array rerpresening the default Window in the xy-plane in which this Exhibit wants to be displayed.
Tells how many frames are to be used by a morphing animation, as returned by getMorphingAnimation(View, int).
This method is meant to produce a "morph" animation for this Exhibit, by animating any applicable animateable parameters.
Returns a name for this Exhibit.
Returns a paramter that is associated with this Exhibit and that has the specified name, if there is one.
Returns an array containing all the parameters associated with this Exhibit.
Returns a human-readable title for this Exhibit that could, for example, be used in a menu that is presented to the user.
Returns the value of the useFilmstripForMorping property.
Returns a list of Views that are displaying this Exhibit.
Remove a ChangeListener from this Exhibit.
Remove a specified Decoration, if present.
Removes a parameter from this Exhibit.
Removes a view from the list of views that are displaying this Exhibit.
This method is called by the View class when it needs to redraw the Exhibit.
Set the default background color for this Exhibit.
Set the default foreground color for this Exhibit.
Sets the default window in the xy-plane for viewing this Exhibit, using xy-limits from an array.
Set the default window in the xy-plane for viewing this Exhibit.
Set the number of frames to be used in a moprphing animation, as returned by getMorphingAnimation(View, int).
Sets the value of the useFilmstripForMorphing property.
Sends a change event, presumably in response to a change in one of the Decorations that have been added to this Exhibit.
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 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.
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.
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.
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().
Sets the name for this view. In general, the default name, consisting of the full class name of the Exhibit object, should be sufficient.
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.
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.
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.
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.
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.
listener - The listener to be added to the exhibit. If the value is null, nothing is done.
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.
listener - The listener to be removed. If it is not currently registered with the Exhibit, then nothing is done.
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.
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.
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.
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.
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.
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.
param - The parameter to be added. If the parameter is null, it is ignored. Adding a parameter for a second time has no effect.
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).
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.
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.
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.
view - The view that that is about to start displaying this Exhibit.
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.
Returns a list of Views that are displaying this Exhibit. The return value can be null.
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.
d - The decoration to be removed. If this is null or or has not been added to this Exhibit then nothing is done.
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.
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.
An array containing alternative views for this exhibit. In the top-level Exhibit class, the return value is null.
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.
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,window,window,window).
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.
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.
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.
c - The default background color. If this is null, the default (white) is used.
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.
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.
c - The default foreground color. If this is null, the default (black) is used.
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.
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.
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().
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.
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).
extraDecorations - Decorations that were added to the View that is being drawn; the value can be null.
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.
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.