Exhibit
vmm3d.core

Class Exhibit

  • All Implemented Interfaces:
    EventListener, ChangeListener, Decorateable, Parameterizable
    Direct Known Subclasses:
    Exhibit3D, Mandelbrot, ODE_2D, PlaneCurve, RepeatedSegmentFractal


    public abstract class Exhibitextends Objectimplements Parameterizable, Decorateable, 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.

    • Constructor Detail

      • Exhibit

        public Exhibit()
    • Method Detail

      • getName

        public 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(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 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.
      • 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(Document containingDocument,               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)
      • addChangeListener

        public void addChangeListener(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(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.
      • stateChanged

        public void stateChanged(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 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(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.
      • parameterChanged

        public void parameterChanged(Parameter param,                    Object oldValue,                    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 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)
      • 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 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(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 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(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(org.freehep.graphics2d.VectorGraphics g,          View view,          Transform transform,          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)

SCaVis 1.8 © jWork.org