prefuse
Class Display

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by prefuse.Display
All Implemented Interfaces:
java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

public class Display
extends javax.swing.JComponent

User interface component that provides an interactive view onto a visualization. The Display is responsible for drawing items to the screen and providing callbacks for user interface actions such as mouse and keyboard events. A Display must be associated with an Visualization from which it pulls the items to visualize.

To control which VisualItem instances are drawn, the Display also maintains an optional Predicate for filtering items. The drawing order of items is controlled by an ItemSorter instance, which calculates a score for each item. Items with higher scores are drawn later, and hence on top of lower scoring items.

The Control interface provides the user interface callbacks for supporting interaction. The prefuse.controls package contains a number of pre-built Control implementations for common interactions.

The Display class also supports arbitrary graphics transforms through the java.awt.geom.AffineTransform class. The setTransform method allows arbitrary transforms to be applied, while the pan and zoom methods provide convenience methods that appropriately update the current transform to achieve panning and zooming of the presentation space.

Additionally, each Display instance also supports use of a text editor to facilitate direct editing of text. See the various editText(prefuse.visual.VisualItem, String) methods.

Version:
1.0
Author:
jeffrey heer
See Also:
Visualization, Control, prefuse.controls, Serialized Form

Nested Class Summary
 class Display.InputEventCapturer
          Captures all mouse and key events on the display, detects relevant VisualItems, and informs ControlListeners.
 
Nested classes/interfaces inherited from class javax.swing.JComponent
javax.swing.JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class java.awt.Container
java.awt.Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
 
Field Summary
protected  double frameRate
           
protected  BackgroundPainter m_bgpainter
           
protected  CopyOnWriteArrayList m_bounders
           
protected  Clip m_bounds
           
protected  Clip m_clip
           
protected  CopyOnWriteArrayList m_controls
           
protected  javax.swing.JToolTip m_customToolTip
           
protected  boolean m_damageRedraw
           
protected  boolean m_highQuality
           
protected  java.awt.geom.AffineTransform m_itransform
           
protected  java.awt.image.BufferedImage m_offscreen
           
protected  CopyOnWriteArrayList m_painters
           
protected  AndPredicate m_predicate
           
protected  RenderingQueue m_queue
           
protected  java.awt.geom.Rectangle2D m_rclip
           
protected  Clip m_screen
           
protected  java.awt.geom.Point2D m_tmpPoint
           
protected  prefuse.Display.TransformActivity m_transact
           
protected  java.awt.geom.AffineTransform m_transform
           
protected  Visualization m_vis
           
protected  int m_visibleCount
           
protected  int nframes
           
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
Display()
          Creates a new Display instance.
Display(Visualization visualization)
          Creates a new Display associated with the given Visualization.
Display(Visualization visualization, Predicate predicate)
          Creates a new Display associated with the given Visualization that draws all VisualItems in the visualization that pass the given Predicate.
Display(Visualization visualization, java.lang.String predicate)
          Creates a new Display associated with the given Visualization that draws all VisualItems in the visualization that pass the given Predicate.
 
Method Summary
 void addControlListener(Control cl)
          Adds a ControlListener to receive all input events on VisualItems.
 void addItemBoundsListener(ItemBoundsListener ibl)
          Add an ItemBoundsListener to receive notifications when the bounds occupied by the VisualItems in this Display change.
 void addPaintListener(PaintListener pl)
          Add a PaintListener to this Display to receive notifications about paint events.
 void animatePan(double dx, double dy, long duration)
          Animate a pan along the specified distance in screen (pixel) co-ordinates using the provided duration.
 void animatePanAbs(double dx, double dy, long duration)
          Animate a pan along the specified distance in absolute (item-space) co-ordinates using the provided duration.
 void animatePanAndZoomTo(java.awt.geom.Point2D p, double scale, long duration)
          Animate a pan to the specified location in screen (pixel) co-ordinates and zoom to the given scale using the provided duration.
 void animatePanAndZoomToAbs(java.awt.geom.Point2D p, double scale, long duration)
          Animate a pan to the specified location in absolute (item-space) co-ordinates and zoom to the given scale using the provided duration.
 void animatePanTo(java.awt.geom.Point2D p, long duration)
          Animate a pan to the specified location in screen (pixel) co-ordinates using the provided duration.
 void animatePanToAbs(java.awt.geom.Point2D p, long duration)
          Animate a pan to the specified location in absolute (item-space) co-ordinates using the provided duration.
 void animateZoom(java.awt.geom.Point2D p, double scale, long duration)
          Animate a zoom centered on a given location in screen (pixel) co-ordinates by the given scale using the provided duration.
 void animateZoomAbs(java.awt.geom.Point2D p, double scale, long duration)
          Animate a zoom centered on a given location in absolute (item-space) co-ordinates by the given scale using the provided duration.
protected  void checkItemBoundsChanged(java.awt.geom.Rectangle2D prev)
          Check if the item bounds has changed, and if so, fire a notification.
 void clearDamage()
          Clears any reports of damaged regions, causing the Display to believe that the display contents are up-to-date.
protected  void clearRegion(java.awt.Graphics2D g, java.awt.geom.Rectangle2D r)
          Clears the specified region of the display in the display's offscreen buffer.
 javax.swing.JToolTip createToolTip()
          Returns the tooltip instance to use for this Display.
 void damageReport()
          Reports damage to the entire Display.
 void damageReport(java.awt.geom.Rectangle2D region)
          Reports damage to the Display within in the specified region.
 void editText(java.lang.String txt, java.awt.Rectangle r)
          Show a text editing widget containing the given text and spanning the specified bounding box.
 void editText(VisualItem item, java.lang.String attribute)
          Edit text for the given VisualItem and attribute.
 void editText(VisualItem item, java.lang.String attribute, java.awt.Rectangle r)
          Edit text for the given VisualItem and field.
 VisualItem findItem(java.awt.Point p)
          Returns the VisualItem located at the given point.
protected  void firePostPaint(java.awt.Graphics2D g)
          Fires a post-paint notification to PaintListeners.
protected  void firePrePaint(java.awt.Graphics2D g)
          Fires a pre-paint notification to PaintListeners.
 java.awt.geom.Point2D getAbsoluteCoordinate(java.awt.geom.Point2D screen, java.awt.geom.Point2D abs)
          Gets the absolute co-ordinate corresponding to the given screen co-ordinate.
 javax.swing.JToolTip getCustomToolTip()
          Get the custom tooltip used by this Display.
 double getDisplayX()
          Returns the x-coordinate of the top-left of the display, in absolute (item-space) co-ordinates.
 double getDisplayY()
          Returns the y-coordinate of the top-left of the display, in absolute (item-space) co-ordinates.
 double getFrameRate()
          Returns the running average frame rate for this Display.
 java.awt.geom.AffineTransform getInverseTransform()
          Returns a reference to the inverse of the AffineTransformation used by this display.
 java.awt.geom.Rectangle2D getItemBounds()
          Returns the bounds, in absolute (item-space) coordinates, of the total bounds occupied by all currently visible VisualItems.
 java.awt.geom.Rectangle2D getItemBounds(java.awt.geom.Rectangle2D b)
          Returns the bounds, in absolute (item-space) coordinates, of the total bounds occupied by all currently visible VisualItems.
 ItemSorter getItemSorter()
          Get the ItemSorter that determines the rendering order of the VisualItems.
protected  java.awt.image.BufferedImage getNewOffscreenBuffer(int width, int height)
          Creates a new buffered image to use as an offscreen buffer.
 java.awt.image.BufferedImage getOffscreenBuffer()
          Returns the offscreen buffer used for double buffering.
 Predicate getPredicate()
          Returns the filtering Predicate used to control what items are drawn by this display.
 double getScale()
          Returns the current scale (zoom) value.
 javax.swing.text.JTextComponent getTextEditor()
          Returns the TextComponent used for on-screen text editing.
 java.awt.geom.AffineTransform getTransform()
          Returns a reference to the AffineTransformation used by this Display.
 int getVisibleItemCount()
          Returns the number of visible items processed by this Display.
 Visualization getVisualization()
          Returns the Visualization backing this Display.
 void invalidate()
          Invalidates this component.
 boolean isDamageRedraw()
          Indicates if damage/redraw rendering is enabled.
 boolean isHighQuality()
          Indicates if the Display is using high quality (return value true) or regular quality (return value false) rendering.
 boolean isTranformInProgress()
          Indicates if a view transformation is currently underway.
protected  void paintBufferToScreen(java.awt.Graphics g)
          Paints the offscreen buffer to the provided graphics context.
 void paintComponent(java.awt.Graphics g)
           
 void paintDisplay(java.awt.Graphics2D g2D, java.awt.Dimension d)
          Renders the display within the given graphics context and size bounds.
 void pan(double dx, double dy)
          Pans the view provided by this display in screen coordinates.
 void panAbs(double dx, double dy)
          Pans the view provided by this display in absolute (i.e. item-space) coordinates.
 void panTo(java.awt.geom.Point2D p)
          Pans the display view to center on the provided point in screen (pixel) coordinates.
 void panToAbs(java.awt.geom.Point2D p)
          Pans the display view to center on the provided point in absolute (i.e. item-space) coordinates.
protected  void prepareGraphics(java.awt.Graphics2D g)
          Sets the transform of the provided Graphics context to be the transform of this Display and sets the desired rendering hints.
protected  void printComponent(java.awt.Graphics g)
          Paints the graph to the provided graphics context, for output to a printer.
protected  void registerDefaultCommands()
          Registers default keystroke commands on the Display.
 void removeControlListener(Control cl)
          Removes a registered ControlListener.
 void removeItemBoundsListener(ItemBoundsListener ibl)
          Remove an ItemBoundsListener to receive notifications when the bounds occupied by the VisualItems in this Display change.
 void removePaintListener(PaintListener pl)
          Remove a PaintListener from this Display.
 void renderImmediate(VisualItem item)
          Immediately render the given VisualItem to the screen.
 void repaintImmediate()
          Immediately repaints the contents of the offscreen buffer to the screen.
 void reset()
          Resets the display by clearing the offscreen buffer and flushing the internal rendering queue.
 void rotate(java.awt.geom.Point2D p, double theta)
          Rotates the view provided by this display by the given angle in radians, anchoring the rotation at the specified point in screen coordinates.
 void rotateAbs(java.awt.geom.Point2D p, double theta)
          Rotates the view provided by this display by the given angle in radians, anchoring the rotation at the specified point in absolute coordinates.
 boolean saveImage(java.io.OutputStream output, java.lang.String format, double scale)
          Saves a copy of this display as an image to the specified output stream.
 void setBackgroundImage(java.awt.Image image, boolean fixed, boolean tileImage)
          Set a background image for this display.
 void setBackgroundImage(java.lang.String location, boolean fixed, boolean tileImage)
          Set a background image for this display.
 void setBounds(int x, int y, int w, int h)
           
 void setCustomToolTip(javax.swing.JToolTip tooltip)
          Set a custom tooltip to use for this Display.
 void setDamageRedraw(boolean b)
          Sets if damage/redraw rendering is enabled.
 void setFont(java.awt.Font f)
          Sets the font used by this Display.
 void setHighQuality(boolean on)
          Determines if the Display uses a higher quality rendering, using anti-aliasing.
 void setItemSorter(ItemSorter cmp)
          Set the ItemSorter that determines the rendering order of the VisualItems.
 void setPredicate(Predicate p)
          Sets the filtering Predicate used to control what items are drawn by this Display.
 void setPredicate(java.lang.String expr)
          Sets the filtering Predicate used to control what items are drawn by this Display.
protected  void setRenderingHints(java.awt.Graphics2D g)
          Sets the rendering hints that should be used while drawing the visualization to the screen.
 void setSize(java.awt.Dimension d)
          Set the size of the Display.
 void setSize(int width, int height)
          Set the size of the Display.
 void setTextEditor(javax.swing.text.JTextComponent tc)
          Sets the TextComponent used for on-screen text editing.
 void setTransform(java.awt.geom.AffineTransform transform)
          Set the 2D AffineTransform (e.g., scale, shear, pan, rotate) used by this display before rendering visual items.
 void setVisualization(Visualization vis)
          Set the Visualiztion associated with this Display.
 void stopEditing()
          Stops text editing on the display, hiding the text editing widget.
 void update(java.awt.Graphics g)
           
 void zoom(java.awt.geom.Point2D p, double scale)
          Zooms the view provided by this display by the given scale, anchoring the zoom at the specified point in screen coordinates.
 void zoomAbs(java.awt.geom.Point2D p, double scale)
          Zooms the view provided by this display by the given scale, anchoring the zoom at the specified point in absolute coordinates.
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, updateUI
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, show, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

m_vis

protected Visualization m_vis

m_predicate

protected AndPredicate m_predicate

m_controls

protected CopyOnWriteArrayList m_controls

m_painters

protected CopyOnWriteArrayList m_painters

m_bounders

protected CopyOnWriteArrayList m_bounders

m_offscreen

protected java.awt.image.BufferedImage m_offscreen

m_clip

protected Clip m_clip

m_screen

protected Clip m_screen

m_bounds

protected Clip m_bounds

m_rclip

protected java.awt.geom.Rectangle2D m_rclip

m_damageRedraw

protected boolean m_damageRedraw

m_highQuality

protected boolean m_highQuality

m_bgpainter

protected BackgroundPainter m_bgpainter

m_queue

protected RenderingQueue m_queue

m_visibleCount

protected int m_visibleCount

m_transform

protected java.awt.geom.AffineTransform m_transform

m_itransform

protected java.awt.geom.AffineTransform m_itransform

m_transact

protected prefuse.Display.TransformActivity m_transact

m_tmpPoint

protected java.awt.geom.Point2D m_tmpPoint

frameRate

protected double frameRate

nframes

protected int nframes

m_customToolTip

protected javax.swing.JToolTip m_customToolTip
Constructor Detail

Display

public Display()
Creates a new Display instance. You will need to associate this Display with a Visualization for it to display anything.


Display

public Display(Visualization visualization)
Creates a new Display associated with the given Visualization. By default, all VisualItem instances in the Visualization will be drawn by the Display.

Parameters:
visualization - the Visualization backing this Display

Display

public Display(Visualization visualization,
               java.lang.String predicate)
Creates a new Display associated with the given Visualization that draws all VisualItems in the visualization that pass the given Predicate. The predicate string will be parsed by the ExpressionParser to get a Predicate instance.

Parameters:
visualization - the Visualization backing this Display
predicate - a predicate expression in the prefuse expression language. This expression will be parsed; if the parsing fails or does not result in a Predicate instance, an exception will result.

Display

public Display(Visualization visualization,
               Predicate predicate)
Creates a new Display associated with the given Visualization that draws all VisualItems in the visualization that pass the given Predicate.

Parameters:
visualization - the Visualization backing this Display
predicate - the filtering Predicate
Method Detail

reset

public void reset()
Resets the display by clearing the offscreen buffer and flushing the internal rendering queue. This method can help reclaim memory when a Display is not visible.


registerDefaultCommands

protected void registerDefaultCommands()
Registers default keystroke commands on the Display. The default commands are Subclasses can override this method to prevent these commands from being set. Additional commands can be registered using the registerKeyboardAction method.


setSize

public void setSize(int width,
                    int height)
Set the size of the Display.

Overrides:
setSize in class java.awt.Component
Parameters:
width - the width of the Display in pixels
height - the height of the Display in pixels
See Also:
Component.setSize(int, int)

setSize

public void setSize(java.awt.Dimension d)
Set the size of the Display.

Overrides:
setSize in class java.awt.Component
Parameters:
d - the dimensions of the Display in pixels
See Also:
Component.setSize(java.awt.Dimension)

invalidate

public void invalidate()
Invalidates this component. Overridden to ensure that an internal damage report is generated.

Overrides:
invalidate in class java.awt.Container
See Also:
Component.invalidate()

setBounds

public void setBounds(int x,
                      int y,
                      int w,
                      int h)
Overrides:
setBounds in class java.awt.Component
See Also:
Component.setBounds(int, int, int, int)

setFont

public void setFont(java.awt.Font f)
Sets the font used by this Display. This determines the font used by this Display's text editor and in any debugging text.

Overrides:
setFont in class javax.swing.JComponent
Parameters:
f - the Font to use

getFrameRate

public double getFrameRate()
Returns the running average frame rate for this Display.

Returns:
the frame rate

setHighQuality

public void setHighQuality(boolean on)
Determines if the Display uses a higher quality rendering, using anti-aliasing. This causes drawing to be much slower, however, and so is disabled by default.

Parameters:
on - true to enable anti-aliased rendering, false to disable it

isHighQuality

public boolean isHighQuality()
Indicates if the Display is using high quality (return value true) or regular quality (return value false) rendering.

Returns:
true if high quality rendering is enabled, false otherwise

getVisualization

public Visualization getVisualization()
Returns the Visualization backing this Display.

Returns:
this Display's Visualization

setVisualization

public void setVisualization(Visualization vis)
Set the Visualiztion associated with this Display. This Display will render the items contained in the provided visualization. If this Display is already associated with a different Visualization, the Display unregisters itself with the previous one.

Parameters:
vis - the backing Visualization to use.

getPredicate

public Predicate getPredicate()
Returns the filtering Predicate used to control what items are drawn by this display.

Returns:
the filtering Predicate

setPredicate

public void setPredicate(java.lang.String expr)
Sets the filtering Predicate used to control what items are drawn by this Display.

Parameters:
expr - the filtering predicate to use. The predicate string will be parsed by the ExpressionParser. If the parse fails or does not result in a Predicate instance, an exception will be thrown.

setPredicate

public void setPredicate(Predicate p)
Sets the filtering Predicate used to control what items are drawn by this Display.

Parameters:
p - the filtering Predicate to use

getVisibleItemCount

public int getVisibleItemCount()
Returns the number of visible items processed by this Display. This includes items not currently visible on screen due to the current panning or zooming state.

Returns:
the count of visible items

getItemSorter

public ItemSorter getItemSorter()
Get the ItemSorter that determines the rendering order of the VisualItems. Items are drawn in ascending order of the scores provided by the ItemSorter.

Returns:
this Display's ItemSorter

setItemSorter

public void setItemSorter(ItemSorter cmp)
Set the ItemSorter that determines the rendering order of the VisualItems. Items are drawn in ascending order of the scores provided by the ItemSorter.

Parameters:
cmp - the ItemSorter to use

setBackgroundImage

public void setBackgroundImage(java.awt.Image image,
                               boolean fixed,
                               boolean tileImage)
Set a background image for this display.

Parameters:
image - the background Image. If a null value is provided, than no background image will be shown.
fixed - true if the background image should stay in a fixed position, invariant to panning, zooming, or rotation; false if the image should be subject to view transforms
tileImage - true to tile the image across the visible background, false to only include the image once

setBackgroundImage

public void setBackgroundImage(java.lang.String location,
                               boolean fixed,
                               boolean tileImage)
Set a background image for this display.

Parameters:
location - a location String of where to retrieve the image file from. Uses IOLib.urlFromString(String) to resolve the String. If a null value is provided, than no background image will be shown.
fixed - true if the background image should stay in a fixed position, invariant to panning, zooming, or rotation; false if the image should be subject to view transforms
tileImage - true to tile the image across the visible background, false to only include the image once

createToolTip

public javax.swing.JToolTip createToolTip()
Returns the tooltip instance to use for this Display. By default, uses the normal Swing tooltips, returning the result of this same method invoked on the JComponent super-class. If a custom tooltip has been set, that is returned instead.

Overrides:
createToolTip in class javax.swing.JComponent
See Also:
setCustomToolTip(JToolTip), JComponent.createToolTip()

setCustomToolTip

public void setCustomToolTip(javax.swing.JToolTip tooltip)
Set a custom tooltip to use for this Display. To trigger tooltip display, you must still use the setToolTipText method as usual. The actual text will no longer have any effect, other than that a null text value will result in no tooltip display while a non-null text value will result in a tooltip being shown. Clients are responsible for setting the tool tip text to enable/disable tooltips as well as updating the content of their own custom tooltip instance.

Parameters:
tooltip - the tooltip component to use
See Also:
JCustomTooltip

getCustomToolTip

public javax.swing.JToolTip getCustomToolTip()
Get the custom tooltip used by this Display. Returns null if normal tooltips are being used.

Returns:
the custom tooltip used by this Display, or null if none

isDamageRedraw

public boolean isDamageRedraw()
Indicates if damage/redraw rendering is enabled. If enabled, the display will only redraw within the bounding box of all areas that have changed since the last rendering operation. For small changes, such as a single item being dragged, this can result in a significant performance increase. By default, the damage/redraw optimization is enabled. It can be disabled, however, if rendering artifacts are appearing in your visualization. Be careful though, as this may not be the best solution. Rendering artifacts may result because the item bounds returned by VisualItem.getBounds() are not accurate and the item's Renderer is drawing outside of the reported bounds. In this case, there is usually a bug in the Renderer. One reported problem arises from Java itself, however, which inaccurately redraws images outside of their reported bounds. If you have a visulization with a number of images and are seeing rendering artifacts, try disabling damage/redraw.

Returns:
true if damage/redraw optimizations are enabled, false otherwise (in which case the entire Display is redrawn upon a repaint)

setDamageRedraw

public void setDamageRedraw(boolean b)
Sets if damage/redraw rendering is enabled. If enabled, the display will only redraw within the bounding box of all areas that have changed since the last rendering operation. For small changes, such as a single item being dragged, this can result in a significant performance increase. By default, the damage/redraw optimization is enabled. It can be disabled, however, if rendering artifacts are appearing in your visualization. Be careful though, as this may not be the best solution. Rendering artifacts may result because the item bounds returned by VisualItem.getBounds() are not accurate and the item's Renderer is drawing outside of the reported bounds. In this case, there is usually a bug in the Renderer. One reported problem arises from Java itself, however, which inaccurately redraws images outside of their reported bounds. If you have a visulization with a number of images and are seeing rendering artifacts, try disabling damage/redraw.

Parameters:
b - true to enable damage/redraw optimizations, false otherwise (in which case the entire Display will be redrawn upon a repaint)

damageReport

public void damageReport(java.awt.geom.Rectangle2D region)
Reports damage to the Display within in the specified region.

Parameters:
region - the damaged region, in absolute coordinates

damageReport

public void damageReport()
Reports damage to the entire Display.


clearDamage

public void clearDamage()
Clears any reports of damaged regions, causing the Display to believe that the display contents are up-to-date. If used incorrectly this can cause inaccurate rendering. Call this method only if you know what you are doing.


getItemBounds

public java.awt.geom.Rectangle2D getItemBounds()
Returns the bounds, in absolute (item-space) coordinates, of the total bounds occupied by all currently visible VisualItems. This method allocates a new Rectangle2D instance for the result.

Returns:
the bounding box of all visibile VisualItems
See Also:
getItemBounds(Rectangle2D)

getItemBounds

public java.awt.geom.Rectangle2D getItemBounds(java.awt.geom.Rectangle2D b)
Returns the bounds, in absolute (item-space) coordinates, of the total bounds occupied by all currently visible VisualItems.

Parameters:
b - the Rectangle2D to use to store the return value
Returns:
the bounding box of all visibile VisualItems

getOffscreenBuffer

public java.awt.image.BufferedImage getOffscreenBuffer()
Returns the offscreen buffer used for double buffering.

Returns:
the offscreen buffer

getNewOffscreenBuffer

protected java.awt.image.BufferedImage getNewOffscreenBuffer(int width,
                                                             int height)
Creates a new buffered image to use as an offscreen buffer.


saveImage

public boolean saveImage(java.io.OutputStream output,
                         java.lang.String format,
                         double scale)
Saves a copy of this display as an image to the specified output stream.

Parameters:
output - the output stream to write to.
format - the image format (e.g., "JPG", "PNG"). The number and kind of available formats varies by platform. See ImageIO and related classes for more.
scale - how much to scale the image by. For example, a value of 2.0 will result in an image with twice the pixel width and height of this Display.
Returns:
true if image was successfully saved, false if an error occurred.

update

public void update(java.awt.Graphics g)
Overrides:
update in class javax.swing.JComponent
See Also:
Component.update(java.awt.Graphics)

paintBufferToScreen

protected void paintBufferToScreen(java.awt.Graphics g)
Paints the offscreen buffer to the provided graphics context.

Parameters:
g - the Graphics context to paint to

repaintImmediate

public void repaintImmediate()
Immediately repaints the contents of the offscreen buffer to the screen. This bypasses the usual rendering loop.


prepareGraphics

protected void prepareGraphics(java.awt.Graphics2D g)
Sets the transform of the provided Graphics context to be the transform of this Display and sets the desired rendering hints.

Parameters:
g - the Graphics context to prepare.

setRenderingHints

protected void setRenderingHints(java.awt.Graphics2D g)
Sets the rendering hints that should be used while drawing the visualization to the screen. Subclasses can override this method to set hints as desired. Such subclasses should consider honoring the high quality flag in one form or another.

Parameters:
g - the Graphics context on which to set the rendering hints

paintComponent

public void paintComponent(java.awt.Graphics g)
Overrides:
paintComponent in class javax.swing.JComponent
See Also:
JComponent.paintComponent(java.awt.Graphics)

paintDisplay

public void paintDisplay(java.awt.Graphics2D g2D,
                         java.awt.Dimension d)
Renders the display within the given graphics context and size bounds.

Parameters:
g2D - the Graphics2D context to use for rendering
d - the rendering width and height of the Display

renderImmediate

public void renderImmediate(VisualItem item)
Immediately render the given VisualItem to the screen. This method bypasses the Display's offscreen buffer.

Parameters:
item - the VisualItem to render immediately

printComponent

protected void printComponent(java.awt.Graphics g)
Paints the graph to the provided graphics context, for output to a printer. This method does not double buffer the painting, in order to provide the maximum print quality. This method may not be working correctly, and will be repaired at a later date.

Overrides:
printComponent in class javax.swing.JComponent
Parameters:
g - the printer graphics context.

clearRegion

protected void clearRegion(java.awt.Graphics2D g,
                           java.awt.geom.Rectangle2D r)
Clears the specified region of the display in the display's offscreen buffer.


setTransform

public void setTransform(java.awt.geom.AffineTransform transform)
                  throws java.awt.geom.NoninvertibleTransformException
Set the 2D AffineTransform (e.g., scale, shear, pan, rotate) used by this display before rendering visual items. The provided transform must be invertible, otherwise an expection will be thrown. For simple panning and zooming transforms, you can instead use the provided pan() and zoom() methods.

Throws:
java.awt.geom.NoninvertibleTransformException

getTransform

public java.awt.geom.AffineTransform getTransform()
Returns a reference to the AffineTransformation used by this Display. Changes made to this reference WILL corrupt the state of this display. Use setTransform() to safely update the transform state.

Returns:
the AffineTransform

getInverseTransform

public java.awt.geom.AffineTransform getInverseTransform()
Returns a reference to the inverse of the AffineTransformation used by this display. Direct changes made to this reference WILL corrupt the state of this display.

Returns:
the inverse AffineTransform

getAbsoluteCoordinate

public java.awt.geom.Point2D getAbsoluteCoordinate(java.awt.geom.Point2D screen,
                                                   java.awt.geom.Point2D abs)
Gets the absolute co-ordinate corresponding to the given screen co-ordinate.

Parameters:
screen - the screen co-ordinate to transform
abs - a reference to put the result in. If this is the same object as the screen co-ordinate, it will be overridden safely. If this value is null, a new Point2D instance will be created and returned.
Returns:
the point in absolute co-ordinates

getScale

public double getScale()
Returns the current scale (zoom) value.

Returns:
the current scale. This is the scaling factor along the x-dimension, so be careful when using this value in rare non-uniform scaling cases.

getDisplayX

public double getDisplayX()
Returns the x-coordinate of the top-left of the display, in absolute (item-space) co-ordinates.

Returns:
the x co-ord of the top-left corner, in absolute coordinates

getDisplayY

public double getDisplayY()
Returns the y-coordinate of the top-left of the display, in absolute (item-space) co-ordinates.

Returns:
the y co-ord of the top-left corner, in absolute coordinates

pan

public void pan(double dx,
                double dy)
Pans the view provided by this display in screen coordinates.

Parameters:
dx - the amount to pan along the x-dimension, in pixel units
dy - the amount to pan along the y-dimension, in pixel units

panAbs

public void panAbs(double dx,
                   double dy)
Pans the view provided by this display in absolute (i.e. item-space) coordinates.

Parameters:
dx - the amount to pan along the x-dimension, in absolute co-ords
dy - the amount to pan along the y-dimension, in absolute co-ords

panTo

public void panTo(java.awt.geom.Point2D p)
Pans the display view to center on the provided point in screen (pixel) coordinates.

Parameters:
p - the point to center on, in screen co-ords

panToAbs

public void panToAbs(java.awt.geom.Point2D p)
Pans the display view to center on the provided point in absolute (i.e. item-space) coordinates.

Parameters:
p - the point to center on, in absolute co-ords

zoom

public void zoom(java.awt.geom.Point2D p,
                 double scale)
Zooms the view provided by this display by the given scale, anchoring the zoom at the specified point in screen coordinates.

Parameters:
p - the anchor point for the zoom, in screen coordinates
scale - the amount to zoom by

zoomAbs

public void zoomAbs(java.awt.geom.Point2D p,
                    double scale)
Zooms the view provided by this display by the given scale, anchoring the zoom at the specified point in absolute coordinates.

Parameters:
p - the anchor point for the zoom, in absolute (i.e. item-space) co-ordinates
scale - the amount to zoom by

rotate

public void rotate(java.awt.geom.Point2D p,
                   double theta)
Rotates the view provided by this display by the given angle in radians, anchoring the rotation at the specified point in screen coordinates.

Parameters:
p - the anchor point for the rotation, in screen coordinates
theta - the angle to rotate by, in radians

rotateAbs

public void rotateAbs(java.awt.geom.Point2D p,
                      double theta)
Rotates the view provided by this display by the given angle in radians, anchoring the rotation at the specified point in absolute coordinates.

Parameters:
p - the anchor point for the rotation, in absolute (i.e. item-space) co-ordinates
theta - the angle to rotation by, in radians

animatePan

public void animatePan(double dx,
                       double dy,
                       long duration)
Animate a pan along the specified distance in screen (pixel) co-ordinates using the provided duration.

Parameters:
dx - the amount to pan along the x-dimension, in pixel units
dy - the amount to pan along the y-dimension, in pixel units
duration - the duration of the animation, in milliseconds

animatePanAbs

public void animatePanAbs(double dx,
                          double dy,
                          long duration)
Animate a pan along the specified distance in absolute (item-space) co-ordinates using the provided duration.

Parameters:
dx - the amount to pan along the x-dimension, in absolute co-ords
dy - the amount to pan along the y-dimension, in absolute co-ords
duration - the duration of the animation, in milliseconds

animatePanTo

public void animatePanTo(java.awt.geom.Point2D p,
                         long duration)
Animate a pan to the specified location in screen (pixel) co-ordinates using the provided duration.

Parameters:
p - the point to pan to in screen (pixel) units
duration - the duration of the animation, in milliseconds

animatePanToAbs

public void animatePanToAbs(java.awt.geom.Point2D p,
                            long duration)
Animate a pan to the specified location in absolute (item-space) co-ordinates using the provided duration.

Parameters:
p - the point to pan to in absolute (item-space) units
duration - the duration of the animation, in milliseconds

animateZoom

public void animateZoom(java.awt.geom.Point2D p,
                        double scale,
                        long duration)
Animate a zoom centered on a given location in screen (pixel) co-ordinates by the given scale using the provided duration.

Parameters:
p - the point to center on in screen (pixel) units
scale - the scale factor to zoom by
duration - the duration of the animation, in milliseconds

animateZoomAbs

public void animateZoomAbs(java.awt.geom.Point2D p,
                           double scale,
                           long duration)
Animate a zoom centered on a given location in absolute (item-space) co-ordinates by the given scale using the provided duration.

Parameters:
p - the point to center on in absolute (item-space) units
scale - the scale factor to zoom by
duration - the duration of the animation, in milliseconds

animatePanAndZoomTo

public void animatePanAndZoomTo(java.awt.geom.Point2D p,
                                double scale,
                                long duration)
Animate a pan to the specified location in screen (pixel) co-ordinates and zoom to the given scale using the provided duration.

Parameters:
p - the point to center on in screen (pixel) units
scale - the scale factor to zoom by
duration - the duration of the animation, in milliseconds

animatePanAndZoomToAbs

public void animatePanAndZoomToAbs(java.awt.geom.Point2D p,
                                   double scale,
                                   long duration)
Animate a pan to the specified location in absolute (item-space) co-ordinates and zoom to the given scale using the provided duration.

Parameters:
p - the point to center on in absolute (item-space) units
scale - the scale factor to zoom by
duration - the duration of the animation, in milliseconds

isTranformInProgress

public boolean isTranformInProgress()
Indicates if a view transformation is currently underway.

Returns:
true if a transform is in progress, false otherwise

addPaintListener

public void addPaintListener(PaintListener pl)
Add a PaintListener to this Display to receive notifications about paint events.

Parameters:
pl - the PaintListener to add

removePaintListener

public void removePaintListener(PaintListener pl)
Remove a PaintListener from this Display.

Parameters:
pl - the PaintListener to remove

firePrePaint

protected void firePrePaint(java.awt.Graphics2D g)
Fires a pre-paint notification to PaintListeners.

Parameters:
g - the current graphics context

firePostPaint

protected void firePostPaint(java.awt.Graphics2D g)
Fires a post-paint notification to PaintListeners.

Parameters:
g - the current graphics context

addItemBoundsListener

public void addItemBoundsListener(ItemBoundsListener ibl)
Add an ItemBoundsListener to receive notifications when the bounds occupied by the VisualItems in this Display change.

Parameters:
ibl - the ItemBoundsListener to add

removeItemBoundsListener

public void removeItemBoundsListener(ItemBoundsListener ibl)
Remove an ItemBoundsListener to receive notifications when the bounds occupied by the VisualItems in this Display change.

Parameters:
ibl - the ItemBoundsListener to remove

checkItemBoundsChanged

protected void checkItemBoundsChanged(java.awt.geom.Rectangle2D prev)
Check if the item bounds has changed, and if so, fire a notification.

Parameters:
prev - the previous item bounds of the Display

addControlListener

public void addControlListener(Control cl)
Adds a ControlListener to receive all input events on VisualItems.

Parameters:
cl - the listener to add.

removeControlListener

public void removeControlListener(Control cl)
Removes a registered ControlListener.

Parameters:
cl - the listener to remove.

findItem

public VisualItem findItem(java.awt.Point p)
Returns the VisualItem located at the given point.

Parameters:
p - the Point at which to look
Returns:
the VisualItem located at the given point, if any

getTextEditor

public javax.swing.text.JTextComponent getTextEditor()
Returns the TextComponent used for on-screen text editing.

Returns:
the TextComponent used for text editing

setTextEditor

public void setTextEditor(javax.swing.text.JTextComponent tc)
Sets the TextComponent used for on-screen text editing.

Parameters:
tc - the TextComponent to use for text editing

editText

public void editText(VisualItem item,
                     java.lang.String attribute)
Edit text for the given VisualItem and attribute. Presents a text editing widget spaning the item's bounding box. Use stopEditing() to hide the text widget. When stopEditing() is called, the data field will automatically be updated with the VisualItem.

Parameters:
item - the VisualItem to edit
attribute - the attribute to edit

editText

public void editText(VisualItem item,
                     java.lang.String attribute,
                     java.awt.Rectangle r)
Edit text for the given VisualItem and field. Presents a text editing widget spaning the given bounding box. Use stopEditing() to hide the text widget. When stopEditing() is called, the field will automatically be updated with the VisualItem.

Parameters:
item - the VisualItem to edit
attribute - the attribute to edit
r - Rectangle representing the desired bounding box of the text editing widget

editText

public void editText(java.lang.String txt,
                     java.awt.Rectangle r)
Show a text editing widget containing the given text and spanning the specified bounding box. Use stopEditing() to hide the text widget. Use the method calls getTextEditor().getText() to get the resulting edited text.

Parameters:
txt - the text string to display in the text widget
r - Rectangle representing the desired bounding box of the text editing widget

stopEditing

public void stopEditing()
Stops text editing on the display, hiding the text editing widget. If the text editor was associated with a specific VisualItem (ie one of the editText() methods which include a VisualItem as an argument was called), the item is updated with the edited text.



Copyright 2007 Regents of the University of California