edu.umd.cs.piccolo
Class PCanvas

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              edu.umd.cs.piccolo.PCanvas

All Implemented Interfaces:

PComponent, ImageObserver, MenuContainer, Serializable

public class PCanvas
extends JComponent
implements PComponent

PCanvas is a simple Swing component that can be used to embed Piccolo into a Java Swing application. Canvases view the Piccolo scene graph through a camera. The canvas manages screen updates coming from this camera, and forwards swing mouse and keyboard events to the camera.

Version:

1.0

Author:

Jesse Grosjean

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

static PCanvas	CURRENT_ZCANVAS Deprecated. since it falsely assumes that there is only one PCanvas per program
static String	INTERACTING_CHANGED_NOTIFICATION Deprecated. in favor of PROPERTY_INTERACTING
static String	INTERATING_CHANGED_NOTIFICATION Deprecated. this is a typo and clients should change their code to reflect the correct spelling
static String	PROPERTY_INTERACTING The property name that identifies a change in the interacting state.

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

PCanvas()
Construct a canvas with the basic scene graph consisting of a root, camera, and layer.

Method Summary

void	addInputEventListener(PInputEventListener listener) Add an input listener to the camera associated with this canvas.
protected PCamera	createDefaultCamera() Creates and returns a basic Scene Graph.
Timer	createTimer(int delay, ActionListener listener) Helper for creating a timer.
boolean	getAnimating() Return true if any activities that respond with true to the method isAnimating were run in the last PRoot.processInputs() loop.
int	getAnimatingRenderQuality() Returns the quality to use when animating.
PCamera	getCamera() Return the camera associated with this canvas.
int	getDefaultRenderQuality() Deprecated. in favor or getNormalRenderQuality
PInputEventListener[]	getInputEventListeners() Returns the input event listeners registered to receive input events.
boolean	getInteracting() Return true if this canvas has been marked as interacting, or whether it's root is interacting.
int	getInteractingRenderQuality() Returns the quality to use when interacting.
PLayer	getLayer() Return layer for this canvas.
int	getNormalRenderQuality() Returns the quality to use when not animating or interacting.
PPanEventHandler	getPanEventHandler() Get the pan event handler associated with this canvas.
PRoot	getRoot() Return root for this canvas.
PZoomEventHandler	getZoomEventHandler() Get the zoom event handler associated with this canvas.
protected void	installInputSources() This method installs mouse and key listeners on the canvas that forward those events to piccolo.
void	paintComponent(Graphics g)
void	paintImmediately() If not painting immediately, send paint notification to RepaintManager, otherwise does nothing.
void	popCursor() Pop the cursor on top of the cursorStack and set it as the canvas cursor.
void	printAll(Graphics graphics) Prints the entire scene regardless of what the viewable area is.
void	pushCursor(Cursor cursor) Set the canvas cursor, and remember the previous cursor on the cursor stack.
void	removeInputEventListener(PInputEventListener listener) Remove an input listener to the camera associated with this canvas.
protected void	removeInputSources() This method removes mouse and key listeners on the canvas that forward those events to piccolo.
void	repaint(PBounds bounds) Called to notify PComponent that given bounds need repainting.
protected void	sendInputEventToInputManager(InputEvent event, int type) Sends the given input event with the given type to the current InputManager.
void	setAnimatingRenderQuality(int animatingRenderQuality) Set the render quality that should be used when rendering this canvas when it is animating.
void	setBounds(int x, int y, int width, int height) Updates the bounds of the component and updates the camera accordingly.
void	setCamera(PCamera newCamera) Set the camera associated with this canvas.
void	setDefaultRenderQuality(int defaultRenderQuality) Set the render quality that should be used when rendering this canvas when it is not interacting or animating.
void	setEnabled(boolean enabled) Override setEnabled to install/remove canvas input sources as needed.
void	setInteracting(boolean isInteracting) Set if this canvas is interacting.
void	setInteractingRenderQuality(int interactingRenderQuality) Set the render quality that should be used when rendering this canvas when it is interacting.
void	setPanEventHandler(PPanEventHandler handler) Set the pan event handler associated with this canvas.
void	setZoomEventHandler(PZoomEventHandler handler) Set the zoom event handler associated with this canvas.

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, 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, printBorder, printChildren, printComponent, 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, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, 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, invalidate, 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, 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

INTERATING_CHANGED_NOTIFICATION

public static final String INTERATING_CHANGED_NOTIFICATION

Deprecated. this is a typo and clients should change their code to reflect the correct spelling

See Also:

Constant Field Values

INTERACTING_CHANGED_NOTIFICATION

public static final String INTERACTING_CHANGED_NOTIFICATION

Deprecated. in favor of PROPERTY_INTERACTING

The property name that identifies a change in the interacting state.

Since:

1.3

See Also:

Constant Field Values

PROPERTY_INTERACTING

public static final String PROPERTY_INTERACTING

The property name that identifies a change in the interacting state.

Since:

1.3

See Also:

Constant Field Values

CURRENT_ZCANVAS

public static PCanvas CURRENT_ZCANVAS

Deprecated. since it falsely assumes that there is only one PCanvas per program

Used as a public global to track the current canvas.

Constructor Detail

PCanvas

public PCanvas()

Construct a canvas with the basic scene graph consisting of a root, camera, and layer. Zooming and panning are automatically installed.

Method Detail

createDefaultCamera

protected PCamera createDefaultCamera()

Creates and returns a basic Scene Graph.

Returns:

a built PCamera scene

getPanEventHandler

public PPanEventHandler getPanEventHandler()

Get the pan event handler associated with this canvas. This event handler is set up to get events from the camera associated with this canvas by default.

Returns:

the current pan event handler, may be null

setPanEventHandler

public void setPanEventHandler(PPanEventHandler handler)

Set the pan event handler associated with this canvas.

Parameters:

handler - the new zoom event handler

getZoomEventHandler

public PZoomEventHandler getZoomEventHandler()

Get the zoom event handler associated with this canvas. This event handler is set up to get events from the camera associated with this canvas by default.

Returns:

the current zoom event handler, may be null

setZoomEventHandler

public void setZoomEventHandler(PZoomEventHandler handler)

Set the zoom event handler associated with this canvas.

Parameters:

handler - the new zoom event handler

getCamera

public PCamera getCamera()

Return the camera associated with this canvas. All input events from this canvas go through this camera. And this is the camera that paints this canvas.

Returns:

camera through which this PCanvas views the scene

setCamera

public void setCamera(PCamera newCamera)

Set the camera associated with this canvas. All input events from this canvas go through this camera. And this is the camera that paints this canvas.

Parameters:

newCamera - the camera which this PCanvas should view the scene

getRoot

public PRoot getRoot()

Return root for this canvas.

Returns:

the root PNode at the "bottom" of the scene

getLayer

public PLayer getLayer()

Return layer for this canvas.

Returns:

the first layer attached to this camera

addInputEventListener

public void addInputEventListener(PInputEventListener listener)

Add an input listener to the camera associated with this canvas.

Parameters:

listener - listener to register for event notifications

removeInputEventListener

public void removeInputEventListener(PInputEventListener listener)

Remove an input listener to the camera associated with this canvas.

Parameters:

listener - listener to unregister from event notifications

getInteracting

public boolean getInteracting()

Return true if this canvas has been marked as interacting, or whether it's root is interacting. If so the canvas will normally render at a lower quality that is faster.

Returns:

whether the canvas has been flagged as being interacted with

getAnimating

public boolean getAnimating()

Return true if any activities that respond with true to the method isAnimating were run in the last PRoot.processInputs() loop. This values is used by this canvas to determine the render quality to use for the next paint.

Returns:

whether the PCanvas is currently being animated

setInteracting

public void setInteracting(boolean isInteracting)

Set if this canvas is interacting. If so the canvas will normally render at a lower quality that is faster. Also repaints the canvas if the render quality should change.

Specified by:

setInteracting in interface PComponent

Parameters:

isInteracting - whether the PCanvas should be considered interacting

setDefaultRenderQuality

public void setDefaultRenderQuality(int defaultRenderQuality)

Set the render quality that should be used when rendering this canvas when it is not interacting or animating. The default value is PPaintContext. HIGH_QUALITY_RENDERING.

Parameters:

defaultRenderQuality - supports PPaintContext.HIGH_QUALITY_RENDERING or PPaintContext.LOW_QUALITY_RENDERING

setAnimatingRenderQuality

public void setAnimatingRenderQuality(int animatingRenderQuality)

Set the render quality that should be used when rendering this canvas when it is animating. The default value is PPaintContext.LOW_QUALITY_RENDERING.

Parameters:

animatingRenderQuality - supports PPaintContext.HIGH_QUALITY_RENDERING or PPaintContext.LOW_QUALITY_RENDERING

setInteractingRenderQuality

public void setInteractingRenderQuality(int interactingRenderQuality)

Set the render quality that should be used when rendering this canvas when it is interacting. The default value is PPaintContext.LOW_QUALITY_RENDERING.

Parameters:

interactingRenderQuality - supports PPaintContext.HIGH_QUALITY_RENDERING or PPaintContext.LOW_QUALITY_RENDERING

pushCursor

public void pushCursor(Cursor cursor)

Set the canvas cursor, and remember the previous cursor on the cursor stack.

Specified by:

pushCursor in interface PComponent

Parameters:

cursor - the cursor to push onto the cursor stack

popCursor

public void popCursor()

Pop the cursor on top of the cursorStack and set it as the canvas cursor.

Specified by:

popCursor in interface PComponent

setEnabled

public void setEnabled(boolean enabled)

Override setEnabled to install/remove canvas input sources as needed.

Overrides:

setEnabled in class JComponent

Parameters:

enabled - new enable status of the Pcanvas

installInputSources

protected void installInputSources()

This method installs mouse and key listeners on the canvas that forward those events to piccolo.

removeInputSources

protected void removeInputSources()

This method removes mouse and key listeners on the canvas that forward those events to piccolo.

sendInputEventToInputManager

protected void sendInputEventToInputManager(InputEvent event,
                                            int type)

Sends the given input event with the given type to the current InputManager.

Parameters:

event - event to dispatch

type - type of event being dispatched

setBounds

public void setBounds(int x,
                      int y,
                      int width,
                      int height)

Updates the bounds of the component and updates the camera accordingly.

Overrides:

setBounds in class Component

Parameters:

x - left of bounds

y - top of bounds

width - width of bounds

height - height of bounds

repaint

public void repaint(PBounds bounds)

Called to notify PComponent that given bounds need repainting.

Specified by:

repaint in interface PComponent

Parameters:

bounds - bounds needing repaint

paintComponent

public void paintComponent(Graphics g)

Overrides:

paintComponent in class JComponent

paintImmediately

public void paintImmediately()

If not painting immediately, send paint notification to RepaintManager, otherwise does nothing.

Specified by:

paintImmediately in interface PComponent

createTimer

public Timer createTimer(int delay,
                         ActionListener listener)

Helper for creating a timer. It's an extension point for subclasses to install their own timers.

Parameters:

delay - the number of milliseconds to wait before invoking the listener

listener - the listener to invoke after the delay

Returns:

the created Timer

getDefaultRenderQuality

public int getDefaultRenderQuality()

Deprecated. in favor or getNormalRenderQuality

Returns the quality to use when not animating or interacting.

Returns:

the render quality to use when not animating or interacting

Since:

1.3

getNormalRenderQuality

public int getNormalRenderQuality()

Returns the quality to use when not animating or interacting.

Returns:

the render quality to use when not animating or interacting

Since:

1.3

getAnimatingRenderQuality

public int getAnimatingRenderQuality()

Returns the quality to use when animating.

Returns:

Returns the quality to use when animating

Since:

1.3

getInteractingRenderQuality

public int getInteractingRenderQuality()

Returns the quality to use when interacting.

Returns:

Returns the quality to use when interacting

Since:

1.3

getInputEventListeners

public PInputEventListener[] getInputEventListeners()

Returns the input event listeners registered to receive input events.

Returns:

array or input event listeners

Since:

1.3

printAll

public void printAll(Graphics graphics)

Prints the entire scene regardless of what the viewable area is.

Overrides:

printAll in class JComponent

Parameters:

graphics - Graphics context onto which to paint the scene for printing