javax.swing

Class JLayeredPane

Implemented Interfaces:
Accessible, ImageObserver, MenuContainer, Serializable
Known Direct Subclasses:
JDesktopPane

public class JLayeredPane
extends JComponent
implements Accessible

A container that adds depth to the usual Container semantics. Each child component of a Layered Pane is placed within one of several layers. JLayeredPane defines a set of standard layers. The pre-defined sets are (in the order from button to top):
DEFAULT_LAYER
PALETTE_LAYER
MODAL_LAYER
POPUP_LAYER
DRAG_LAYER

A child is in exactly one of these layers at any time, though there may be other layers if someone creates them.

You can add a component to a specific layer using the Container.add(Component,Object) method. I.e. layeredPane.add(comp, JLayeredPane.MODAL_LAYER) will add the component comp to the modal layer of layeredPane.

To change the layer of a component that is already a child of a JLayeredPane, use the setLayer(Component,int) method.

The purpose of this class is to translate this view of "layers" into a contiguous array of components: the one held in our ancestor, Container.

There is a precise set of words we will use to refer to numbers within this class:

componentContainer[0 .. component.length)
int

Note: the layer numbering order is the reverse of the component indexing and position order

See Also:
Serialized Form

Nested Class Summary

protected class
JLayeredPane.AccessibleJLayeredPane
Provides accessibility support for JLayeredPane.

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

static Integer
DEFAULT_LAYER
static Integer
DRAG_LAYER
static Integer
FRAME_CONTENT_LAYER
static String
LAYER_PROPERTY
static Integer
MODAL_LAYER
static Integer
PALETTE_LAYER
static Integer
POPUP_LAYER

Fields inherited from class javax.swing.JComponent

TOOL_TIP_TEXT_KEY, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW, accessibleContext, listenerList, ui

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

JLayeredPane()
Creates a new JComponent instance.

Method Summary

protected Hashtable
Integer> getComponentToLayer()
Return a hashtable mapping child components of this container to Integer objects representing the component's layer assignments.
protected void
addImpl(Component comp, Object layerConstraint, int index)
Overrides the default implementation from Container such that layerConstraint is interpreted as an Integer, specifying the layer to which the component will be added (at the bottom position).
AccessibleContext
getAccessibleContext()
Returns the accessible context for this JLayeredPane.
int
getComponentCountInLayer(int layer)
Return the number of components within a layer of this container.
Component[]
getComponentsInLayer(int layer)
Return an array of all components within a layer of this container.
int
getIndexOf(Component c)
Return the index of a component within the underlying (contiguous) array of children.
int
getLayer(Component c)
Looks up the layer a child component is currently assigned to.
static int
getLayer(JComponent comp)
Looks up the layer in the client property with the key LAYER_PROPERTY of comp.
static JLayeredPane
getLayeredPaneAbove(Component comp)
Returns the first JLayeredPane that contains the Component comp or null if comp is not contained in a JLayeredPane.
protected Integer
getObjectForLayer(int layer)
Return an Integer object which holds the same int value as the parameter.
int
getPosition(Component c)
Return the position of a component within its layer.
int
highestLayer()
Return the greatest layer number currently in use, in this container.
protected int
insertIndexForLayer(int layer, int position)
Computes an index at which to request the superclass Container inserts a component, given an abstract layer and position number.
boolean
isOptimizedDrawingEnabled()
Returns false if components in this layered pane can overlap, otherwise true.
int
lowestLayer()
Return the least layer number currently in use, in this container.
void
moveToBack(Component c)
Moves a component to the "back" of its layer.
void
moveToFront(Component c)
Moves a component to the "front" of its layer.
void
paint(Graphics g)
This method is overridden order to provide a reasonable painting mechanism for JLayeredPane.
static void
putLayer(JComponent component, int layer)
Sets the layer property for a JComponent.
void
remove(int index)
Removes a child from this container.
void
removeAll()
Removes all components from this container.
void
setLayer(Component c, int layer)
Set the layer property for a component, within this container.
void
setLayer(Component c, int layer, int position)
Set the layer and position of a component, within this container.
void
setPosition(Component c, int position)
Change the position of a component within its layer.

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, extends EventListener> T[] getListeners, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setNextFocusableComponent, setOpaque, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addNotify, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, extends EventListener> T[] getListeners, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponentZOrder, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paint, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusDownCycle, update, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, extends EventListener> T[] getListeners, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPeer, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFocusable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paint, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFocusable, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, update, validate

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_LAYER

public static final Integer DEFAULT_LAYER

DRAG_LAYER

public static final Integer DRAG_LAYER

FRAME_CONTENT_LAYER

public static final Integer FRAME_CONTENT_LAYER

LAYER_PROPERTY

public static final String LAYER_PROPERTY
Field Value:
"layeredContainerLayer"

MODAL_LAYER

public static final Integer MODAL_LAYER

PALETTE_LAYER

public static final Integer PALETTE_LAYER

POPUP_LAYER

public static final Integer POPUP_LAYER

Constructor Details

JLayeredPane

public JLayeredPane()
Creates a new JComponent instance.

Method Details

Integer> getComponentToLayer

protected HashtableInteger> getComponentToLayer()
Return a hashtable mapping child components of this container to Integer objects representing the component's layer assignments.

addImpl

protected void addImpl(Component comp,
                       Object layerConstraint,
                       int index)
Overrides the default implementation from Container such that layerConstraint is interpreted as an Integer, specifying the layer to which the component will be added (at the bottom position). The argument index specifies the position within the layer at which the component should be added, where 0 is the top position greater values specify positions below that and -1 specifies the bottom position.
Overrides:
addImpl in interface Container
Parameters:
comp - the component to add
layerConstraint - an integer specifying the layer to add the component to
index - the position within the layer

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns the accessible context for this JLayeredPane.
Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in interface JComponent
Returns:
the accessible context for this JLayeredPane

getComponentCountInLayer

public int getComponentCountInLayer(int layer)
Return the number of components within a layer of this container.
Parameters:
layer - the layer count components in
Returns:
the number of components in the layer

getComponentsInLayer

public Component[] getComponentsInLayer(int layer)
Return an array of all components within a layer of this container. Components are ordered front-to-back, with the "front" element (which draws last) at position 0 of the returned array.
Parameters:
layer - the layer to return components from
Returns:
the components in the layer

getIndexOf

public int getIndexOf(Component c)
Return the index of a component within the underlying (contiguous) array of children. This is a "raw" number which does not represent the child's position in a layer, but rather its position in the logical drawing order of all children of the container.
Parameters:
c - the component to look up.
Returns:
the external index of the component or -1 if c is not a child of this layered pane

getLayer

public int getLayer(Component c)
Looks up the layer a child component is currently assigned to. If c is an instance of JComponent, then the layer is fetched from the client property with the key LAYER_PROPERTY. Otherwise it is looked up in an internal hashtable that maps non-JComponent components to layers. If the components cannot be found in either way, the DEFAULT_LAYER is returned.
Parameters:
c - the component to look up.
Returns:
the layer the component is currently assigned to; if the component is not in this layered pane, then 0 (DEFAULT_LAYER) is returned

getLayer

public static int getLayer(JComponent comp)
Looks up the layer in the client property with the key LAYER_PROPERTY of comp. If no such property can be found, we return 0 (DEFAULT_LAYER).
Parameters:
comp - the component for which the layer is looked up
Returns:
the layer of comp as stored in the corresponding client property, or 0 if there is no such property

getLayeredPaneAbove

public static JLayeredPane getLayeredPaneAbove(Component comp)
Returns the first JLayeredPane that contains the Component comp or null if comp is not contained in a JLayeredPane.
Parameters:
comp - the component for which we are searching the JLayeredPane ancestor
Returns:
the first JLayeredPane that contains the Component comp or null if comp is not contained in a JLayeredPane

getObjectForLayer

protected Integer getObjectForLayer(int layer)
Return an Integer object which holds the same int value as the parameter. This is strictly an optimization to minimize the number of identical Integer objects which we allocate.
Parameters:
layer - the layer number as an int.
Returns:
the layer number as an Integer, possibly shared.

getPosition

public int getPosition(Component c)
Return the position of a component within its layer. Positions are assigned from the "front" (position 0) to the "back" (position N-1), and drawn from the back towards the front.
Parameters:
c - the component to get the position of
Returns:
the position of c within its layer or -1 if c is not a child of this layered pane

highestLayer

public int highestLayer()
Return the greatest layer number currently in use, in this container. This number may legally be positive or negative.
Returns:
the highest layer number
See Also:
lowestLayer()

insertIndexForLayer

protected int insertIndexForLayer(int layer,
                                  int position)
Computes an index at which to request the superclass Container inserts a component, given an abstract layer and position number.
Parameters:
layer - the layer in which to insert a component.
position - the position in the layer at which to insert a component.
Returns:
the index at which to insert the component.

isOptimizedDrawingEnabled

public boolean isOptimizedDrawingEnabled()
Returns false if components in this layered pane can overlap, otherwise true.
Overrides:
isOptimizedDrawingEnabled in interface JComponent
Returns:
false if components in this layered pane can overlap, otherwise true

lowestLayer

public int lowestLayer()
Return the least layer number currently in use, in this container. This number may legally be positive or negative.
Returns:
the least layer number

moveToBack

public void moveToBack(Component c)
Moves a component to the "back" of its layer. The "back" is a synonym for position N-1 (also known as position -1), where N is the size of the layer.

The "back" of a layer is the first position drawn, so the component at the "back" is usually the component which is occluded by the most other components in its layer.

Parameters:
c - the component to move to the back of its layer.

moveToFront

public void moveToFront(Component c)
Moves a component to the "front" of its layer. The "front" is a synonym for position 0, which is also the last position drawn in each layer, so is usually the component which occludes the most other components in its layer.
Parameters:
c - the component to move to the front of its layer

paint

public void paint(Graphics g)
This method is overridden order to provide a reasonable painting mechanism for JLayeredPane. This is necessary since JLayeredPane's do not have an own UI delegate. Basically this method clears the background for the JLayeredPane and then calls super.paint(g).
Overrides:
paint in interface JComponent
Parameters:
g - the graphics context to use

putLayer

public static void putLayer(JComponent component,
                            int layer)
Sets the layer property for a JComponent.
Parameters:
component - the component for which to set the layer
layer - the layer property to set

remove

public void remove(int index)
Removes a child from this container. The child is specified by index. After removal, the child no longer occupies a layer.
Overrides:
remove in interface Container
Parameters:
index - the index of the child component to remove.

removeAll

public void removeAll()
Removes all components from this container.
Overrides:
removeAll in interface Container
Since:
1.5

setLayer

public void setLayer(Component c,
                     int layer)
Set the layer property for a component, within this container. The component will be implicitly mapped to the bottom-most position in the layer, but only if added after calling this method.

Read that carefully: this method should be called before the component is added to the container.

Parameters:
c - the component to set the layer property for.
layer - the layer number to assign to the component.

setLayer

public void setLayer(Component c,
                     int layer,
                     int position)
Set the layer and position of a component, within this container.
Parameters:
c - the child component to set the layer property for.
layer - the layer number to assign to the component.
position - the position number to assign to the component.

setPosition

public void setPosition(Component c,
                        int position)
Change the position of a component within its layer. Positions are assigned from the "front" (position 0) to the "back" (position N-1), and drawn from the back towards the front.
Parameters:
c - the component to change the position of
position - the position to assign the component to

JLayeredPane.java -- Copyright (C) 2002, 2004 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.