prefuse
Class Display

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              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

• ctrl D - Toggle debug info display
• ctrl H - Toggle high quality rendering
• ctrl E - Export display view to an image file

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.