Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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.

To make a ZCanvas scrollable, you can add it to a ZScrollPane in the same way a normal JComponent is added to a JScrollPane. Note that manipulating the scrollbars changes the camera view, not the canvas view. By default, 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.

To get different scrolling behavior from the default, you can set the ZScrollDirector on the ZViewport. See the ScrollingExample in the jazz examples package for an example of a modified ZScrollDirector.

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

Nested Class Summary
 class ZCanvas.ZBasicRepaintManager
          This is an internal class used by Jazz to support Swing components in Jazz.
 
Nested classes inherited from class javax.swing.JComponent
javax.swing.JComponent.AccessibleJComponent
 
Nested classes inherited from class java.awt.Container
java.awt.Container.AccessibleAWTContainer
 
Nested classes inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
 
Field Summary
protected  boolean enableNodeEvents
          True if any ZMouseEvents are being sent to nodes on the canvas.
protected  boolean excludeMouseMoveEvents
          True if ZMouseEvents of type ZMouseEvent.MOUSE_MOVED, ZMouseEvent.MOUSE_ENTERED, and ZMouseEvent.MOUSE_EXITED are being excluded and not sent to nodes on the canvas.
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  ZSwingEventHandler swingEventHandler
          The event handler that supports events for Swing Visual Components.
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.
 boolean getExcludeMouseMoveEvents()
          Returns true if ZMouseEvents of type ZMouseEvent.MOUSE_MOVED, ZMouseEvent.MOUSE_ENTERED, and ZMouseEvent.MOUSE_EXITED are being excluded and not sent to nodes on the canvas.
 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.
 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 screenToGlobal(java.awt.geom.Dimension2D dimension)
          Converts the specified dimension from screen coordinates of this canvas to global coordinates.
 void screenToGlobal(java.awt.geom.Point2D pt)
          Converts the specified point from screen coordinates of this canvas to global coordinates.
 void screenToGlobal(java.awt.geom.Rectangle2D rectangle)
          Converts the specified rectangle from screen coordinates of this canvas to global coordinates.
 void setAutoScrollingEnabled(boolean autoScroll)
          Deprecated. As of Jazz version 1.2
 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 setExcludeMouseMoveEvents(boolean aBoolean)
          If the parameter aBoolean is true then ZMouseEvents of type ZMouseEvent.MOUSE_MOVED, ZMouseEvent.MOUSE_ENTERED, and ZMouseEvent.MOUSE_EXITED are being excluded and not sent to nodes on the canvas.
 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, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, 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, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFontSet, isForegroundSet, isLightweight, 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, processMouseEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, repaint, repaint, repaint, resize, resize, setBounds, setComponentOrientation, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, 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

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.

enableNodeEvents

protected boolean enableNodeEvents
True if any ZMouseEvents are being sent to nodes on the canvas.

excludeMouseMoveEvents

protected boolean excludeMouseMoveEvents
True if ZMouseEvents of type ZMouseEvent.MOUSE_MOVED, ZMouseEvent.MOUSE_ENTERED, and ZMouseEvent.MOUSE_EXITED are being excluded and not sent to nodes on the canvas. If a Jazz application does not need these event types then enabling this flag can increase performance since Jazz will not need to call ZDrawingSurface.pick() on every mouse movement.

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

setDrawingSurface

public void setDrawingSurface(ZDrawingSurface aSurface)
Sets the surface.

getDrawingSurface

public ZDrawingSurface getDrawingSurface()
Return the surface.

Returns:
the surface

setCamera

public void setCamera(ZCamera aCamera)
Sets 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.

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.

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 java.awt.Component
Returns:
true if this ZCanvas can receive the focus, otherwise false.

setAutoScrollingEnabled

public void setAutoScrollingEnabled(boolean autoScroll)
Deprecated. As of Jazz version 1.2

See Also:
ZScrollPane, ZViewport, ZScrollDirector, ZDefaultScrollDirector, JScrollPane.setHorizontalScrollBarPolicy(int), JScrollPane.setVerticalScrollBarPolicy(int)

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

screenToGlobal

public void screenToGlobal(java.awt.geom.Point2D pt)
Converts the specified point from screen coordinates of this canvas to global coordinates. This method modifies the pt parameter.

Parameters:
pt - the point in screen coords that will be converted to global coords.

screenToGlobal

public void screenToGlobal(java.awt.geom.Dimension2D dimension)
Converts the specified dimension from screen coordinates of this canvas to global coordinates. This method modifies the dimension parameter.

Parameters:
dimension - the point in screen coords that will be converted to global coords.

screenToGlobal

public void screenToGlobal(java.awt.geom.Rectangle2D rectangle)
Converts the specified rectangle from screen coordinates of this canvas to global coordinates. This method modifies the rectangle parameter.

Parameters:
rectangle - the rectangle in screen coords that will be converted to global coords.

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.

getExcludeMouseMoveEvents

public boolean getExcludeMouseMoveEvents()
Returns true if ZMouseEvents of type ZMouseEvent.MOUSE_MOVED, ZMouseEvent.MOUSE_ENTERED, and ZMouseEvent.MOUSE_EXITED are being excluded and not sent to nodes on the canvas. If a Jazz application does not need these event types then enabling this flag can increase performance since Jazz will not need to call ZDrawingSurface.pick() on every mouse movement.

setExcludeMouseMoveEvents

public void setExcludeMouseMoveEvents(boolean aBoolean)
If the parameter aBoolean is true then ZMouseEvents of type ZMouseEvent.MOUSE_MOVED, ZMouseEvent.MOUSE_ENTERED, and ZMouseEvent.MOUSE_EXITED are being excluded and not sent to nodes on the canvas. If a Jazz application does not need these event types then enabling this flag can increase performance since Jazz will not need to call ZDrawingSurface.pick() on every mouse movement.

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
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright � 2003 by University of Maryland, College Park, MD 20742, USA All rights reserved.