*
JLayeredPane adds depth to a JFC/Swing container,
* allowing components to overlap each other when needed.
* An Integer object specifies each component's depth in the
* container, where higher-numbered components sit "on top" of other
* components.
* For task-oriented documentation and examples of using layered panes see
* How to Use a Layered Pane,
* a section in The Java Tutorial.
*
* |
*
|
*
JLayeredPane divides the depth-range
* into several different layers. Putting a component into one of those
* layers makes it easy to ensure that components overlap properly,
* without having to worry about specifying numbers for specific depths:
* JLayeredPane methods moveToFront(Component),
* moveToBack(Component) and setPosition can be used
* to reposition a component within its layer. The setLayer method
* can also be used to change the component's current layer.
*
* JLayeredPane manages its list of children like
* Container, but allows for the definition of a several
* layers within itself. Children in the same layer are managed exactly
* like the normal Container object,
* with the added feature that when children components overlap, children
* in higher layers display above the children in lower layers.
*
* Each layer is a distinct integer number. The layer attribute can be set
* on a Component by passing an Integer
* object during the add call.
For example:
*
* layeredPane.add(child, JLayeredPane.DEFAULT_LAYER); * or * layeredPane.add(child, new Integer(10)); ** The layer attribute can also be set on a Component by calling
* layeredPaneParent.setLayer(child, 10)* on the
JLayeredPane that is the parent of component. The layer
* should be set before adding the child to the parent.
* * Higher number layers display above lower number layers. So, using * numbers for the layers and letters for individual components, a * representative list order would look like this:
* 5a, 5b, 5c, 2a, 2b, 2c, 1a* where the leftmost components are closest to the top of the display. *
* A component can be moved to the top or bottom position within its
* layer by calling moveToFront or moveToBack.
*
* The position of a component within a layer can also be specified directly. * Valid positions range from 0 up to one less than the number of * components in that layer. A value of -1 indicates the bottommost * position. A value of 0 indicates the topmost position. Unlike layer * numbers, higher position values are lower in the display. *
* Note: This sequence (defined by java.awt.Container) is the reverse * of the layer numbering sequence. Usually though, you will use* Here are some examples using the method add(Component, layer, position): * Calling add(5x, 5, -1) results in:moveToFront, *moveToBack, andsetLayer. *
* 5a, 5b, 5c, 5x, 2a, 2b, 2c, 1a* * Calling add(5z, 5, 2) results in:
* 5a, 5b, 5z, 5c, 5x, 2a, 2b, 2c, 1a* * Calling add(3a, 3, 7) results in:
* 5a, 5b, 5z, 5c, 5x, 3a, 2a, 2b, 2c, 1a* * Using normal paint/event mechanics results in 1a appearing at the bottom * and 5a being above all other components. *
* Note: that these layers are simply a logical construct and LayoutManagers * will affect all child components of this container without regard for * layer settings. *
* Warning: Swing is not thread safe. For more * information see Swing's Threading * Policy. *
* Warning:
* Serialized objects of this class will not be compatible with
* future Swing releases. The current serialization support is
* appropriate for short term storage or RMI between applications running
* the same version of Swing. As of 1.4, support for long term storage
* of all JavaBeans™
* has been added to the
* Note: Position numbering is defined by java.awt.Container, and
* is the opposite of layer numbering. Lower position numbers are closer
* to the top (0 is topmost), and higher position numbers are closer to
* the bottom.
*
* @param c the Component to move
* @param position an int in the range -1..N-1, where N is the number of
* components in the component's current layer
*/
public void setPosition(Component c, int position) {
setLayer(c, getLayer(c), position);
}
/**
* Get the relative position of the component within its layer.
*
* @param c the Component to check
* @return an int giving the component's position, where 0 is the
* topmost position and the highest index value = the count
* count of components at that layer, minus 1
*
* @see #getComponentCountInLayer
*/
public int getPosition(Component c) {
int i, startLayer, curLayer, startLocation, pos = 0;
getComponentCount();
startLocation = getIndexOf(c);
if(startLocation == -1)
return -1;
startLayer = getLayer(c);
for(i = startLocation - 1; i >= 0; i--) {
curLayer = getLayer(getComponent(i));
if(curLayer == startLayer)
pos++;
else
return pos;
}
return pos;
}
/** Returns the highest layer value from all current children.
* Returns 0 if there are no children.
*
* @return an int indicating the layer of the topmost component in the
* pane, or zero if there are no children
*/
public int highestLayer() {
if(getComponentCount() > 0)
return getLayer(getComponent(0));
return 0;
}
/** Returns the lowest layer value from all current children.
* Returns 0 if there are no children.
*
* @return an int indicating the layer of the bottommost component in the
* pane, or zero if there are no children
*/
public int lowestLayer() {
int count = getComponentCount();
if(count > 0)
return getLayer(getComponent(count-1));
return 0;
}
/**
* Returns the number of children currently in the specified layer.
*
* @param layer an int specifying the layer to check
* @return an int specifying the number of components in that layer
*/
public int getComponentCountInLayer(int layer) {
int i, count, curLayer;
int layerCount = 0;
count = getComponentCount();
for(i = 0; i < count; i++) {
curLayer = getLayer(getComponent(i));
if(curLayer == layer) {
layerCount++;
/// Short circut the counting when we have them all
} else if(layerCount > 0 || curLayer < layer) {
break;
}
}
return layerCount;
}
/**
* Returns an array of the components in the specified layer.
*
* @param layer an int specifying the layer to check
* @return an array of Components contained in that layer
*/
public Component[] getComponentsInLayer(int layer) {
int i, count, curLayer;
int layerCount = 0;
Component[] results;
results = new Component[getComponentCountInLayer(layer)];
count = getComponentCount();
for(i = 0; i < count; i++) {
curLayer = getLayer(getComponent(i));
if(curLayer == layer) {
results[layerCount++] = getComponent(i);
/// Short circut the counting when we have them all
} else if(layerCount > 0 || curLayer < layer) {
break;
}
}
return results;
}
/**
* Paints this JLayeredPane within the specified graphics context.
*
* @param g the Graphics context within which to paint
*/
public void paint(Graphics g) {
if(isOpaque()) {
Rectangle r = g.getClipBounds();
Color c = getBackground();
if(c == null)
c = Color.lightGray;
g.setColor(c);
if (r != null) {
g.fillRect(r.x, r.y, r.width, r.height);
}
else {
g.fillRect(0, 0, getWidth(), getHeight());
}
}
super.paint(g);
}
//////////////////////////////////////////////////////////////////////////////
//// Implementation Details
//////////////////////////////////////////////////////////////////////////////
/**
* Returns the hashtable that maps components to layers.
*
* @return the Hashtable used to map components to their layers
*/
protected Hashtable
* Warning:
* Serialized objects of this class will not be compatible with
* future Swing releases. The current serialization support is
* appropriate for short term storage or RMI between applications running
* the same version of Swing. As of 1.4, support for long term storage
* of all JavaBeans™
* has been added to the java.beans package.
* Please see {@link java.beans.XMLEncoder}.
*
* @author David Kloba
* @since 1.2
*/
@JavaBean(defaultProperty = "accessibleContext")
@SuppressWarnings("serial")
public class JLayeredPane extends JComponent implements Accessible {
/// Watch the values in getObjectForLayer()
/** Convenience object defining the Default layer. Equivalent to new Integer(0).*/
public final static Integer DEFAULT_LAYER = 0;
/** Convenience object defining the Palette layer. Equivalent to new Integer(100).*/
public final static Integer PALETTE_LAYER = 100;
/** Convenience object defining the Modal layer. Equivalent to new Integer(200).*/
public final static Integer MODAL_LAYER = 200;
/** Convenience object defining the Popup layer. Equivalent to new Integer(300).*/
public final static Integer POPUP_LAYER = 300;
/** Convenience object defining the Drag layer. Equivalent to new Integer(400).*/
public final static Integer DRAG_LAYER = 400;
/** Convenience object defining the Frame Content layer.
* This layer is normally only use to position the contentPane and menuBar
* components of JFrame.
* Equivalent to new Integer(-30000).
* @see JFrame
*/
public final static Integer FRAME_CONTENT_LAYER = new Integer(-30000);
/** Bound property */
public final static String LAYER_PROPERTY = "layeredContainerLayer";
// Hashtable to store layer values for non-JComponent components
private Hashtableposition within its current layer,
* where 0 is the topmost position within the layer and -1 is the bottommost
* position.
* null.
*
* @return a string representation of this JLayeredPane.
*/
protected String paramString() {
String optimizedDrawingPossibleString = (optimizedDrawingPossible ?
"true" : "false");
return super.paramString() +
",optimizedDrawingPossible=" + optimizedDrawingPossibleString;
}
/////////////////
// Accessibility support
////////////////
/**
* Gets the AccessibleContext associated with this JLayeredPane.
* For layered panes, the AccessibleContext takes the form of an
* AccessibleJLayeredPane.
* A new AccessibleJLayeredPane instance is created if necessary.
*
* @return an AccessibleJLayeredPane that serves as the
* AccessibleContext of this JLayeredPane
*/
@BeanProperty(bound = false)
public AccessibleContext getAccessibleContext() {
if (accessibleContext == null) {
accessibleContext = new AccessibleJLayeredPane();
}
return accessibleContext;
}
/**
* This class implements accessibility support for the
* JLayeredPane class. It provides an implementation of the
* Java Accessibility API appropriate to layered pane user-interface
* elements.
* java.beans package.
* Please see {@link java.beans.XMLEncoder}.
*/
@SuppressWarnings("serial")
protected class AccessibleJLayeredPane extends AccessibleJComponent {
/**
* Get the role of this object.
*
* @return an instance of AccessibleRole describing the role of the
* object
* @see AccessibleRole
*/
public AccessibleRole getAccessibleRole() {
return AccessibleRole.LAYERED_PANE;
}
}
}