javax.swing
Class JLayeredPane

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by javax.swing.JLayeredPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
Direct Known 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
The layer where most of the normal components are placed. This is the bottommost layer.
PALETTE_LAYER
Palette windows are placed in this layer.
MODAL_LAYER
The layer where internal modal dialog windows are placed.
POPUP_LAYER
The layer for popup menus
DRAG_LAYER
Components that are beeing dragged are temporarily placed in this 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:

Component Index:
An offset into the component array held in our ancestor, Container, from [0 .. component.length). The drawing rule with indices is that 0 is drawn last.
Layer Number:
A general int specifying a layer within this component. Negative numbers are drawn first, then layer 0, then positive numbered layers, in ascending order.
Position:
An offset into a layer's "logical drawing order". Layer position 0 is drawn last. Layer position -1 is a synonym for the first layer position (the logical "bottom").

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
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
JLayeredPane()
           
 
Method Summary
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.
protected  Hashtable<Component,Integer> getComponentToLayer()
          Return a hashtable mapping child components of this container to Integer objects representing the component's layer assignments.
 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, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, 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, isPaintingTile, isRequestFocusEnabled, isValidateRoot, 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, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, 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, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, 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, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, 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, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

LAYER_PROPERTY

public static final String LAYER_PROPERTY
See Also:
Constant Field Values

FRAME_CONTENT_LAYER

public static final Integer FRAME_CONTENT_LAYER

DEFAULT_LAYER

public static final Integer DEFAULT_LAYER

PALETTE_LAYER

public static final Integer PALETTE_LAYER

MODAL_LAYER

public static final Integer MODAL_LAYER

POPUP_LAYER

public static final Integer POPUP_LAYER

DRAG_LAYER

public static final Integer DRAG_LAYER
Constructor Detail

JLayeredPane

public JLayeredPane()
Method Detail

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

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

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
See Also:
highestLayer()

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
See Also:
moveToBack(java.awt.Component)

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.
See Also:
moveToFront(java.awt.Component)

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
See Also:
setPosition(java.awt.Component, int)

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
See Also:
getPosition(java.awt.Component)

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

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

getComponentToLayer

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


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

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.

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.

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 class Container
Parameters:
index - the index of the child component to remove.

removeAll

public void removeAll()
Removes all components from this container.

Overrides:
removeAll in class 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.

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 class Container
Parameters:
comp - the component to add
layerConstraint - an integer specifying the layer to add the component to
index - the position within the layer

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

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns the accessible context for this JLayeredPane.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
the accessible context for this JLayeredPane

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 class JComponent
Parameters:
g - the graphics context to use
See Also:
JComponent.paintImmediately(Rectangle)

isOptimizedDrawingEnabled

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

Overrides:
isOptimizedDrawingEnabled in class JComponent
Returns:
false if components in this layered pane can overlap, otherwise true