edu.umd.cs.jazz.util
Class ZCanvas

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--javax.swing.JComponent
                    |
                    +--edu.umd.cs.jazz.util.ZCanvas

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

public class ZCanvas

extends javax.swing.JComponent

implements java.io.Serializable

ZCanvas is a simple Swing component that can be used to render onto for Jazz. It extends JComponent, and overrides the appropriate methods so that whenever Java requests that this widget gets redrawn, the requests are forwarded on to Jazz to render appropriately. It also defines a very simple Jazz scenegraph consisting of a root, a camera, and one node. It supports capturing the current camera view onto an Image (i.e., a screengrab). It also supports the use of Swing components within Jazz by forwarding mouse, repaint, and revalidate events.

A ZCanvas also supports scrollBars when it is added to a JScrollPane. Note that manipulating the scrollbars changes the camera view, not the canvas view. The scrollbars adjust to accomodate the objects in the camera view, incorporating the magnification. There can be weird effects when the camera is panned manually, as the scrollBars are adjusted to include all the objects in the scenegraph, plus the current camera view. Panning the camera in space that includes no objects will cause the scrollBars to change size, as they adapt to the changing space that is the union of the objects and the camera.

ZCanvas defines basic event handlers for panning and zooming with the keyboard and mouse which can be enabled and disabled with setNavEventHandlersActive(boolean).

Warning: Serialized and ZSerialized objects of this class will not be compatible with future Jazz releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Jazz. A future release of Jazz will provide support for long term persistence.

Author:

Benjamin B. Bederson, Lance E. Good

See Also:

Serialized Form

Inner Class Summary

class

ZCanvas.ZBasicRepaintManager This is an internal class used by Jazz to support Swing components in Jazz.

Inner classes inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Inner classes inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Inner classes inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent

Field Summary

protected boolean	enableNodeEvents True if ZMouseEvents are being sent to nodes on the canvas.
protected javax.swing.JScrollBar	hbar The horizontal and vertical scrollBars.
protected boolean	hbarVisible True if horizontal scrollBar is currently visible.
protected ZEventHandler	keyEventHandler The event handler that supports key events.
protected edu.umd.cs.jazz.util.ZCanvas.ZNodeEventHandler	nodeListener Mouse Listener for ZNodes that have visual components.
protected ZPanEventHandler	panEventHandler The event handler that supports panning.
protected javax.swing.JScrollPane	scrollParent A scrollPane may be an ancestor of this ZCanvas.
protected ZSwingEventHandler	swingEventHandler The event handler that supports events for Swing Visual Components.
protected javax.swing.JScrollBar	vbar The horizontal and vertical scrollBars.
protected boolean	vbarVisible True if vertical scrollBar is currently visible.
protected ZoomEventHandler	zoomEventHandler The event handler that supports zooming.

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

ZCanvas()
The default constructor for a ZCanvas.

ZCanvas(ZRoot aRoot, ZLayerGroup layer)
A constructor for a ZCanvas that uses an existing scenegraph.

Method Summary

ZCamera	getCamera() Return the camera associated with the primary surface.
ZNode	getCameraNode() Return the camera's node associated with the primary surface.
ZDrawingSurface	getDrawingSurface() Return the surface.
boolean	getEnableNodeEvents() Determine if Jazz node event handlers should be invoked.
ZLayerGroup	getLayer() Return the "layer".
ZEventHandler	getPanEventHandler() Return the pan event handler.
ZRoot	getRoot() Return the root of the scenegraph.
java.awt.Image	getScreenImage(int maxDim) Generate a copy of the view in the current camera scaled so that the aspect ratio of the screen is maintained, and the larger dimension is scaled to match the specified parameter.
java.awt.Image	getScreenImage(int w, int h) Generate a copy of the current camera scaled to the specified dimensions.
ZSwingEventHandler	getSwingEventHandler() Returns the event handler that supports events for Swing Visual Components.
javax.swing.JComponent	getSwingWrapper() Returns the component to which Swing components are added to function properly in Jazz.
ZEventHandler	getZoomEventHandler() Return the zoom event handler.
protected void	init() Internal method to support initialization of a ZCanvas.
protected void	initScrollBars() Add horizontal and vertical scrollBars to this ZCanvas.
boolean	isFocusTraversable() Identifies whether or not this component can receive the focus.
void	paintComponent(java.awt.Graphics g) This renders the Jazz scene attached to this component by passing on the Swing paint request to the underlying Jazz surface.
void	resetCursor() Sets the current cursor to the ZCanvas's cursor.
void	setAutoScrollingEnabled(boolean autoScroll) Determines whether the ZCanvas automatically handles scrolling when placed in a JScrollPane
void	setBackground(java.awt.Color background) Sets the background color of this component.
void	setBounds(int x, int y, int w, int h) This captures changes in the component's bounds so the underlying Jazz camera can be updated to mirror bounds change.
void	setCamera(ZCamera aCamera) Sets the camera.
void	setCamera(ZCamera aCamera, ZNode aCameraNode) Sets the camera.
void	setCursor(java.awt.Cursor c) Sets the cursor for this ZCanvas
void	setCursor(java.awt.Cursor c, boolean realSet) Sets the cursor for this ZCanvas.
void	setDrawingSurface(ZDrawingSurface aSurface) Sets the surface.
void	setEnableNodeEvents(boolean enable) Specify if Jazz node event handlers should be invoked.
void	setLayer(ZLayerGroup aLayer) Sets the layer of the scenegraph.
void	setNavEventHandlersActive(boolean active) Control whether event handlers are active or not for this ZCanvas.
void	setRoot(ZRoot aRoot) Sets the root of the scenegraph.
void	setSwingEventHandlersActive(boolean active) Control whether swing event handlers are active or not for this ZCanvas.
void	setToolTipText(java.lang.String s) Sets the ToolTip Text for this ZCanvas LEG: HACK - this includes a workaround to update the ToolTip as as soon as it changes by forwarding fake mouse events to the tooltip manager

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getUIClassID, getVerifyInputWhenFocusTarget, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, hide, isDoubleBuffered, isFocusCycleRoot, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processFocusEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setLayout, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, resize, resize, setBounds, setComponentOrientation, setDropTarget, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

nodeListener

protected edu.umd.cs.jazz.util.ZCanvas.ZNodeEventHandler nodeListener

Mouse Listener for ZNodes that have visual components.

swingEventHandler

protected ZSwingEventHandler swingEventHandler

The event handler that supports events for Swing Visual Components.

panEventHandler

protected ZPanEventHandler panEventHandler

The event handler that supports panning.

zoomEventHandler

protected ZoomEventHandler zoomEventHandler

The event handler that supports zooming.

keyEventHandler

protected ZEventHandler keyEventHandler

The event handler that supports key events.

hbar

protected javax.swing.JScrollBar hbar

The horizontal and vertical scrollBars.

vbar

protected javax.swing.JScrollBar vbar

The horizontal and vertical scrollBars.

scrollParent

protected javax.swing.JScrollPane scrollParent

A scrollPane may be an ancestor of this ZCanvas.

vbarVisible

protected boolean vbarVisible

True if vertical scrollBar is currently visible.

hbarVisible

protected boolean hbarVisible

True if horizontal scrollBar is currently visible.

enableNodeEvents

protected boolean enableNodeEvents

True if ZMouseEvents are being sent to nodes on the canvas.

Constructor Detail

ZCanvas

public ZCanvas()

The default constructor for a ZCanvas. This creates a simple scenegraph with a root, camera, surface, and layer. These 4 scenegraph elements are accessible to the application through get methods. Also adds the necessary structure to facilitate the focus, repaint, and event handling for Swing components within Jazz

See Also:

getRoot(), getDrawingSurface(), getCamera(), getLayer()

ZCanvas

public ZCanvas(ZRoot aRoot,
               ZLayerGroup layer)

A constructor for a ZCanvas that uses an existing scenegraph. This creates a new camera and surface. The camera is inserted into the scenegraph under the root, and the specified layer is added to the camera's paint start point list. The scenegraph elements are accessible to the application through get methods. Also adds the necessary structure to facilitate the focus, repaint, and event handling for Swing components within Jazz

Parameters:

aRoot - The existing root of the scenegraph this component is attached to

layer - The existing layer node of the scenegraph that this component's camera looks onto

See Also:

getRoot(), getDrawingSurface(), getCamera(), getLayer()

Method Detail

init

protected void init()

Internal method to support initialization of a ZCanvas.

initScrollBars

protected void initScrollBars()

Add horizontal and vertical scrollBars to this ZCanvas. A listener is added to the camera so the scrollBars can be updated when the camera moves. Likewise, listeners are added to the scrollBars, so the camera can be updated.

setAutoScrollingEnabled

public void setAutoScrollingEnabled(boolean autoScroll)

Determines whether the ZCanvas automatically handles scrolling when placed in a JScrollPane

Parameters:

autoScroll - Will this ZCanvas automatically handle scrolling?

paintComponent

public void paintComponent(java.awt.Graphics g)

This renders the Jazz scene attached to this component by passing on the Swing paint request to the underlying Jazz surface.

Overrides:

paintComponent in class javax.swing.JComponent

Parameters:

g - The graphics to be painted onto

setBounds

public void setBounds(int x,
                      int y,
                      int w,
                      int h)

This captures changes in the component's bounds so the underlying Jazz camera can be updated to mirror bounds change.

Overrides:

setBounds in class java.awt.Component

Parameters:

x - The X-coord of the top-left corner of the component

y - The Y-coord of the top-left corner of the component

width - The width of the component

height - The Height of the component

setBackground

public void setBackground(java.awt.Color background)

Sets the background color of this component. Actually - this is implemented by changing the fill color of the camera associated with this component since the camera controls the rendering onto this component.

Overrides:

setBackground in class javax.swing.JComponent

Parameters:

background - The new color to use for this component's background

setDrawingSurface

public void setDrawingSurface(ZDrawingSurface aSurface)

Sets the surface.

Parameters:

surface - the surface

getDrawingSurface

public ZDrawingSurface getDrawingSurface()

Return the surface.

Returns:

the surface

setCamera

public void setCamera(ZCamera aCamera)

Sets the camera.

Parameters:

camera - the camera

setCamera

public void setCamera(ZCamera aCamera,
                      ZNode aCameraNode)

Sets the camera.

Parameters:

aCamera - the camera

aCameraNode - the camera node

getCamera

public ZCamera getCamera()

Return the camera associated with the primary surface.

Returns:

the camera

getCameraNode

public ZNode getCameraNode()

Return the camera's node associated with the primary surface.

Returns:

the camera's node

setRoot

public void setRoot(ZRoot aRoot)

Sets the root of the scenegraph.

Parameters:

root - the root

getRoot

public ZRoot getRoot()

Return the root of the scenegraph.

Returns:

the root

setLayer

public void setLayer(ZLayerGroup aLayer)

Sets the layer of the scenegraph.

Parameters:

layer - the layer

getLayer

public ZLayerGroup getLayer()

Return the "layer". That is, the single node that the camera looks onto to start.

Returns:

the node

isFocusTraversable

public boolean isFocusTraversable()

Identifies whether or not this component can receive the focus.

Overrides:

isFocusTraversable in class javax.swing.JComponent

Returns:

true if this ZCanvas can receive the focus, otherwise false.

getScreenImage

public java.awt.Image getScreenImage(int maxDim)

Generate a copy of the view in the current camera scaled so that the aspect ratio of the screen is maintained, and the larger dimension is scaled to match the specified parameter.

Returns:

An image of the camera

getScreenImage

public java.awt.Image getScreenImage(int w,
                                     int h)

Generate a copy of the current camera scaled to the specified dimensions.

Parameters:

w - Width of the image

h - Height of the image

Returns:

An image of the camera

getPanEventHandler

public ZEventHandler getPanEventHandler()

Return the pan event handler.

Returns:

the pan event handler.

getZoomEventHandler

public ZEventHandler getZoomEventHandler()

Return the zoom event handler.

Returns:

the zoom event handler.

setSwingEventHandlersActive

public void setSwingEventHandlersActive(boolean active)

Control whether swing event handlers are active or not for this ZCanvas. This controls basic mouse events on Swing components within a ZCanvas.

Parameters:

active - - a boolean: true to enable the swing event handlers, false to disable them.

setNavEventHandlersActive

public void setNavEventHandlersActive(boolean active)

Control whether event handlers are active or not for this ZCanvas. This controls basic panning and zooming event handlers for the mouse, so that the left button pans, and the right button zooms.

getSwingWrapper

public javax.swing.JComponent getSwingWrapper()

Returns the component to which Swing components are added to function properly in Jazz. This method is public only to allow access to ZSwing. It should not be used otherwise.

Returns:

The component to which Swing components are added to function in Jazz

getSwingEventHandler

public ZSwingEventHandler getSwingEventHandler()

Returns the event handler that supports events for Swing Visual Components.

Returns:

the event handler that supports events for Swing Visual Components.

setEnableNodeEvents

public void setEnableNodeEvents(boolean enable)

Specify if Jazz node event handlers should be invoked. NOTE: This should only be called if Jazz Events are not needed

Parameters:

enable - True if node event handlers should be invoked.

getEnableNodeEvents

public final boolean getEnableNodeEvents()

Determine if Jazz node event handlers should be invoked.

Returns:

True if Node event handlers should be invoked.

setCursor

public void setCursor(java.awt.Cursor c)

Sets the cursor for this ZCanvas

Overrides:

setCursor in class java.awt.Component

Parameters:

c - The new cursor

setCursor

public void setCursor(java.awt.Cursor c,
                      boolean realSet)

Sets the cursor for this ZCanvas. If realSet is true then the cursor that displays when the mouse is over the ZCanvas is set as well as the currently displayed cursor. If realSet is false then only the currently displayed cursor is changed to indicate that the mouse is over a deeper component within the ZCanvas.

Parameters:

c - The new cursor

realSet - true - The ZCanvas cursor and current cursor set false - Only the current cursor set

resetCursor

public void resetCursor()

Sets the current cursor to the ZCanvas's cursor.

setToolTipText

public void setToolTipText(java.lang.String s)

Sets the ToolTip Text for this ZCanvas LEG: HACK - this includes a workaround to update the ToolTip as as soon as it changes by forwarding fake mouse events to the tooltip manager

Overrides:

setToolTipText in class javax.swing.JComponent

Parameters:

s - The new tooltip text