BufferedPanel (JPT 2.6.0 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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,

edu.neu.ccs.gui Class BufferedPanel

edu.neu.ccs.gui
Class BufferedPanel