Package sim.display

Class Display2D

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
sim.display.Display2D
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Manipulating2D, Steppable
public class Display2D extends JComponent implements Steppable, Manipulating2D
Display2D holds, displays, and manipulates 2D Portrayal objects, allowing the user to scale them, scroll them, change how often they're updated, take snapshots, and generate Quicktime movies. Display2D is Steppable, and each time it is stepped it redraws itself. Display2D also handles double-click events, routing them to the underlying portrayals as inspector requests.

In addition to various GUI widgets, Display2D holds a JScrollView which in turn holds a Display2D.InnerDisplay2D (a JComponent responsible for doing the actual drawing). Display2D can be placed in a JFrame; indeed it provides a convenience function to sprout its own JFrame with the method createFrame(). You can put Display2D in your own JFrame if you like, but you should try to call Display2D.quit() when the frame is disposed.

Display2D's constructor takes a height and a width; this will be the "expected" height and width of the underlying portrayal region when the Display2D is scaled to 1.0 (the default). The portrayals will also have an origin at (0,0) -- the top left corner. Display2D will automatically clip the portrayals to the area (0,0) to (width * scale, height * scale).

Display2D's step() method is typically called from the underlying schedule thread; this means that it has to be careful about painting as Swing widgets expect to be painted in the event loop thread. Display2D handles this in two ways. First, on MacOS X, the step() method calls repaint(), which will in turn call paintComponent() from the event loop thread at a time when the underlying schedule thread is doing nothing -- see Console. Second, on Windows and XWindows, the step() method immediately calls paintComponent(). Different OSes do it differently because MacOS X is far more efficient using standard repaint() calls, which get routed through Quartz. The step() method also updates various widgets using SwingUtilities.invokeLater().

See Also:

  • Field Details

    • DEFAULT_PREFERENCES_KEY

      public String DEFAULT_PREFERENCES_KEY

    • isMacOSX

      public static final boolean isMacOSX
      Set to true if we're running on a Mac

    • isWindows

      public static final boolean isWindows
      Set to true if we're running on Windows

    • javaVersion

      public static final String javaVersion
      Set to the version number

    • OPEN_HAND_CURSOR_P

      public static final ImageIcon OPEN_HAND_CURSOR_P

    • CLOSED_HAND_CURSOR_P

      public static final ImageIcon CLOSED_HAND_CURSOR_P

    • LAYERS_ICON

      public static final ImageIcon LAYERS_ICON

    • LAYERS_ICON_P

      public static final ImageIcon LAYERS_ICON_P

    • REFRESH_ICON

      public static final ImageIcon REFRESH_ICON

    • REFRESH_ICON_P

      public static final ImageIcon REFRESH_ICON_P

    • MOVIE_ON_ICON

      public static final ImageIcon MOVIE_ON_ICON

    • MOVIE_ON_ICON_P

      public static final ImageIcon MOVIE_ON_ICON_P

    • MOVIE_OFF_ICON

      public static final ImageIcon MOVIE_OFF_ICON

    • MOVIE_OFF_ICON_P

      public static final ImageIcon MOVIE_OFF_ICON_P

    • CAMERA_ICON

      public static final ImageIcon CAMERA_ICON

    • CAMERA_ICON_P

      public static final ImageIcon CAMERA_ICON_P

    • OPTIONS_ICON

      public static final ImageIcon OPTIONS_ICON

    • OPTIONS_ICON_P

      public static final ImageIcon OPTIONS_ICON_P

    • REDRAW_OPTIONS

      public static final Object[] REDRAW_OPTIONS

    • insideDisplay

      public Display2D.InnerDisplay2D insideDisplay
      The 2D display inside the scroll view. Does the actual drawing of the simulation.

    • optionPane

      public Display2D.OptionPane optionPane
      Our option pane

    • portrayals

      public ArrayList portrayals
      The list of portrayals the insideDisplay draws. Each element in this list is a Portrayal2DHolder.

    • display

      public JScrollPane display
      The scroll view which holds the insideDisplay.

    • layersbutton

      public JToggleButton layersbutton
      The button which pops up the layers menu

    • refreshPopup

      public JPopupMenu refreshPopup
      The refresh menu

    • refreshbutton

      public JToggleButton refreshbutton
      The button which pops up the refresh menu

    • movieButton

      public JButton movieButton
      The button which starts or stops a movie

    • snapshotButton

      public JButton snapshotButton
      The button which snaps a screenshot

    • optionButton

      public JButton optionButton
      The button which pops up the option pane

    • scaleField

      public NumberTextField scaleField
      The field for scaling values

    • skipField

      public NumberTextField skipField
      The field for skipping frames

    • skipBox

      public JComboBox skipBox
      The combo box for skipping frames

    • skipFrame

      public JFrame skipFrame
      The frame which holds the skip controls

    • SELECTION_MODE_MULTI

      public static final int SELECTION_MODE_MULTI
      See Also:

    • SELECTION_MODE_SINGLE

      public static final int SELECTION_MODE_SINGLE
      See Also:

    • TYPE_PDF

      public static final int TYPE_PDF
      See Also:

    • TYPE_PNG

      public static final int TYPE_PNG
      See Also:

    • UPDATE_RULE_STEPS

      public static final int UPDATE_RULE_STEPS
      Used internally and by Display3D to indicate
      See Also:

    • UPDATE_RULE_INTERNAL_TIME

      public static final int UPDATE_RULE_INTERNAL_TIME
      See Also:

    • UPDATE_RULE_WALLCLOCK_TIME

      public static final int UPDATE_RULE_WALLCLOCK_TIME
      See Also:

    • UPDATE_RULE_ALWAYS

      public static final int UPDATE_RULE_ALWAYS
      See Also:

    • UPDATE_RULE_NEVER

      public static final int UPDATE_RULE_NEVER
      See Also:

    • updateRule

      protected int updateRule

    • stepInterval

      protected long stepInterval

    • timeInterval

      protected double timeInterval

    • wallInterval

      protected long wallInterval

  • Constructor Details

    • Display2D

      public Display2D(double width, double height, GUIState simulation, long interval)
      Deprecated.
      Creates a Display2D with the provided width and height for its portrayal region, attached to the provided simulation. The interval is ignored.

    • Display2D

      public Display2D(double width, double height, GUIState simulation)
      Creates a Display2D with the provided width and height for its portrayal region, attached to the provided simulation, and displaying itself with the given interval (which must be > 0).

  • Method Details

    • getPrecise

      public boolean getPrecise()
      Returns true if this display has been set to always draw precisely. Note that even if this function returns false, the display may draw precisely in certain circumstances, such as when outputting to a PDF.

    • setPrecise

      public void setPrecise(boolean precise)
      Sets this display to always draw precisely (or not). Note that even if this display has been set to not display precisely, it may still draw precisely in certain circumstances, such as when outputting to a PDF.

    • setPreferencesKey

      public void setPreferencesKey(String s)
      If you have more than one Display2D in your simulation and you want them to have different preferences, set each to a different key value. The default value is DEFAULT_PREFERENCES_KEY. You may not have a key which ends in a forward slash (/) when trimmed Key may be set to null (the default).

    • getPreferencesKey

      public String getPreferencesKey()

    • removeListeners

      public void removeListeners()
      Removes all mouse listeners, mouse motion listeners, and Key listeners from this component. Mostly used for kiosk mode stuff -- see the Howto

    • setScale

      public void setScale(double val)
      Sets the scale (the zoom value) of the Display2D

    • getScale

      public double getScale()
      Returns the scale (the zoom value) of the Display2D

    • isClipping

      public boolean isClipping()
      Returns true if the Display2D is clipping the drawing area to the user-specified height and width

    • setClipping

      public void setClipping(boolean val)
      Sets the Display2D to clip or to not clip to the user-specified height and width when drawing

    • setBackdrop

      public void setBackdrop(Paint c)
      Specify the backdrop color or other paint. The backdrop is the region behind where the simulation actually draws. If set to null, no color/paint is used -- and indeed the background you're drawing on is not defined. Only set to null if you know you're filling the entire background with something else anyway.

    • getBackdrop

      public Paint getBackdrop()
      Returns the backdrop color or paint. The backdrop is the region behind where the simulation actually draws. If set to null, no color/paint is used.

    • getScrollPosition

      public Double2D getScrollPosition()
      Returns the current scroll positions (x and y) as proportional values between 0.0 (minimum scroll position) and 1.0 (maximum scroll position).

    • setScrollPosition

      public void setScrollPosition(Double2D vals)
      Sets the current scroll positions (x and y) to proportional values between 0.0 (minimum scroll position) and 1.0 (maximum scroll position).

    • setScrollPosition

      public void setScrollPosition(double x, double y)
      Sets the current scroll positions (x and y) to proportional values between 0.0 (minimum scroll position) and 1.0 (maximum scroll position).

    • setOffset

      public void setOffset(double x, double y)
      Sets the offset of the origin of the display. By default the offset is (0,0).

    • setOffset

      public void setOffset(Point2D.Double d)
      Sets the offset of the origin of the display. By default the offset is (0,0).

    • getOffset

      public Point2D.Double getOffset()
      Returns the offset of the origin of the display. By default the offset is (0,0).

    • quit

      public void quit()
      Quits the Display2D. Called by the Display2D's frame if the Display2D made the frame itself. Also called by finalize(). Otherwise you should call this method before destroying the Display2D.

    • reset

      public void reset()
      Resets the Display2D so it reschedules itself and clears out all selections. This is useful when reusing the Display2D.

    • attach

      public void attach(FieldPortrayal2D portrayal, String name)
      Attaches a portrayal to the Display2D, along with the provided human-readable name for the portrayal. The portrayal will be attached with an origin at (0,0) and a width and height equal to the Display2D's default width and height. Portrayals are drawn on-screen in the order that they are attached; thus the "top-most" portrayal will be the last one attached.

    • attach

      public void attach(FieldPortrayal2D portrayal, String name, Rectangle2D.Double bounds)
      Attaches a portrayal to the Display2D, along with the provided human-readable name for the portrayal. The portrayal's attached origin, width and height is given in the bounds rectangle. Portrayals are drawn on-screen in the order that they are attached; thus the "top-most" portrayal will be the last one attached.

    • attach

      public void attach(FieldPortrayal2D portrayal, String name, boolean visible)
      Attaches a portrayal to the Display2D, along with the provided human-readable name for the portrayal. The portrayal will be attached with an origin at (0,0) and a width and height equal to the Display2D's default width and height. The portrayal may be set to initially visible or not visible. Portrayals are drawn on-screen in the order that they are attached; thus the "top-most" portrayal will be the last one attached.

    • attach

      public void attach(FieldPortrayal2D portrayal, String name, double x, double y, boolean visible)
      Attaches a portrayal to the Display2D, along with the provided human-readable name for the portrayal. The portrayal's attached origin is given with the coordinates provided. The width and height will be equal to the Display2D's default width and height (display2D.insideDisplay.width and display2D.insideDisplay.height respectively). To put the origin at the center of the display, you can set the x and y coordinates to display2D.insideDisplay.width/2, display2D.insideDisplay.height/2). The portrayal may be set to initially visible or not visible. Portrayals are drawn on-screen in the order that they are attached; thus the "top-most" portrayal will be the last one attached.

    • attach

      public void attach(FieldPortrayal2D portrayal, String name, Rectangle2D.Double bounds, boolean visible)
      Attaches a portrayal to the Display2D, along with the provided human-readable name for the portrayal. The portrayal's attached origin, width and height is given in the bounds rectangle. The portrayal may be set to initially visible or not visible. Portrayals are drawn on-screen in the order that they are attached; thus the "top-most" portrayal will be the last one attached.

    • attach

      public void attach(Inspector inspector, String name)
      A convenience function: creates a popup menu item of the given name which, when selected, will display the given inspector in the Console. Used rarely, typically for per-field Inspectors.

    • detachAll

      public ArrayList detachAll()
      Detatches all portrayals from the Display2D.

    • objectsHitBy

      public Bag[] objectsHitBy(Rectangle2D.Double rect)
      Returns LocationWrappers for all the objects which fall within the coordinate rectangle specified by rect. This rectangle is in the coordinate system of the (InnerDisplay2D) component inside the scroll view of the Display2D class. The return value is an array of Bags. For each FieldPortrayal attached to the Display2D, one Bag is returned holding all the LocationWrappers for objects falling within the rectangle which are associated with that FieldPortrayal's portrayed field. The order of the Bags in the array is the same as the order of the FieldPortrayals in the Display2D's portrayals list.

    • objectsHitBy

      public Bag[] objectsHitBy(Point2D point)
      Returns LocationWrappers for all the objects which overlap with the point specified by 'point'. This point is in the coordinate system of the (InnerDisplay2D) component inside the scroll view of the Display2D class. The return value is an array of Bags. For each FieldPortrayal attached to the Display2D, one Bag is returned holding all the LocationWrappers for objects overlapping with the point which are associated with that FieldPortrayal's portrayed field. The order of the Bags in the array is the same as the order of the FieldPortrayals in the Display2D's portrayals list.

    • getDrawInfo2D

      public DrawInfo2D getDrawInfo2D(FieldPortrayal2D portrayal, Point2D point)
      Constructs a DrawInfo2D for the given portrayal, or null if failed. O(num portrayals). Uses the given point as a clip.

    • getDrawInfo2D

      public DrawInfo2D getDrawInfo2D(FieldPortrayal2D portrayal, Rectangle2D clip)
      Constructs a DrawInfo2D for the given portrayal, or null if failed. O(num portrayals). Uses the given clip.

    • getSelectedWrappers

      public LocationWrapper[] getSelectedWrappers()
      Returns as LocationWrappers all the currently selected objects in the display. Do not modify these wrapper objects; they are used internally. These LocationWrappers may be invalid at any time in the near future if the user deselects objects.

    • performSelection

      public void performSelection(LocationWrapper wrapper)
      Selects the following object, deselecting other objects if so asked.
      Specified by:
      performSelection in interface Manipulating2D

    • clearSelections

      public void clearSelections()

    • performSelection

      public void performSelection(Point2D point)

    • performSelection

      public void performSelection(Rectangle2D.Double rect)

    • getSelectionMode

      public int getSelectionMode()
      Returns whether selecting a region will select all the objects within that region (the default), or instead a single object.

    • setSelectionMode

      public void setSelectionMode(int val)
      Sets whether selecting a region will select all the objects within that region (the default), or instead a single object.

    • performSelection

      public void performSelection(Bag locationWrappers)

    • createInspector

      public void createInspector(LocationWrapper wrapper, GUIState simulation)
      Inspects the following object.

    • createInspectors

      public void createInspectors(Point2D point, GUIState simulation)
      Determines the inspectors appropriate for the given point, and sends them on to the Controller.

    • createInspectors

      public void createInspectors(Bag locationWrappers, GUIState simulation)
      Determines the inspectors appropriate for the wrappers, and sends them on to the Controller.

    • createInspectors

      public void createInspectors(Rectangle2D.Double rect, GUIState simulation)
      Determines the inspectors appropriate for the given selection region (rect), and sends them on to the Controller.

    • createFrame

      public JFrame createFrame()
      Creates a frame holding the Display2D. This is the best method to create the frame, rather than making a frame and putting the Display2D in it. If you prefer the latter, then you need to handle two things. First, when the frame is disposed, you need to call quit() on the Display2D. Second, if you care about distribution to MacOS X Java 1.3.1, you need to call Utilities.doEnsuredRepaint(header) whenever the window is resized.

    • getFrame

      public Frame getFrame()
      Returns the frame holding this Component. If there is NO such frame, an error will be generated (probably a ClassCastException).

    • takeSnapshot

      public void takeSnapshot(File file, int type) throws IOException
      Throws:
      IOException

    • takeSnapshot

      public void takeSnapshot()

    • startMovie

      public void startMovie()
      Starts a Quicktime movie on the given Display2D. The size of the movie frame will be the size of the display at the time this method is called. This method ought to be called from the main event loop. Most of the default movie formats provided will result in a gigantic movie, which you can re-encode using something smarter (like the Animation or Sorenson codecs) to put to a reasonable size. On the Mac, Quicktime Pro will do this quite elegantly.

    • stopMovie

      public void stopMovie()
      Stops a Quicktime movie and cleans up, flushing the remaining frames out to disk. This method ought to be called from the main event loop.

    • requestUpdate

      public void requestUpdate()
      Asks Display2D to update itself next iteration regardless of the current redrawing/updating rule.

    • shouldUpdate

      public boolean shouldUpdate()
      Returns whether it's time to update.

    • setMouseChangesOffset

      public void setMouseChangesOffset(boolean val)
      Sets whether the user can change the offset by right-mouse-button-dragging, (or on OS X) Command-dragging or two-finger-click-dragging. By default FALSE.

    • getMouseChangesOffset

      public boolean getMouseChangesOffset()
      Sets whether the user can change the offset by right-mouse-button-dragging, (or on OS X) Command-dragging or two-finger-click-dragging. By default FALSE.

    • setMovingWrapper

      public void setMovingWrapper(LocationWrapper wrapper)
      Declares an object to be the one under control of MovablePortrayal2D.
      Specified by:
      setMovingWrapper in interface Manipulating2D

    • handleMouseEvent

      public boolean handleMouseEvent(MouseEvent event)

    • rebuildSkipFrame

      protected void rebuildSkipFrame()

    • rebuildRefreshPopup

      protected void rebuildRefreshPopup()

    • step

      public void step(SimState state)
      Steps the Display2D in the GUIState schedule. This results in a repaint() request generated.
      Specified by:
      step in interface Steppable