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

Since:
1.0
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.
 
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.
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.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, 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 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[] clearSequence()
          Clears the internal paintable sequence; 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.
 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.
 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 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 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.
 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.
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, addObject, addObject, addObject, addObject, dataMalformed, endAlert, frame, frame, frame, frame, frame, frame, generalDialog, generalDialog, generalDialog, generalDialog, getCodec, getDefaultViewState, getDefaultViewStates, getDisplayables, getViewState, getViewStates, makeComponent, OKCancelDialog, OKCancelDialog, OKDialog, OKDialog, refreshComponent, remove, remove, removeAll, reset, setCodec, setDeepBackground, setDeepBackground, setDefaultViewState, setDefaultViewStates, setEnabled, setViewState, setViewStates, 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.


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

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.


getBuffer

public BufferedImage getBuffer()

Returns the internal buffered image for this panel.


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

Fills this buffered panel with its background color or 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 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.


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.

The panel is only filled with the background paint if the method clearPanel() 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 this decision explicitly.

Parameters:
background - the new background color or Paint

getBufferBackground

public Paint getBufferBackground()

Returns the background color or Paint for this buffered panel.


drawGrid

public void drawGrid(int pixels)

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

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.

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

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

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

getBufferWidth

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


getBufferHeight

public int getBufferHeight()
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

getMouseActionAdapter

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


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

getKeyActionAdapter

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


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.


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.

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

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.

Since:
1.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 int getMouseX()

Gets the current value of the mouse x-position.

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


getMouseY

public int getMouseY()

Gets the current value of the mouse y-position.

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


setMousePosition

public 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 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 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 void uninstallAllMouseActions()
Uninstalls all mouse actions that have been attached to the mouse action adapter for this panel.


uninstallAllKeyActions

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