edu.neu.ccs.gui
Class BufferedPanel

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--javax.swing.JComponent
                    |
                    +--javax.swing.JPanel
                          |
                          +--edu.neu.ccs.gui.DisplayPanel
                                |
                                +--edu.neu.ccs.gui.BufferedPanel
All Implemented Interfaces:
Accessible, AlertListener, Displayable, EventListener, ImageObserver, JPTConstants, MalformedDataListener, MenuContainer, Serializable, SwingConstants

public class BufferedPanel
extends DisplayPanel

A panel that maintains a persistent graphics state by repainting itself from a stored BufferedImage object.

This behavior differs from the double-buffering provided in JComponent in that its intention is not necessarily to provide flicker-free repaints. Its goal is to retain the effects of method calls on its buffer graphics context regardless of whether or not those calls are in a paint method.

To ensure proper performance, the user should paint to the buffer graphics context, which is available through the getBufferGraphics method, rather than to a component graphics context provided as an argument to the paint method or returned by the getGraphics method.

Since:
1.0
See Also:
Serialized Form

Nested Class Summary
protected static class BufferedPanel.Painter
          Panel that paints the internal BufferedImage that maintains the persistent graphics state of a BufferedPanel.
 
Field Summary
protected  BufferedImage buffer
          The buffered image that maintains the persistent graphics state.
protected  Paint bufferBackground
          The background paint for this buffered panel.
static Color DEFAULT_BUFFER_BACKGROUND
          Default background color for a buffered panel.
protected  KeyActionAdapter keyActions
          The key action adapter for this buffered panel.
protected  MouseActionAdapter mouseActions
          The mouse action adapter for this buffered panel.
protected  BufferedPanel.Painter painter
          The internal painter panel.
 
Fields inherited from class edu.neu.ccs.gui.DisplayPanel
background, codec, CODEC
 
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 edu.neu.ccs.gui.Displayable
DEFAULT_VIEW_STATE, VIEW_STATE
 
Fields inherited from interface edu.neu.ccs.util.JPTConstants
ABOVE, ALIGNMENT, BELOW, BOTTOM_LEFT, BOTTOM_RIGHT, DEFAULT, FONT, INPUT_PROPERTIES, MANDATORY, OPTIONAL, ORIENTATION, TOP_LEFT, TOP_RIGHT
 
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
BufferedPanel(Dimension dimension)
          Constructs a BufferedPanel containing a buffered image with the given Dimension, and a white background.
BufferedPanel(Dimension dimension, Paint background)
          Constructs a BufferedPanel containing a buffered image with the given Dimension, and the given background color or Paint for the image.
BufferedPanel(int width, int height)
          Constructs a BufferedPanel containing a buffered image with the given width and height, and a white background.
BufferedPanel(int width, int height, Paint background)
          Constructs a BufferedPanel containing a buffered image with the given width and height, and the given background color or Paint for the image.
 
Method Summary
 void clearPanel()
          Fills this buffered panel with its background color or Paint.
 void fillPanel(Paint fill)
          Fills this buffered panel with the given color or Paint.
 BufferedImage getBuffer()
          Returns the internal buffered image for this panel.
 Paint getBufferBackground()
          Returns the background color or Paint for this buffered panel.
 Graphics2D getBufferGraphics()
          Returns a Graphics2D object that permits painting to the internal buffered image for this panel.
 int getBufferHeight()
          Returns the height of the buffered image.
 int getBufferWidth()
          Returns the width of the buffered image.
 DisplayPanel getInnerPanel()
          Returns the internal panel for this buffered panel, that is, the panel that paints the buffered image and handles the mouse and key adapters.
 KeyActionAdapter getKeyActionAdapter()
          Returns the key action adapter for the buffer.
 MouseActionAdapter getMouseActionAdapter()
          Returns the mouse action adapter for the buffer.
 void paintOver(Graphics2D g2)
          Override this paintOver method to add additional painting actions after the default buffer repaint is done during a repaint() call.
 void quickRepaint()
          Repaints the buffered panel directly without a call to the generic repaint method in Component.
 void setBackground(Color background)
          Sets the background color for the panel that wraps the buffer to the given color.
 void setBufferBackground(Paint background)
          Sets the background color or Paint to the given color or Paint.
 void setBufferSize(Dimension size)
          Sets the size of the buffered image to the given Dimension.
 void setBufferSize(int width, int height)
          Sets the size of the buffered image to the given height and width.
 void setKeyActionAdapter(KeyActionAdapter adapter)
          Sets the key action adapter for the buffer to the given adapter.
 void setMouseActionAdapter(MouseActionAdapter adapter)
          Sets the mouse action adapter for the buffer to the given adapter.
 
Methods inherited from class edu.neu.ccs.gui.DisplayPanel
add, add, add, add, add, addObject, addObject, addObject, addObject, dataMalformed, endAlert, frame, frame, frame, frame, frame, frame, generalDialog, generalDialog, generalDialog, generalDialog, getCodec, getDefaultViewState, getViewState, makeComponent, OKCancelDialog, OKCancelDialog, OKDialog, OKDialog, refreshComponent, remove, remove, removeAll, reset, setCodec, setDefaultViewState, setEnabled, setViewState, startAlert, uniformizeHeight, uniformizeSize, uniformizeWidth, YesNoCancelDialog, YesNoCancelDialog
 
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
 
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, 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, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, 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, setBorder, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
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, 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, isFocusTraversable, 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, 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

DEFAULT_BUFFER_BACKGROUND

public static final Color DEFAULT_BUFFER_BACKGROUND
Default background color for a buffered panel.


buffer

protected BufferedImage buffer
The buffered image that maintains the persistent graphics state.


painter

protected BufferedPanel.Painter painter
The internal painter panel.


bufferBackground

protected Paint bufferBackground
The background paint for this buffered panel.


mouseActions

protected MouseActionAdapter mouseActions
The mouse action adapter for this buffered panel.


keyActions

protected KeyActionAdapter keyActions
The key action adapter for this buffered panel.

Constructor Detail

BufferedPanel

public BufferedPanel(int width,
                     int height)

Constructs a BufferedPanel containing a buffered image with the given width and height, and a white background.

If the given width or height is less than 1 pixel, that value is set to 1 pixel.

Though the component itself may grow arbitrarily large, the buffered image painted to the buffer will remain the size specified in this constructor unless the size is reset using the setBufferSize method.

Parameters:
width - the width of the buffered image
height - the height of the buffered image
See Also:
BufferedPanel(Dimension), BufferedPanel(int, int, Paint), BufferedPanel(Dimension, Paint), setBufferSize(int, int), setBufferSize(Dimension)

BufferedPanel

public BufferedPanel(Dimension dimension)

Constructs a BufferedPanel containing a buffered image with the given Dimension, and a white background.

If the given Dimension is null, then the buffer width and height are both set to 1 pixel.

If the width or height of the given Dimension is less than 1 pixel, that value is set to 1 pixel.

Though the component itself may grow arbitrarily large, the buffered image painted to the buffer will remain the size specified in this constructor unless the size is reset using the setBufferSize method.

Parameters:
dimension - the dimension of the buffered image
See Also:
BufferedPanel(int, int), BufferedPanel(int, int, Paint), BufferedPanel(Dimension, Paint), setBufferSize(int, int), setBufferSize(Dimension)

BufferedPanel

public BufferedPanel(int width,
                     int height,
                     Paint background)

Constructs a BufferedPanel containing a buffered image with the given width and height, and the given background color or Paint for the image.

If the given width or height is less than 1 pixel, that value is set to 1 pixel.

Though the component itself may grow arbitrarily large, the buffered image painted to the buffer will remain the size specified in this constructor unless the size is reset using the setBufferSize method.

Parameters:
width - the width of the buffered image
height - the height of the buffered image
background - the background color or Paint for the buffered image
See Also:
BufferedPanel(int, int), BufferedPanel(Dimension), BufferedPanel(Dimension, Paint), setBufferSize(int, int), setBufferSize(Dimension)

BufferedPanel

public BufferedPanel(Dimension dimension,
                     Paint background)

Constructs a BufferedPanel containing a buffered image with the given Dimension, and the given background color or Paint for the image.

If the given Dimension is null, then the buffer width and height are both set to 1 pixel.

If the width or height of the given Dimension is less than 1 pixel, that value is set to 1 pixel.

Though the component itself may grow arbitrarily large, the buffered image painted to the buffer will remain the size specified in this constructor unless the size is reset using the setBufferSize method.

Parameters:
dimension - the dimension of the buffered image
background - the background color or Paint for the buffered image
See Also:
BufferedPanel(int, int), BufferedPanel(Dimension), BufferedPanel(int, int, Paint), setBufferSize(int, int), setBufferSize(Dimension)
Method Detail

getBufferGraphics

public Graphics2D getBufferGraphics()

Returns a Graphics2D object that permits painting to the internal buffered image for this panel.

The user should always use this object to paint to the buffer and thus indirectly modify this buffered panel.

To make painting changes to the buffer visible, the repaint() method must explicitly be called. This allows a number of painting operations to be done prior to screen repaint.

Returns:
the graphics context of the internal buffered image
See Also:
getBuffer(), getInnerPanel()

getBuffer

public BufferedImage getBuffer()

Returns the internal buffered image for this panel.

Returns:
the internal buffered image
See Also:
getBufferGraphics(), getInnerPanel()

getInnerPanel

public DisplayPanel getInnerPanel()

Returns the internal panel for this buffered panel, that is, the panel that paints the buffered image and handles the mouse and key adapters.

This panel may be used when access to the panel on which the graphics is drawn is needed.

Do not set a border on this internal panel. Set a border on the outer BufferedPanel object.

Returns:
the internal panel for this buffered panel
Since:
1.1
See Also:
getBufferGraphics(), getBuffer()

quickRepaint

public void quickRepaint()

Repaints the buffered panel directly without a call to the generic repaint method in Component.

Instead, this method directly asks the inner panel to paint itself which is done by repainting the screen from the buffer.

This method is supplied for performance reasons to support the use of animation in a buffered panel.

This method does nothing if the buffered panel is not installed in a window or dialog box.

Since:
2.3

setBufferBackground

public void setBufferBackground(Paint background)

Sets the background color or Paint to the given color or Paint.

If the given color or Paint is null, the current background is not changed.

Parameters:
background - the new background color or Paint
See Also:
getBufferBackground()

getBufferBackground

public Paint getBufferBackground()

Returns the background color or Paint for this buffered panel.

Returns:
the current background color or Paint
See Also:
setBufferBackground(Paint)

clearPanel

public void clearPanel()

Fills this buffered panel with its background color or Paint.

See Also:
fillPanel(Paint)

fillPanel

public void fillPanel(Paint fill)

Fills this buffered panel with the given color or Paint.

If the given color or Paint is null, the buffered panel is not changed.

Parameters:
fill - the color or Paint used to fill
See Also:
clearPanel()

setBackground

public void setBackground(Color background)

Sets the background color for the panel that wraps the buffer to the given color.

Overrides:
setBackground in class JComponent
Parameters:
background - the new background color

setBufferSize

public void setBufferSize(Dimension size)

Sets the size of the buffered image to the given Dimension.

If the given Dimension is null, the current image size is not changed.

If the width or height of the given Dimension is less than 1 pixel, it is set to 1 pixel.

Any image area gained by an size increase in either direction will be painted with the current background color.

Any image area lost by a size decrease in either direction will be clipped on the right and/or bottom of the image.

For a short time both the image of the previous size and an image of the new size are maintained in memory.

Parameters:
size - the new size for the image
See Also:
setBufferSize(int, int)

setBufferSize

public void setBufferSize(int width,
                          int height)

Sets the size of the buffered image to the given height and width.

If the given width or height is less than 1 pixel, it is set to 1 pixel.

Any image area gained by an size increase in either direction will be painted with the current background color.

Any image area lost by a size decrease in either direction will be clipped on the right and/or bottom of the image.

For a short time both the image of the previous size and an image of the new size are maintained in memory.

Parameters:
width - the new width for the image
height - the new height for the image
See Also:
setBufferSize(Dimension)

getBufferWidth

public int getBufferWidth()
Returns the width of the buffered image.

Returns:
the width of the buffered image

getBufferHeight

public int getBufferHeight()
Returns the height of the buffered image.

Returns:
the height of the buffered image

setMouseActionAdapter

public void setMouseActionAdapter(MouseActionAdapter adapter)

Sets the mouse action adapter for the buffer to the given adapter.

If null, the current adapter is not changed.

Parameters:
adapter - the new mouse action adapter
See Also:
getMouseActionAdapter()

getMouseActionAdapter

public MouseActionAdapter getMouseActionAdapter()
Returns the mouse action adapter for the buffer.

Returns:
the mouse action adapter for the buffer
See Also:
setMouseActionAdapter(MouseActionAdapter)

setKeyActionAdapter

public void setKeyActionAdapter(KeyActionAdapter adapter)

Sets the key action adapter for the buffer to the given adapter.

If null, the current adapter is not changed.

Parameters:
adapter - the new key action adapter
See Also:
getKeyActionAdapter()

getKeyActionAdapter

public KeyActionAdapter getKeyActionAdapter()
Returns the key action adapter for the buffer.

Returns:
the key action adapter for the buffer
See Also:
setKeyActionAdapter(KeyActionAdapter)

paintOver

public void paintOver(Graphics2D g2)

Override this paintOver method to add additional painting actions after the default buffer repaint is done during a repaint() call.

The intention of this facility is to enable algorithmic painting to be done via the paintOver method on top of the default painting of the buffer image on the panel. This makes the buffer appear to be the background and what is painted via the paintOver method to be painted in the foreground.

The default implementation of the paintOver method is to do nothing. This enables overrides as desired.

Parameters:
g2 - the Graphics2D context for the buffer repaint operation
Since:
1.0.1
See Also:
BufferedPanel.Painter.paint(Graphics)