Display
vmm3d.core

Class Display

  • All Implemented Interfaces:
    ImageObserver, MenuContainer, Serializable, Accessible
    Direct Known Subclasses:
    DisplayXM


    public class Displayextends JPanel
    A Display is a canvas where a View can draw an Exhibit. A display can manage an Animation; it has methods for installing, stopping, controlling the speed, and pausing an animation. It can also manage MouseTasks, which respond to user mouse clicks on the Display. A View can define a MouseTask that is active as long as the View is installed in the Display. It is also possible to install a "one-shot mouse task" that is active only for one user mouse action.

    A display can have an associated container, which can be obtained by calling getHolder(). The ordinary way to add a display is to add this "holder" to a parent container, rather than adding the display itself. The holder holds a status bar in addition to the display, and other components can be added as well using addBorderComponent(Component, Object). The status bar can be hidden. In addition, if the display is in a holder, it is possible to "split" the holder, with the display in one half and another component in the other half. Note that exhibits that use the capabilities associated with the holder might not function fully if the display is not contained in a holder. Ordinarily, you should not do anything with the holder directly except add it to a parent component. Note that whenever an exhibit is removed from the display, the holder is reset to its default state, showing only the display and (if it has not been hidden) the status bar.

    See Also:
    Serialized Form
    • Field Detail

      • FILMSTRIP_AVAILABLE_PROPERTY

        public static final String FILMSTRIP_AVAILABLE_PROPERTY
        The property name for PropertyChangeEvents that are sent when a filmstrip becomes available for replay, or when a filmstrip stops being availble. The value of the property is of type Boolean.
        See Also:
        Constant Field Values
      • STATUS_PROPERTY

        public static final String STATUS_PROPERTY
        The property name for PropertyChangeEvents that are sent when the status of the display changes. The status of the Display tells whether an Exhibit is installed, whether an animation is running, and whether a one-shot mouse task is active. A Display sends PropertyChangeEvents when its status changes. The value of the STATUS property is one of the constants STATUS_EMPTY, STATUS_IDLE, STATUS_RUNNING, STATUS_ANIMATION_RUNNING, STATUS_ANIMATION_PAUSED, or STATUS_ONE_SHOT_MOUSE_TASK.
        See Also:
        Constant Field Values
      • STATUS_EMPTY

        public static final String STATUS_EMPTY
        A value for the STATUS property that indicates that no Exhibit is currently installed.
        See Also:
        Constant Field Values
      • STATUS_IDLE

        public static final String STATUS_IDLE
        A value for the STATUS property that indicates that an Exhibit is currently installed, but no animation or one-shot mouse task is active.
        See Also:
        Constant Field Values
      • STATUS_ANIMATION_RUNNING

        public static final String STATUS_ANIMATION_RUNNING
        A value for the STATUS property that indicates that an animation is installed and is running.
        See Also:
        Constant Field Values
      • STATUS_ANIMATION_PAUSED

        public static final String STATUS_ANIMATION_PAUSED
        A value for the STATUS property that indicates that an animation is installed but is currently paused.
        See Also:
        Constant Field Values
      • STATUS_ONE_SHOT_MOUSE_TASK

        public static final String STATUS_ONE_SHOT_MOUSE_TASK
        A value for the STATUS property that indicates that a one-shot mouse task is currently active.
        See Also:
        Constant Field Values
      • AUX_VIEW_ON_LEFT

        public static final int AUX_VIEW_ON_LEFT
        A constant that can be used in to specify the position of the auxiliary view.
        See Also:
        Constant Field Values
      • AUX_VIEW_ON_RIGHT

        public static final int AUX_VIEW_ON_RIGHT
        A constant that can be used in to specify the position of the auxiliary view.
        See Also:
        Constant Field Values
      • AUX_VIEW_ON_TOP

        public static final int AUX_VIEW_ON_TOP
        A constant that can be used in to specify the position of the auxiliary view.
        See Also:
        Constant Field Values
      • AUX_VIEW_ON_BOTTOM

        public static final int AUX_VIEW_ON_BOTTOM
        A constant that can be used in to specify the position of the auxiliary view.
        See Also:
        Constant Field Values
    • Constructor Detail

      • Display

        public Display()
        Construct an initially empty Display.
    • Method Detail

      • getVectorGraphics

        public org.freehep.graphics2d.VectorGraphics getVectorGraphics()
      • getSavedFilmstrip

        public Filmstrip getSavedFilmstrip()
        Get the Filmstrip, if any, that has been created by a recent animation. If there is no such Filmstrip, the return value is null.
      • getSavedFilmstripLooping

        public int getSavedFilmstripLooping()
        Get the looping mode () of the Filmstrip that has been created by a recent animation. If there is no such filmstrip, the return value is -1.
      • install

        public void install(View view,           Exhibit exhibit)
        Install a specified View and Exhibit into this Display. If there is a previously installed View or Exhibit, it is removed first. This method is intended to do all the busy work that is necessary to associate a Display, a View, and an Exhibit. For example, it calls the setExhibit method of the view, which in turn will set up the View as a ChangeListener for the Exhibit. Users of these classes should not have to worry about this make-work stuff.

        Note that installing a view and exhibit will cancel any animation or mouse task associated with the Display. It will also emove any extra components that have been added by addBorderComponent(Component, Object) or split(Component). After calling this method, the status of the Display will be STATUS_IDLE or STATUS_EMPTY.

        Note: Calling this method ALWAYS removes any auxiliary view from the display. Sett installAuxiliaryView(View, View).)

        Parameters:
        view - The View to be installed. This can be null; If both parameters are null, then any previously installed View is removed and no View is associated with the Display. If the view parameter is null and the exhibit parameter is not, then the default view for the exhibit is obtained by calling Exhibit.getDefaultView().
        exhibit - An Exhibit for the View to draw. It should be an Exhibit that the specified view is capable of drawing. If this parameter is not null and the view parameter is null, then the default View for the Exhibit is used. If the exhibit parameter is null and the view parameter is non-null and the view already has an exhibit installed, then the exhibit is set to the view's current exhibit.
      • getView

        public View getView()
        Returns the View that is curently installed in this display. If no View is installed, the return value is null. Note that in the case where there is an auxiliary view, it is the main view that is returned by this method (see installAuxiliaryView(View, View, int, double, boolean)).
      • installAuxiliaryView

        public boolean installAuxiliaryView(View mainView,                           View auxiliaryView)
        Add an extra view to the display, which will always occupy half of the display. The extra view will appear to the left of the main view. This method can be called with auxiliaryView == null to remove the current auxliary view, if any. This method simply calls installAuxiliaryView(mainView,auxiliaryView,Display.AUX_VIEW_ON_LEFT,0.5,false).
        Parameters:
        mainView - This parameter must equal the current main view of the display. If not, nothing further is done and the return value of them method will be false.
        auxiliaryView - The auxliary view that is to be installed to the left of the main view in this Display.
        Returns:
        true if the auxiliary view is installed. The only case where the return value is not true is if the mainView parameter in the method call does not match the current main view in the display.
      • installAuxiliaryView

        public boolean installAuxiliaryView(View mainView,                           View auxliaryView,                           int auxViewPosition,                           double fractionOfDisplay,                           boolean resizable)
        Add an extra view to the display. This method can be called with auxiliaryView == null to remove the current auxliary view, if any.
        Parameters:
        mainView - This parameter must equal the current main view of the display. If not, nothing further is done and the return value of them method will be false.
        auxliaryView - The auxliary view that is to be installed to the left of the main view in this Display.
        auxViewPosition - specifies where the extra view is placed in relation to the main view. This must be one of the constants Display.AUX_VIEW_ON_LEFT, Display.AUX_VIEW_ON_RIGHT, Display.AUX_VIEW_ON_TOP, or Display.AUX_VIEW_ON_BOTTOM. If not, an IllegalArgumentException is thrown.
        fractionOfDisplay - a number in the range 0.0 to 1.0 specifying the fraction of the display that is to be occupied by the auxiliary view.
        resizable - if true, then the user can drag the bar that separates the auxiliary view from the main view in order to change the fraction of the display that is allocated to the main view.
        Returns:
        true if the auxiliary view is installed. The only case where the return value is not true is if the mainView parameter in the method call does not match the current main view in the display.
        See Also:
        installAuxiliaryView(View, View)
      • getExhibit

        public Exhibit getExhibit()
        Return the Exhibit that is currently installed in the display. If no View is associated with the Display, this returns null. Otherwise, it returns the exhibit associated with the current View; this value can also be null even if the view is not null;
      • paintComponent

        public void paintComponent(Graphics g)
        Draw the Exhibit, if any. This method always draws the Exhibit using a graphics context in which the upper left corner is (0,0) and such that any Border that has been added to the display is not included in the drawing area of this graphics context. If a View is installed in the Display, then that view is responsible for all drawing. If not, the Display is simply filled with the white backgroun color.
        Overrides:
        paintComponent in class JComponent
      • installAnimation

        public void installAnimation(Animation anim)
        Install an animation in the display and start it running. Any previously running animation is first canceled. If a one-shot mouse task is active, it is canceled. (Animations and one-shot mouse tasks are mutually exclusive; only one can be installed at any given time.)
        Parameters:
        anim - The animation to be installed. If this is null, no animation is installed, but any current animation or one-shot mouse task is still canceled.
      • stopAnimation

        public void stopAnimation()
        Stop any animation that is currently installed. If no animation is installed, this has no effect. Note that an animation that stops on its own is automatially removed from the display when it stops. An animation that runs forever will continue to run until it is stopped explicitely by calling this method or by installing another animation or one-shot mouse task, or by removing the current exhibit from the display, or when the user clicks the mouse on this Display.
      • toggleAnimationPaused

        public void toggleAnimationPaused()
        Pause the current animation, if it is currently running, or resume it if it is currently paused. If no animation is currently installed in the display, this has no effect.
      • setTimeDilationForAnimations

        public void setTimeDilationForAnimations(double dilationFactor)
        Sets the speed for any animation that runs in this display. This is done by calling the setTimeDilation method of each animation. Note that this applies not just the current animationn that is running in the display, but to any animation that is installed in the future.
        Parameters:
        dilationFactor - The time dilation factor for animations. The default value, 1, means that animations run at normal speed. A factor of 2 means they run at half speed, of 3 means that they run at 1/3 speed, and so on. It is also possible to speed up animations by using a time dilation factor between 0 and 1, but speed-up is always limited by processing time required by the animation.
        See Also:
        Animation.setTimeDilation(double)
      • getTimeDilationForAnimations

        public double getTimeDilationForAnimations()
        Returns the speed factor for animations that run in this display.
        See Also:
        setTimeDilationForAnimations(double)
      • discardFilmstrip

        public void discardFilmstrip()
        If this disply has saved a filmstrip from the most recent animation, the animation is discarded (freeing up the memory used by the filmstrip).
      • playFilmstrip

        public void playFilmstrip(Filmstrip filmstrip,                 int looping,                 Dimension preferredSize)
        This method plays a specified filmstrip animation. After the animation is played, the Display returns to its previous state, showing the same Exhibit.
        Parameters:
        filmstrip - the filmstrip to be played. If this value is null, then the method call is simply ignored.
        looping - determines whether the filmstrip is played once through, or in a loop, or oscillating back and forth. The value is one of TimerAnimation.LOOP, TimerAnimation.OSCILLATE, or TimerAnimation.ONCE.
        preferredSize - If this is non-null, then the preferred size of the display is set to this value. In the 3DXM application, this will cause the window to change size. After the animation, the preferred size of the display is set to the size of the display before the animation began (note: not the preferred size, which might be different from the actual size).
      • playFilmstrip

        public void playFilmstrip()
        If there is a saved filmstrip in the display, this will play it back.
      • getStopAnimationsOnResize

        public boolean getStopAnimationsOnResize()
        Get the property that determines whether animations in this view are stopped when a resize occurs.
        See Also:
        setStopAnimationsOnResize(boolean)
      • setStopAnimationsOnResize

        public void setStopAnimationsOnResize(boolean stopAnimationsOnResize)
        Set the stopAnimationOnResize property, which determines whether animations in this view are stopped when a resize occurs and whether fastDrawing is used during resize. The default value is true, and should only be set to false on rare occasions. This property is meant to be managed by a View that is displayed in this display. Whenever a new View is installed, the value of this property is reset to true.

        (This property was introduced only because resize events are generated when the display is split and when components are added to or removed from the "holder" (see getHolder()). When either of these two actions is taken at the time a view is installed in the display, the create animation will be stopped by the resize event unless the stopAnimationOnResize property has been set to false. This affects the ConformalMap category, where the display is split when the exhibit is first installed, and ODE categories, where a control panel is added to the holder when the exhibit is first installed.)

      • installMouseTask

        public void installMouseTask(MouseTask task)
        Install a default mouse handler for this Display. This mouse task will remain active until a new exhibit is installed or until a new default mouse task is installed using this method. When a new Exhibit is installed, its default mouse task is automatically installed in the display.

        Note that this installs the mouse task for the main view, in the case where there is also an auxiliary view (see installAuxiliaryView(View, View)).

        If a one-shot mouse task is active (in the main view) when this method is installed, the one-shot mouse task is canceled.

      • getMouseTask

        public MouseTask getMouseTask()
        Returns the current mouse task. Note that this returns the default mouse handler for the display. The default mouse task is installed by installMouseTask(MouseTask) or is installed automatically when an Exhibit is installed. The value can be null. Any one-shot mouse task, as installed with installOneShotMouseTask(MouseTask), is not the value that is returned here.
      • installAuxiliaryMouseTask

        public void installAuxiliaryMouseTask(MouseTask task)
        Install a default mouse handler for the auxiliary view in Display. Nothing will be done if there is no auxiliary view in the display.

        If a one-shot mouse task is active in the auxiliary view when this method is installed, the one-shot mouse task is canceled.

      • installOneShotMouseTask

        public void installOneShotMouseTask(MouseTask task)
        Install a mouse task that will fire just once (or maybe a few times). After each click, the mouse task's MouseTask.wantsMoreClicks(Display, View) method is called to see whether it should be removed from the display. This takes precedence over any default mouse task installed by the installMouseTask method, but the default mouse task is restored after the one-shot mouse task is removed. The one-shot mouse task will be canceled if an animation is installed, or if another one-shot mouse task is installed, or if a new Exhbit is installed. Since animations and one-shot mouse tasks are mutually exclusive, installing a one-shot mouse task will cancel any animation that is currently running in the display.

        Note that in the case where there is an auxiliary view in this display, this installs a mouse task that is active only in the main display. If the user clicks the auxiliary view while a one-shot mouse task is active in the main display, the user is told to click the main view instead.

        See Also:
        installMouseTask(MouseTask)
      • installAuxiliaryOneShotMouseTask

        public void installAuxiliaryOneShotMouseTask(MouseTask task)
        Install a mouse task in the auxiliary view that will fire just once (or maybe a few times). After each click, the mouse task's MouseTask.wantsMoreClicks(Display, View) method is called to see whether it should be removed from the display. This takes precedence over any default mouse task installed by the installAuxiliaryMouseTask method, but the default mouse task is restored after the one-shot mouse task is removed. The one-shot mouse task will be canceled if an animation is installed, or if another one-shot mouse task is installed, or if a new Exhbit is installed. Since animations and one-shot mouse tasks are mutually exclusive, installing a one-shot mouse task will cancel any animation that is currently running in the display.

        Note that this installs a one-shot mouse task that is active only in the main display. If the user clicks the main view while a one-shot mouse task is active in the auxiliary display, the user is told to click the main view instead.

        See Also:
        installMouseTask(MouseTask), installOneShotMouseTask(MouseTask)
      • setShowStatusBar

        public void setShowStatusBar(boolean show)
        Sets the value of the showStatusBar property. If this property is true, then a status bar will be shown at the bottom of the container that is returned by getHolder().
      • getShowStatusBar

        public boolean getShowStatusBar()
        Returns the value of the showStatusBar property.
        See Also:
        setShowStatusBar(boolean)
      • getStatusText

        public String getStatusText()
        Returns the string from the status bar. If no holder holder has been created for this display (by calling getHolder()), then the return value is null; otherwise, the return value is the text from the JLabel that is used in the status bar of the holder. (This works even if the status bar is currently hidden.)
      • setStatusText

        public void setStatusText(String message)
        Sets the text to be displayed in the status bar of the holder for this display. If no holder has been created for this display (by calling getHolder()), then this method has no effect at all. If the parameter is null, then a status string is obtained as follows: If there is no exhibit in the display, then the status string is "No Exhiibt" (in the default English locale); otherwise if there is an animation, the animation's Animation.getStatusText(boolean) method is called to get the status string, and if the return value is null the string "Animation Runing" or "Animation Paused" is used; otherwise if there is a one-shot mouse task its MouseTask.getStatusText() method is called, and if the return value is null then the string "Waiting for mouse input" is used; otherwise, if there is a mouse task and if the MouseTask.getStatusText() method in the mouse task returns a non-null value, then that is used as the status string; otherwise, the current view's View#getStatusText() method is called and if it returns a non-null value then that is used as the status text; otherwise, the status string is set to the current exhibit's title. The idea to is provide a reasonable default string that describes the current status, but to allow animations, mouse tasks, and views to specify alternative strings as appropriate; this will probably be most useful for one-shot mouse tasks. Note that the status string changes automatically when a new exhibit, animation, mouse task, or one-shot mouse task is installed, and the previous string is discarded. It will be relatively rare to call this method directly.
        Parameters:
        message - the string to be displayed in the status bar, or null to construct a string based on the current state of the display.
      • addBorderComponent

        public void addBorderComponent(Component c,                      Object position)
        Adds an extra component to the display's holder. Has no effect unless a holder has been created for the display by calling getHolder(). This method adds a component in the north, south, east, or west postions of the holder's BorderLayout.
        Parameters:
        c - the component to be added. This should be non-null.
        position - specifies the position to be occupied by the component. Must be one of the values BorderLayout.NORTH, BorderLayout.EAST, BorderLayout.WEST, or BorderLayout.SOUTH. If the value is BorderLayout.SOUTH, the status bar that usually occupies that postion will be removed, the showStatusBar property will be set to false, and the new component will be placed in the south position. You should be careful not to add two components in the same position; no error-checking is done to prevent this.
        Throws:
        IllegalArgumentException - if position is not one of the four legal values
      • removeBorderComponent

        public void removeBorderComponent(Component c)
        Removes a specified component from the display's holder. This has no effect if no holder has been created for the display (by calling getHolder()).
        Parameters:
        c - the component to be removed. Presumably, this is a component that has been added to the holder by calling addBorderComponent(Component, Object), but no error checking is done. The holder's remove() method is simply called with c as its parameter.
      • split

        public JSplitPane split(Component newComponent,               boolean splitVertically,               boolean displayIsSecondComponent)
        Replaces the display in its holder with a JSplitPane that contains the display and another component. Has no effect if no holder has been created for this display (by calling getHolder(). If the display has aleady been split, the previous JSplitPane and its extra component are thrown away. Note that split(Component) calls this method with the most likly value (false) for the second and third parameters.
        Parameters:
        newComponent - the other component, in addition to the display, that will replace the display in the center position of the holder
        splitVertically - if true, the JSplitPane is split vertically; if false, it is split horizontally
        displayIsSecondComponent - if true, the display is in the right or bottom position of the split pane; if false, it is in the left or top position
        Returns:
        the JSplitPane, in case you want to do further customization. The pane is set to use half the available height or width for each component, to distribute new space equally during a resize of the pane, and to have no border.
      • resetHolder

        public void resetHolder()
        Restores the holder to its default state; this is called automatically by install(View, Exhibit). Has no effect if no holder has been created for this display.
        See Also:
        getHolder()
      • getHolder

        public Container getHolder()
        Returns the container or "holder" for this display. The usual way to use a Display is to call this method to get its holder, and add the holder to a parent container rather than the Display itself. You should ordinarily not do anything else with the holder except to add it to a container. The holder uses a BorderLayout with the display in its center position. It has a status bar in its south position; the status bar can be hidden and shown using setShowStatusBar(boolean). Other components can be added to the holder using addBorderComponent(Component, Object), split(Component), and split(Component, boolean, boolean). The holder uses black as its background color with gaps of 1 pixel between the components that it contains. When a new exhibit is installed (including when the exhibit is set to null), the holder is restored to its default state (BorderLayout with 1-pixel gaps, black background, display in center postion, and staus bar in south postion if the showStatusBar property is true).
      • processComponentEvent

        public void processComponentEvent(ComponentEvent evt)
        Used to call stopAnimation() if the size of the Display changes; not meant to be called directly. Stops any ongoing animation and sets "fast drawing mode" to true so that the exhibit can be continually redrawn as the display is resized.
        Overrides:
        processComponentEvent in class Component

SCaVis 2.0 © jWork.ORG