edu.neu.ccs.gui
Class BufferedPanel

java.lang.Object
  extended byjava.awt.Component
      extended byjava.awt.Container
          extended byjavax.swing.JComponent
              extended byjavax.swing.JPanel
                  extended byedu.neu.ccs.gui.DisplayPanel
                      extended byedu.neu.ccs.gui.BufferedPanel
All Implemented Interfaces:
Accessible, AlertListener, Displayable, EventListener, ImageObserver, JPTConstants, MalformedDataListener, MenuContainer, Serializable, SwingConstants

public class BufferedPanel
extends DisplayPanel

A BufferedPanel combines bit-map-graphics with algorithmic graphics based on objects.

A BufferedPanel maintains a base layer onto which the caller may paint graphics of arbitrary complexity; the data in this base layer is stored in a Java BufferedImage that persists until changed by the caller; the panel also holds a PaintableSequence whose objects are painted on top of the base layer; in effect, the paintable sequence collects a sequence of sprites that are painted above the image that is held in the base layer.

This design allows a BufferedPanel to combine the flexibility of mutatable graphics objects held in the paintable sequence with the advantages of a persistant background image that is stored in a bit-map.

We will now give a brief tutorial on how to use a BufferedPanel. For simplicity, we assume the name of the panel is "window".

By default, the BufferedPanel has a background of white paint. To change this initial background if desired, use the calls:

window.setBufferBackground(the-paint);

window.clearPanel();

Once the initial background is set, one can make further changes to the bit-map-image of the window. To do this, one must get the graphics context of the bit-map-image via the call:

Graphics2D g = window.getBufferGraphics();

Then, one can make any calls in the Java Graphics2D library or in JPT to act on g and change the bit-map-image. In this way, arbitrary graphics may be drawn on the bit-map-image. Such graphics will persist in the bits until explicitly changed.

The caller can decide when to refresh the screen. To do this, make the call:

window.repaint();

A second way to supply graphics in a BufferedPanel is to add one more Paintable objects to a PaintableSequence that is maintained by the panel. You may think of a Paintable as an object that maintains both graphics state and algorithmics for painting that state. A Paintable can also be mutated by affine transformations and, in particular, may be dragged on the screen if suitable mouse behavior has been installed in the window.

A BufferedPanel has methods to set, add, or remove Paintables one-by-one or by using arrays of Paintables. For convenience, one can supply general objects and this class will make a best effort to convert such objects into Paintables. The key to this generality is that the method ComponentFactory.makePaintable is invoked when an object is presented to the panel to be added. If the object is already Paintable then it is added as-is; otherwise it is converted into a Paintable if that is possible.

One can obtain the PaintableSequence object and use that object to perform sophisticated actions such as mutation by affine transformations. For convenience, the panel also has a built-in option to use the mouse to drag the Paintable objects. To install this option, make the call:

window.installSimpleMouseActions(shift);

If the supplied boolean parameter shift is true then when a Paintable is clicked by the mouse it will be shifted to be the topmost Paintable in the sequence.

It is certainly possible for the caller to create more sophisticated mouse behavior and install such behavior.

Finally, the BufferedPanel class provides a "hook" so that a derived class can add additional algorithmic graphics features. There is a method:

public void paintOver(Graphics2D g2)

By default, this method does nothing. However, a derived class may redefine this method to do anything whatsover. The order of painting calls in the class is then as follows:

Note that one may install key actions for this panel but there are no default key actions that have been predefined. This decision is left to the user of this class.

In 2.6.0, the interface Paintable introduced the notions of a background paint and a background tile. The implication is that the internal paintable sequence of this buffered panel can also have a background paint or a background tile. Thus, the description of how the panel is painted may now be expanded to:

To support use of the background paint of the internal paintable sequence, the default bounds of the sequence are explicitly set to be the rectangle for the internal buffer. Hence, if the background of the paintable sequence is set to an opaque paint, it will entirely cover up what is painted via the buffer. This can be extremely useful. For example, if you set the background paint of the sequence to white, then that will hide the buffer; if you later clear this background paint, then the buffer will once again be visible. Hence, it is unnecessary to copy the buffer to some auxiliary buffer just to hide and restore it.

A number of methods have been added that support setting and clearing of the background paint and background tile of the internal paintable sequence.

Changes in 2.6.0d:

Changes in 2.6.0e:

A BufferedPanel is constructed with an inner panel of class Painter that is responsible for painting and for returning the preferred size of the component. In this release, the body of the methods paint and paintComponent in class Painter have been synchronized on the enclosing BufferedPanel object. This means that the user of this class has the option of also using synchronized on this BufferedPanel object when making changes to either the internal BufferedImage or to the PaintableSequence of objects painted above the buffer. If this synchronization is done, then Java repainting will not take place while the data structure is undergoing change. In practice, this synchronization is needed only when lots of dynamic activity is happening.

Since:
1.0
Version:
2.6.0e
See Also:
Serialized Form

Nested Class Summary
protected static class BufferedPanel.Painter
          Panel that paints the internal buffered image that maintains the persistent graphics state of the buffered panel.
 
Nested classes inherited from class javax.swing.JPanel
JPanel.AccessibleJPanel
 
Nested classes inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
 
Nested classes inherited from class java.awt.Container
Container.AccessibleAWTContainer
 
Nested classes inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
protected  boolean autoShiftToTop
          Whether or not to shift the current paintable to the top.
protected  BufferedImage buffer
          The buffered image that maintains the persistent graphics state.
protected  Paint bufferBackground
          The background paint for this buffered panel.
private  int bufferheight
          The buffer height.
private  int bufferwidth
          The buffer width.
protected  Paintable currentPaintable
          The current paintable being dragged.
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  boolean mouseIsInPanel
          Whether or not the mouse is in the panel.
protected  int mouseX
          The mouse x-position.
protected  int mouseY
          The mouse y-position.
protected  PaintableSequence paintablesequence
          The paintable sequence that paints on top of the buffer.
protected  BufferedPanel.Painter painter
          The internal painter panel.
protected  MouseAction SMA_Clicked_Action
          The "Simple Mouse Action" clicked action.
protected  MouseAction SMA_Dragged_Action
          The "Simple Mouse Action" dragged action.
protected  MouseAction SMA_Entered_Action
          The "Simple Mouse Action" entered panel action.
protected  MouseAction SMA_Exited_Action
          The "Simple Mouse Action" exited panel action.
protected  MouseAction SMA_Moved_Action
          The "Simple Mouse Action" moved action.
protected  MouseAction SMA_Pressed_Action
          The "Simple Mouse Action" pressed action.
protected  MouseAction SMA_Released_Action
          The "Simple Mouse Action" released action.
 
Fields inherited from class edu.neu.ccs.gui.DisplayPanel
background, codec, CODEC
 
Fields inherited from class javax.swing.JPanel
 
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.Container
 
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, VALUE
 
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
 Paintable addPaintable(int index, Object o)
          Calls the corresponding method on the internal paintable sequence.
 Paintable addPaintable(Object o)
          Calls the corresponding method on the internal paintable sequence.
 Paintable addPaintable(Object o, int index)
          Calls the corresponding method on the internal paintable sequence.
 Paintable addPaintableAtTop(Object o)
          Calls the corresponding method on the internal paintable sequence.
 Paintable[] addSequence(int index, Object[] objects)
          Calls the corresponding method on the internal paintable sequence.
 Paintable[] addSequence(Object[] objects)
          Calls the corresponding method on the internal paintable sequence.
 Paintable[] addSequence(Object[] objects, int index)
          Calls the corresponding method on the internal paintable sequence.
 Paintable[] addSequenceAtTop(Object[] objects)
          Calls the corresponding method on the internal paintable sequence.
 Paintable appendPaintable(Object o)
          Calls the corresponding method on the internal paintable sequence.
 Paintable[] appendSequence(Object[] objects)
          Calls the corresponding method on the internal paintable sequence.
 void clearBothSequenceBackgrounds()
          Clear the both the internal paintable sequence background paint and the internal paintable sequence background tile.
 void clearPanel()
          Fills this buffered panel with its background color or Paint.
 Paintable[] clearPanelAndSequence()
          Fills this buffered panel with its background color or Paint and clears the internal paintable sequence; returns an array with the paintables removed.
 Paintable[] clearPanelAndSequenceData()
          Fills this buffered panel with its background color or Paint and clears all data in the internal paintable sequence, that is, the sequence paintables, the sequence background paint, and the sequence background tile; returns an array with the paintables removed.
 Paintable[] clearSequence()
          Clears the internal paintable sequence; returns an array with the paintables removed.
 void clearSequenceBackgroundPaint()
          Clear the internal paintable sequence background paint.
 void clearSequenceBackgroundTile()
          Clear the internal paintable sequence background tile.
 Paintable[] clearSequenceData()
          Clears all data in the internal paintable sequence, that is, the sequence paintables, the sequence background paint, and the sequence background tile; returns an array with the paintables removed.
 void drawGrid(int pixels)
          Draws a grid with spacing equal to the given pixels value and color equal to Colors.lightgray.
 void drawGrid(int pixels, Color color)
          Draws a grid with spacing equal to the given pixels value and color equal to the given color.
 void fillPanel(Paint fill)
          Fills this buffered panel with the given color or Paint.
 boolean getAutoShiftToTop()
          Gets whether or not a clicked paintable should shift to the top of the paintable sequence.
 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.
 int getIndex(Paintable paintable)
          Calls the corresponding method on the internal paintable sequence.
 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.
 int getMouseX()
          Gets the current value of the mouse x-position.
 int getMouseY()
          Gets the current value of the mouse y-position.
 Paintable getPaintable(int index)
          Calls the corresponding method on the internal paintable sequence.
 PaintableSequence getPaintableSequence()
          Gets the internal PaintableSequence that will be painted after the underlying buffer is painted.
 Paint getSequenceBackgroundPaint()
          Returns the internal paintable sequence background paint.
 Paintable getSequenceBackgroundTile()
          Returns the internal paintable sequence background tile.
 void installSimpleMouseActions()
          Installs a set of simple mouse actions that by default will permit a user to drag the paintables in the internal paintable sequence.
 void installSimpleMouseActions(boolean shift)
          Convenience method that installs the simple mouse actions and sets the auto-shift-to-top parameter at the same time.
 boolean isFocusable()
          Overrides to delegate to the inner panel that is the panel returned by getInnerPanel().
 boolean isRequestFocusEnabled()
          Overrides to delegate to the inner panel that is the panel returned by getInnerPanel().
private  void makePainterPanelIfNeeded()
           
 BufferedImage makeSnapshot()
          Construct a BufferedImage object that is the same size as this buffered panel and then paint this new buffered image by simulating the paint operations of this buffered panel.
 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.
 Paintable removePaintable(int index)
          Calls the corresponding method on the internal paintable sequence.
 void removePaintable(Paintable paintable)
          Calls the corresponding method on the internal paintable sequence.
 Paintable[] removeSequence(int m, int n)
          Calls the corresponding method on the internal paintable sequence.
 void requestFocus()
          Overrides to delegate to the inner panel that is the panel returned by getInnerPanel().
 boolean requestFocusInWindow()
          Overrides to delegate to the inner panel that is the panel returned by getInnerPanel().
 void setAutoShiftToTop(boolean shift)
          Sets whether or not a clicked paintable should shift to the top of the paintable sequence.
 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 width and height.
 void setFocusable(boolean focusable)
          Overrides to delegate to the inner panel that is the panel returned by getInnerPanel().
 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.
 void setMousePosition(MouseEvent evt)
          Sets the mouse position from the mouse event.
 Paintable setPaintable(int index, Object o)
          Calls the corresponding method on the internal paintable sequence.
 Paintable setPaintable(Object o, int index)
          Calls the corresponding method on the internal paintable sequence.
 Paintable[] setSequence(Object[] objects)
          Calls the corresponding method on the internal paintable sequence.
 void setSequenceBackgroundPaint(Paint background)
          Sets the internal paintable sequence background paint.
 void setSequenceBackgroundTile(Object object)
          Sets the internal paintable sequence background tile paintable.
protected  void SMA_Clicked(MouseEvent evt)
          The method that implements the "Simple Mouse Action" clicked action.
protected  void SMA_Dragged(MouseEvent evt)
          The method that implements the "Simple Mouse Action" dragged action.
protected  void SMA_Entered(MouseEvent evt)
          The method that implements the "Simple Mouse Action" entered panel action.
protected  void SMA_Exited(MouseEvent evt)
          The method that implements the "Simple Mouse Action" exited panel action.
protected  void SMA_Moved(MouseEvent evt)
          The method that implements the "Simple Mouse Action" moved action.
protected  void SMA_Pressed(MouseEvent evt)
          The method that implements the "Simple Mouse Action" pressed action.
protected  void SMA_Released(MouseEvent evt)
          The method that implements the "Simple Mouse Action" released action.
 void uninstallAllKeyActions()
          Uninstalls all key actions that have been attached to the key action adapter for this panel.
 void uninstallAllMouseActions()
          Uninstalls all mouse actions that have been attached to the mouse action adapter for this panel.
 
Methods inherited from class edu.neu.ccs.gui.DisplayPanel
add, add, add, add, add, addBorder, addObject, addObject, addObject, addObject, bevelBorderLowered, bevelBorderLowered, bevelBorderLowered, bevelBorderLowered, bevelBorderLowered, bevelBorderRaised, bevelBorderRaised, bevelBorderRaised, bevelBorderRaised, bevelBorderRaised, compoundBorder, compoundBorder, dataMalformed, emptyBorder, emptyBorder, emptyBorder, endAlert, etchBorderLowered, etchBorderLowered, etchBorderLowered, etchBorderRaised, etchBorderRaised, etchBorderRaised, frame, frame, frame, frame, frame, frame, generalDialog, generalDialog, generalDialog, generalDialog, getCodec, getDefaultViewState, getDefaultViewStates, getDisplayables, getViewState, getViewStates, lineBorder, lineBorder, lineBorder, lineBorder, makeComponent, matteBorder, matteBorder, matteBorder, matteBorder, matteBorder, matteBorder, OKCancelDialog, OKCancelDialog, OKDialog, OKDialog, refreshComponent, remove, remove, removeAll, removeBorder, reset, sandwichBorder, setCodec, setDeepBackground, setDeepBackground, setDefaultViewState, setDefaultViewStates, setEnabled, setViewState, setViewStates, startAlert, titleBorder, titleBorder, titleBorder, titleBorder, titleBorder, titleBorder, titleBorder, titleBorder, 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, 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, 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, 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, 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.


bufferwidth

private int bufferwidth
The buffer width.


bufferheight

private int bufferheight
The buffer height.


paintablesequence

protected PaintableSequence paintablesequence
The paintable sequence that paints on top of the buffer.


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.


mouseX

protected int mouseX
The mouse x-position.


mouseY

protected int mouseY
The mouse y-position.


currentPaintable

protected Paintable currentPaintable
The current paintable being dragged.


autoShiftToTop

protected boolean autoShiftToTop
Whether or not to shift the current paintable to the top.


mouseIsInPanel

protected boolean mouseIsInPanel
Whether or not the mouse is in the panel.


SMA_Moved_Action

protected MouseAction SMA_Moved_Action
The "Simple Mouse Action" moved action.


SMA_Pressed_Action

protected MouseAction SMA_Pressed_Action
The "Simple Mouse Action" pressed action.


SMA_Released_Action

protected MouseAction SMA_Released_Action
The "Simple Mouse Action" released action.


SMA_Clicked_Action

protected MouseAction SMA_Clicked_Action
The "Simple Mouse Action" clicked action.


SMA_Dragged_Action

protected MouseAction SMA_Dragged_Action
The "Simple Mouse Action" dragged action.


SMA_Entered_Action

protected MouseAction SMA_Entered_Action
The "Simple Mouse Action" entered panel action.


SMA_Exited_Action

protected MouseAction SMA_Exited_Action
The "Simple Mouse Action" exited panel action.

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

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

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

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
Method Detail

makePainterPanelIfNeeded

private void makePainterPanelIfNeeded()

getBufferGraphics

public final 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.


getBuffer

public final BufferedImage getBuffer()

Returns the internal buffered image for this panel.


setBufferSize

public final 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

setBufferSize

public final void setBufferSize(int width,
                                int height)

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

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

getBufferWidth

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


getBufferHeight

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


makeSnapshot

public final BufferedImage makeSnapshot()

Construct a BufferedImage object that is the same size as this buffered panel and then paint this new buffered image by simulating the paint operations of this buffered panel.

This method creates a snapshot of the current visual state of this buffered panel.

Insets and borders to the buffered panel are ignored.


getInnerPanel

public final 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.

Since:
1.1

quickRepaint

public final 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 is not 100% robust because Java occasionally loses track of where on the screen it is painting. Therefore, this method should be used only if performance issues require that it be used. Using repaint is still the recommended way to repaint the buffered panel.

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

Since:
2.3

fillPanel

public final 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

clearPanel

public final void clearPanel()

Fills this buffered panel with its background color or Paint.

See Also:
getBufferBackground(), setBufferBackground(Paint)

clearSequence

public final Paintable[] clearSequence()

Clears the internal paintable sequence; returns an array with the paintables removed.

Calls the corresponding method on the internal paintable sequence.


clearPanelAndSequence

public final Paintable[] clearPanelAndSequence()

Fills this buffered panel with its background color or Paint and clears the internal paintable sequence; returns an array with the paintables removed.


clearSequenceData

public final Paintable[] clearSequenceData()

Clears all data in the internal paintable sequence, that is, the sequence paintables, the sequence background paint, and the sequence background tile; returns an array with the paintables removed.

Calls clearEverything on the internal paintable sequence.


clearPanelAndSequenceData

public final Paintable[] clearPanelAndSequenceData()

Fills this buffered panel with its background color or Paint and clears all data in the internal paintable sequence, that is, the sequence paintables, the sequence background paint, and the sequence background tile; returns an array with the paintables removed.

Calls clearEverything on the internal paintable sequence.


setBufferBackground

public final 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.

The panel is only filled with the background paint if one of clearPanel... methods is called after setting the background. The reason for this is that changing the buffer background destroys all current color data in the buffer and the caller should make an explicit decision to do this action.

Parameters:
background - the new background color or Paint

getBufferBackground

public final Paint getBufferBackground()

Returns the background color or Paint for this buffered panel.


setSequenceBackgroundPaint

public final void setSequenceBackgroundPaint(Paint background)

Sets the internal paintable sequence background paint.

The paint may be set to null to eliminate background painting.

Parameters:
background - the internal paintable sequence background paint

getSequenceBackgroundPaint

public final Paint getSequenceBackgroundPaint()
Returns the internal paintable sequence background paint.

Returns:
the internal paintable sequence background paint.

clearSequenceBackgroundPaint

public final void clearSequenceBackgroundPaint()

Clear the internal paintable sequence background paint.


setSequenceBackgroundTile

public final void setSequenceBackgroundTile(Object object)

Sets the internal paintable sequence background tile paintable. The object passed should be a paintable or be convertible to a paintable via the method ComponentFactory.makePaintable.

The object may be set to null to eliminate background tiling.

Parameters:
object - the internal paintable sequence background tile object

getSequenceBackgroundTile

public final Paintable getSequenceBackgroundTile()
Returns the internal paintable sequence background tile.

Returns:
the internal paintable sequence background tile.

clearSequenceBackgroundTile

public final void clearSequenceBackgroundTile()

Clear the internal paintable sequence background tile.


clearBothSequenceBackgrounds

public final void clearBothSequenceBackgrounds()

Clear the both the internal paintable sequence background paint and the internal paintable sequence background tile.


drawGrid

public void drawGrid(int pixels)

Draws a grid with spacing equal to the given pixels value and color equal to Colors.lightgray.

Does nothing if pixels <= 0.

Parameters:
pixels - the pixel spacing of the grid

drawGrid

public void drawGrid(int pixels,
                     Color color)

Draws a grid with spacing equal to the given pixels value and color equal to the given color.

If the given color is null, it is set to the value Colors.lightgray.

Does nothing if pixels <= 0.

Parameters:
pixels - the pixel spacing of the grid
color - the grid color

setBackground

public final void setBackground(Color background)

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

Parameters:
background - the new background color

setMouseActionAdapter

public final 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

getMouseActionAdapter

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


setKeyActionAdapter

public final 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

getKeyActionAdapter

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


setFocusable

public final void setFocusable(boolean focusable)

Overrides to delegate to the inner panel that is the panel returned by getInnerPanel().


isFocusable

public final boolean isFocusable()

Overrides to delegate to the inner panel that is the panel returned by getInnerPanel().


isRequestFocusEnabled

public final boolean isRequestFocusEnabled()

Overrides to delegate to the inner panel that is the panel returned by getInnerPanel().


requestFocus

public final void requestFocus()

Overrides to delegate to the inner panel that is the panel returned by getInnerPanel().


requestFocusInWindow

public final boolean requestFocusInWindow()

Overrides to delegate to the inner panel that is the panel returned by getInnerPanel().


getPaintableSequence

public final PaintableSequence getPaintableSequence()

Gets the internal PaintableSequence that will be painted after the underlying buffer is painted.

This method enables access to the full functionality of the internal paintable sequence.


setPaintable

public final Paintable setPaintable(int index,
                                    Object o)

Calls the corresponding method on the internal paintable sequence.

Parameters:
index - the position in the sequence
o - the object convert to a paintable to set at the position

setPaintable

public final Paintable setPaintable(Object o,
                                    int index)

Calls the corresponding method on the internal paintable sequence.

Parameters:
o - the object convert to a paintable to set at the position
index - the position in the sequence

getPaintable

public final Paintable getPaintable(int index)

Calls the corresponding method on the internal paintable sequence.

Parameters:
index - the position in the sequence

getIndex

public final int getIndex(Paintable paintable)

Calls the corresponding method on the internal paintable sequence.

Parameters:
paintable - the paintable to find

addPaintable

public final Paintable addPaintable(int index,
                                    Object o)

Calls the corresponding method on the internal paintable sequence.

Parameters:
index - the position in the sequence
o - the object to convert to a paintable to insert at the position

addPaintable

public final Paintable addPaintable(Object o,
                                    int index)

Calls the corresponding method on the internal paintable sequence.

Parameters:
o - the object to convert to a paintable to insert at the position
index - the position in the sequence

addPaintable

public final Paintable addPaintable(Object o)

Calls the corresponding method on the internal paintable sequence.

Parameters:
o - the object to convert to a paintable to insert at the top

addPaintableAtTop

public final Paintable addPaintableAtTop(Object o)

Calls the corresponding method on the internal paintable sequence.

Parameters:
o - the object to convert to a paintable to insert at the top

appendPaintable

public final Paintable appendPaintable(Object o)

Calls the corresponding method on the internal paintable sequence.

Parameters:
o - the object to convert to a paintable to insert at the bottom

setSequence

public final Paintable[] setSequence(Object[] objects)

Calls the corresponding method on the internal paintable sequence.

Parameters:
objects - the array of objects to install

addSequence

public final Paintable[] addSequence(int index,
                                     Object[] objects)

Calls the corresponding method on the internal paintable sequence.

Parameters:
index - the position in the sequence at which to add
objects - the array of objects to add

addSequence

public final Paintable[] addSequence(Object[] objects,
                                     int index)

Calls the corresponding method on the internal paintable sequence.

Parameters:
objects - the array of objects to add
index - the position in the sequence at which to add

addSequence

public final Paintable[] addSequence(Object[] objects)

Calls the corresponding method on the internal paintable sequence.

Parameters:
objects - the array of objects to add at the top

addSequenceAtTop

public final Paintable[] addSequenceAtTop(Object[] objects)

Calls the corresponding method on the internal paintable sequence.

Parameters:
objects - the array of objects to add at the top

appendSequence

public final Paintable[] appendSequence(Object[] objects)

Calls the corresponding method on the internal paintable sequence.

Parameters:
objects - the array of objects to append

removePaintable

public final Paintable removePaintable(int index)

Calls the corresponding method on the internal paintable sequence.

Parameters:
index - the position of the item to remove

removePaintable

public final void removePaintable(Paintable paintable)

Calls the corresponding method on the internal paintable sequence.

Parameters:
paintable - the item to remove

removeSequence

public final Paintable[] removeSequence(int m,
                                        int n)

Calls the corresponding method on the internal paintable sequence.

Parameters:
m - the starting index inclusive
n - the ending index exclusive

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.

As of 2.4.0, this method is called after both the painting of the buffer and the painting of the internal paintable sequence. Given the power inherent in painting both the buffer bitmap and the internal paintable sequence, it is rare that this method will need to be overridden.

Parameters:
g2 - the Graphics2D context for the buffer repaint operation
Since:
1.0.1

SMA_Moved

protected void SMA_Moved(MouseEvent evt)
The method that implements the "Simple Mouse Action" moved action.


SMA_Pressed

protected void SMA_Pressed(MouseEvent evt)
The method that implements the "Simple Mouse Action" pressed action.


SMA_Released

protected void SMA_Released(MouseEvent evt)
The method that implements the "Simple Mouse Action" released action.


SMA_Clicked

protected void SMA_Clicked(MouseEvent evt)
The method that implements the "Simple Mouse Action" clicked action.


SMA_Dragged

protected void SMA_Dragged(MouseEvent evt)
The method that implements the "Simple Mouse Action" dragged action.


SMA_Entered

protected void SMA_Entered(MouseEvent evt)
The method that implements the "Simple Mouse Action" entered panel action.


SMA_Exited

protected void SMA_Exited(MouseEvent evt)
The method that implements the "Simple Mouse Action" exited panel action.


getMouseX

public final int getMouseX()

Gets the current value of the mouse x-position.

Valid only if mouse actions are installed that set this position.


getMouseY

public final int getMouseY()

Gets the current value of the mouse y-position.

Valid only if mouse actions are installed that set this position.


setMousePosition

public final void setMousePosition(MouseEvent evt)

Sets the mouse position from the mouse event.

May be used as a helper method for defining mouse actions. If used while the mouse is moved or dragged then will make getMouseX and getMouseY valid.

Parameters:
evt - a mouse event

setAutoShiftToTop

public final void setAutoShiftToTop(boolean shift)

Sets whether or not a clicked paintable should shift to the top of the paintable sequence.

Parameters:
shift - whether or not to shift a paintable to the top

getAutoShiftToTop

public final boolean getAutoShiftToTop()

Gets whether or not a clicked paintable should shift to the top of the paintable sequence.


installSimpleMouseActions

public void installSimpleMouseActions()

Installs a set of simple mouse actions that by default will permit a user to drag the paintables in the internal paintable sequence.

These actions will only drag while the mouse is in the panel. This avoids dragging a paintable completely out of view. However, if the mouse re-enters the panel, then the paintable will jump to the new mouse position.

These mouse actions respect the decision on whether or not a clicked paintable should shift to the top of the internal paintable sequence.

These mouse actions are just a useful simple default set of actions. The caller can change this behavior by either of two methods:

1. Obtain the mouse action adapter via the method call getMouseActionAdapter() and install actions directly.

2. Define a derived class and override the following seven protected methods:

Then use installSimpleMouseActions() to install the seven mouse actions you have defined.

Technical note: This method call automatically uninstalls any other mouse actions that may have been installed.


installSimpleMouseActions

public void installSimpleMouseActions(boolean shift)

Convenience method that installs the simple mouse actions and sets the auto-shift-to-top parameter at the same time.

Equivalent to:

Parameters:
shift - whether or not to shift a paintable to the top

uninstallAllMouseActions

public final void uninstallAllMouseActions()
Uninstalls all mouse actions that have been attached to the mouse action adapter for this panel.


uninstallAllKeyActions

public final void uninstallAllKeyActions()
Uninstalls all key actions that have been attached to the key action adapter for this panel.