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:

• Paint the buffer
• Paint the internal paintable sequence
• Call the paintOver method for further graphics

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:

• Paint the buffer
• Paint the background paint of the internal paintable sequence
• Paint the background tile of the internal paintable sequence
• Paint the paintables of the internal paintable sequence
• Call the paintOver method for further graphics

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:

• Added the method makeSnapshot that will construct a new BufferedImage that is the same size as this panel and that captures the current visual state of this panel.

• Changed the method name of setBackgroundTile to setSequenceBackgroundTile to be consistent with the naming conventions of the related methods.
• Added final to methods that should not be overridden.

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:

• SMA_Moved(MouseEvent evt)
• SMA_Pressed(MouseEvent evt)
• SMA_Released(MouseEvent evt)
• SMA_Clicked(MouseEvent evt)
• SMA_Dragged(MouseEvent evt)
• SMA_Entered(MouseEvent evt)
• SMA_Exited(MouseEvent evt)

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:

• installSimpleMouseActions()
• setAutoShiftToTop(shift)

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.