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. Finally, 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.

ZCanvas defines basic event handlers for panning and zooming with the keyboard and mouse which can be disabled with @link{#disableEventHandlers}.

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 ZEventHandler	keyEventHandler The event handler that supports key events
protected ZEventHandler	panEventHandler The event handler that supports panning
protected ZSwingEventHandler	swingEventHandler The event handler that supports events for Swing Visual Components
protected ZEventHandler	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

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.
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.
boolean	isFocusTraversable()
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	processMouseEvent(java.awt.event.MouseEvent e) Internal method that overrides java.awt.Component.processMouseEvent to pass the mouse events to our listeners first, and then on to the other listeners.
protected void	processMouseMotionEvent(java.awt.event.MouseEvent e) Internal method that overrides java.awt.Component.processMouseEvent to pass the mouse events to our listeners first, and then on to the other listeners.
void	resetCursor() Sets the current cursor to the ZCanvas's cursor
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	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.
void	setNavEventHandlersActive(boolean active) Control whether event handlers are active or not for this ZCanvas.
void	setRoot(ZRoot aRoot) Sets the root.
void	setSwingEventHandlersActive(boolean active)

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, 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, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processFocusEvent, processKeyBinding, processKeyEvent, 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, setToolTipText, 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, disable, disableEvents, dispatchEvent, enable, 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, 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

swingEventHandler

protected ZSwingEventHandler swingEventHandler

The event handler that supports events for Swing Visual Components

panEventHandler

protected ZEventHandler panEventHandler

The event handler that supports panning

zoomEventHandler

protected ZEventHandler zoomEventHandler

The event handler that supports zooming

keyEventHandler

protected ZEventHandler keyEventHandler

The event handler that supports key events

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.

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

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.

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.

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()

Overrides:

isFocusTraversable in class javax.swing.JComponent

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. *@eturn the zoom event handler.

setSwingEventHandlersActive

public void setSwingEventHandlersActive(boolean active)

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. Only public to give access to ZSwing. Should not be used otherwise.

Returns:

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

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.

processMouseEvent

public void processMouseEvent(java.awt.event.MouseEvent e)

Internal method that overrides java.awt.Component.processMouseEvent to pass the mouse events to our listeners first, and then on to the other listeners. This allows Jazz to support consuming the events, and only passing the events on if they are not consumed. Mouse events get dispatched with the following priority (assuming swing and node events are enabled.)

1. If there is a Swing widget, then that gets the mouse event
2. If the event is not consumed, and there is a node event listener, then that gets the event
3. If the event is not consumed, then any other component event listeners are processed.

Overrides:

processMouseEvent in class java.awt.Component

Parameters:

e - The MouseEvent to process

See Also:

setEnableNodeEvents(boolean)

processMouseMotionEvent

protected void processMouseMotionEvent(java.awt.event.MouseEvent e)

Internal method that overrides java.awt.Component.processMouseEvent to pass the mouse events to our listeners first, and then on to the other listeners. This allows Jazz to support consuming the events, and only passing the events on if they are not consumed. Mouse events get dispatched with the following priority (assuming swing and node events are enabled.)

1. If there is a Swing widget, then that gets the mouse event
2. If the event is not consumed, and there is a node event listener, then that gets the event
3. If the event is not consumed, then any other component event listeners are processed.

Overrides:

processMouseMotionEvent in class javax.swing.JComponent

Parameters:

e - The MouseEvent to process

See Also:

setEnableNodeEvents(boolean)

setCursor

public void setCursor(java.awt.Cursor c)

Sets the cursor for this ZCanvas

Overrides:

setCursor in class java.awt.Container

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