1 /* JLayeredPane.java --
2 Copyright (C) 2002, 2004 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
41 import java
.awt
.Color
;
42 import java
.awt
.Component
;
43 import java
.awt
.Container
;
44 import java
.awt
.Graphics
;
45 import java
.awt
.Rectangle
;
46 import java
.util
.Hashtable
;
48 import javax
.accessibility
.Accessible
;
49 import javax
.accessibility
.AccessibleContext
;
50 import javax
.accessibility
.AccessibleRole
;
53 * A container that adds depth to the usual <code>Container</code> semantics.
54 * Each child component of a <code>Layered Pane</code> is placed within one
55 * of several layers. <code>JLayeredPane</code> defines a set of standard
56 * layers. The pre-defined sets are (in the order from button to top):
59 * <dt>{@link #DEFAULT_LAYER}</dt>
60 * <dd>The layer where most of the normal components are placed. This
61 * is the bottommost layer.</dd>
63 * <dt>{@link #PALETTE_LAYER}</dt>
64 * <dd>Palette windows are placed in this layer.</dd>
66 * <dt>{@link #MODAL_LAYER}</dt>
67 * <dd>The layer where internal modal dialog windows are placed.</dd>
69 * <dt>{@link #POPUP_LAYER}</dt>
70 * <dd>The layer for popup menus</dd>
72 * <dt>{@link #DRAG_LAYER}</dt>
73 * <dd>Components that are beeing dragged are temporarily placed in
77 * <p>A child is in exactly one of these layers at any time, though there may
78 * be other layers if someone creates them.</p>
80 * <p>You can add a component to a specific layer using the
81 * {@link Container#add(Component, Object)} method. I.e.
82 * <code>layeredPane.add(comp, JLayeredPane.MODAL_LAYER)</code> will add the
83 * component <code>comp</code> to the modal layer of <code>layeredPane</code>.
86 * <p>To change the layer of a component that is already a child of
87 * a <code>JLayeredPane</code>, use the {@link #setLayer(Component, int)}
90 * <p>The purpose of this class is to translate this view of "layers" into a
91 * contiguous array of components: the one held in our ancestor,
92 * {@link java.awt.Container}.</p>
94 * <p>There is a precise set of words we will use to refer to numbers within
98 * <dt>Component Index:</dt>
99 * <dd>An offset into the <code>component</code> array held in our ancestor,
100 * {@link java.awt.Container}, from <code>[0 .. component.length)</code>. The drawing
101 * rule with indices is that 0 is drawn last.</dd>
103 * <dt>Layer Number:</dt>
104 * <dd>A general <code>int</code> specifying a layer within this component. Negative
105 * numbers are drawn first, then layer 0, then positive numbered layers, in
106 * ascending order.</dd>
109 * <dd>An offset into a layer's "logical drawing order". Layer position 0
110 * is drawn last. Layer position -1 is a synonym for the first layer
111 * position (the logical "bottom").</dd>
114 * <p><b>Note:</b> the layer numbering order is the <em>reverse</em> of the
115 * component indexing and position order</p>
117 * @author Graydon Hoare (graydon@redhat.com)
118 * @author Roman Kennke (kennke@aicas.com)
120 public class JLayeredPane
extends JComponent
implements Accessible
124 * Provides accessibility support for <code>JLayeredPane</code>.
126 protected class AccessibleJLayeredPane
extends AccessibleJComponent
129 * Creates a new instance of <code>AccessibleJLayeredPane</code>.
131 protected AccessibleJLayeredPane()
133 // Nothing to do here.
137 * Returns the accessble role of <code>JLayeredPane</code>,
138 * {@link AccessibleRole#LAYERED_PANE}.
140 public AccessibleRole
getAccessibleRole()
142 return AccessibleRole
.LAYERED_PANE
;
146 private static final long serialVersionUID
= 5534920399324590459L;
148 public static final String LAYER_PROPERTY
= "layeredContainerLayer";
150 public static final Integer FRAME_CONTENT_LAYER
= new Integer (-30000);
152 public static final Integer DEFAULT_LAYER
= new Integer (0);
153 public static final Integer PALETTE_LAYER
= new Integer (100);
154 public static final Integer MODAL_LAYER
= new Integer (200);
155 public static final Integer POPUP_LAYER
= new Integer (300);
156 public static final Integer DRAG_LAYER
= new Integer (400);
158 private Hashtable componentToLayer
; // Component -> Layer Number (Integer)
160 public JLayeredPane()
162 componentToLayer
= new Hashtable ();
167 * Looks up the layer a child component is currently assigned to.
169 * If <code>c</code> is an instance of {@link JComponent}, then the layer
170 * is fetched from the client property with the key {@link #LAYER_PROPERTY}.
171 * Otherwise it is looked up in an internal hashtable that maps
172 * non-JComponent components to layers. If the components cannot be found
173 * in either way, the {@link #DEFAULT_LAYER} is returned.
175 * @param c the component to look up.
177 * @return the layer the component is currently assigned to; if the component
178 * is not in this layered pane, then 0 (DEFAULT_LAYER) is returned
180 public int getLayer(Component c
)
183 if (c
instanceof JComponent
)
185 JComponent jc
= (JComponent
) c
;
186 layerObj
= (Integer
) jc
.getClientProperty(LAYER_PROPERTY
);
189 layerObj
= (Integer
) componentToLayer
.get(c
);
191 if (layerObj
== null)
192 layerObj
= DEFAULT_LAYER
;
194 return layerObj
.intValue();
198 * Looks up the layer in the client property with the key
199 * {@link #LAYER_PROPERTY} of <code>comp</code>. If no such property can be
200 * found, we return <code>0</code> ({@link #DEFAULT_LAYER}).
202 * @param comp the component for which the layer is looked up
204 * @return the layer of <code>comp</code> as stored in the corresponding
205 * client property, or <code>0</code> if there is no such property
207 public static int getLayer(JComponent comp
)
209 Integer layerObj
= (Integer
) comp
.getClientProperty(LAYER_PROPERTY
);
210 if (layerObj
== null)
211 layerObj
= DEFAULT_LAYER
;
212 return layerObj
.intValue();
216 * Returns the first JLayeredPane that contains the Component
217 * <code>comp</code> or <code>null</code> if <code>comp</code> is
218 * not contained in a JLayeredPane.
220 * @param comp the component for which we are searching the JLayeredPane
223 * @return the first JLayeredPane that contains the Component
224 * <code>comp</code> or <code>null</code> if <code>comp</code> is
225 * not contained in a JLayeredPane
227 public static JLayeredPane
getLayeredPaneAbove(Component comp
)
229 JLayeredPane lp
= (JLayeredPane
) SwingUtilities
.getAncestorOfClass
230 (JLayeredPane
.class, comp
);
235 * Return the greatest layer number currently in use, in this container.
236 * This number may legally be positive <em>or</em> negative.
238 * @return the highest layer number
240 * @see #lowestLayer()
242 public int highestLayer()
244 Component
[] components
= getComponents();
246 if (components
.length
== 0)
250 highest
= Integer
.MIN_VALUE
;
251 for (int i
= 0; i
< components
.length
; i
++)
252 highest
= Math
.max(highest
, getLayer(components
[i
]));
258 * Return the least layer number currently in use, in this container.
259 * This number may legally be positive <em>or</em> negative.
261 * @return the least layer number
263 * @see #highestLayer()
265 public int lowestLayer()
267 Component
[] components
= getComponents();
269 if (components
.length
== 0)
273 lowest
= Integer
.MAX_VALUE
;
274 for (int i
= 0; i
< components
.length
; i
++)
275 lowest
= Math
.max(lowest
, getLayer(components
[i
]));
281 * Moves a component to the "front" of its layer. The "front" is a
282 * synonym for position 0, which is also the last position drawn in each
283 * layer, so is usually the component which occludes the most other
284 * components in its layer.
286 * @param c the component to move to the front of its layer
290 public void moveToFront(Component c
)
296 * <p>Moves a component to the "back" of its layer. The "back" is a
297 * synonym for position N-1 (also known as position -1), where N is the
298 * size of the layer.</p>
300 * <p>The "back" of a layer is the first position drawn, so the component at
301 * the "back" is usually the component which is occluded by the most
302 * other components in its layer.</p>
304 * @param c the component to move to the back of its layer.
308 public void moveToBack(Component c
)
314 * Return the position of a component within its layer. Positions are assigned
315 * from the "front" (position 0) to the "back" (position N-1), and drawn from
316 * the back towards the front.
318 * @param c the component to get the position of
320 * @return the position of <code>c</code> within its layer or -1 if
321 * <code>c</code> is not a child of this layered pane
325 public int getPosition(Component c
)
328 int index
= getIndexOf(c
);
329 Component
[] components
= getComponents();
330 int layer
= getLayer(c
);
333 for (int i
= index
; i
>= 0; --i
)
335 if (layer
== getLayer(components
[i
]))
345 * Change the position of a component within its layer. Positions are assigned
346 * from the "front" (position 0) to the "back" (position N-1), and drawn from
347 * the back towards the front.
349 * @param c the component to change the position of
350 * @param position the position to assign the component to
354 public void setPosition(Component c
, int position
)
356 int layer
= getLayer(c
);
357 int index
= insertIndexForLayer(layer
, position
);
358 setComponentZOrder(c
, index
);
362 * Return an array of all components within a layer of this
363 * container. Components are ordered front-to-back, with the "front"
364 * element (which draws last) at position 0 of the returned array.
366 * @param layer the layer to return components from
368 * @return the components in the layer
370 public Component
[] getComponentsInLayer(int layer
)
372 Component
[] inLayer
= new Component
[getComponentCountInLayer(layer
)];
373 Component
[] components
= getComponents();
375 for (int i
= 0; i
< components
.length
; ++i
)
377 if (layer
== getLayer(components
[i
]))
379 inLayer
[j
] = components
[i
];
387 * Return the number of components within a layer of this
390 * @param layer the layer count components in
392 * @return the number of components in the layer
394 public int getComponentCountInLayer(int layer
)
396 Component
[] components
= getComponents();
398 for (int i
= components
.length
- 1; i
>= 0; --i
)
400 if (getLayer(components
[i
]) == layer
)
407 * Return a hashtable mapping child components of this container to
408 * Integer objects representing the component's layer assignments.
410 protected Hashtable
getComponentToLayer()
412 return componentToLayer
;
416 * Return the index of a component within the underlying (contiguous)
417 * array of children. This is a "raw" number which does not represent the
418 * child's position in a layer, but rather its position in the logical
419 * drawing order of all children of the container.
421 * @param c the component to look up.
423 * @return the external index of the component or <code>-1</code> if
424 * <code>c</code> is not a child of this layered pane
426 public int getIndexOf(Component c
)
428 return getComponentZOrder(c
);
432 * Return an Integer object which holds the same int value as the
433 * parameter. This is strictly an optimization to minimize the number of
434 * identical Integer objects which we allocate.
436 * @param layer the layer number as an int.
438 * @return the layer number as an Integer, possibly shared.
440 protected Integer
getObjectForLayer(int layer
)
445 return FRAME_CONTENT_LAYER
;
448 return DEFAULT_LAYER
;
451 return PALETTE_LAYER
;
466 return new Integer(layer
);
470 * Computes an index at which to request the superclass {@link
471 * java.awt.Container} inserts a component, given an abstract layer and
474 * @param layer the layer in which to insert a component.
475 * @param position the position in the layer at which to insert a component.
477 * @return the index at which to insert the component.
479 protected int insertIndexForLayer(int layer
, int position
)
481 // position < 0 means insert at greatest position within layer.
483 position
= Integer
.MAX_VALUE
;
485 Component
[] components
= getComponents();
488 // Try to find the start index of the specified layer.
490 for (int i
= 0; i
< components
.length
; i
++)
492 int l
= getLayer(components
[i
]);
495 // If we are in the layer we look for, try to find the position.
504 // No need to look further if the layer at i is smaller than layer.
512 * Removes a child from this container. The child is specified by
513 * index. After removal, the child no longer occupies a layer.
515 * @param index the index of the child component to remove.
517 public void remove(int index
)
519 Component c
= getComponent(index
);
520 if (! (c
instanceof JComponent
))
521 componentToLayer
.remove(c
);
526 * Removes all components from this container.
530 public void removeAll()
532 componentToLayer
.clear();
537 * <p>Set the layer property for a component, within this container. The
538 * component will be implicitly mapped to the bottom-most position in the
539 * layer, but only if added <em>after</em> calling this method.</p>
541 * <p>Read that carefully: this method should be called <em>before</em> the
542 * component is added to the container.</p>
544 * @param c the component to set the layer property for.
545 * @param layer the layer number to assign to the component.
547 public void setLayer(Component c
, int layer
)
549 setLayer(c
, layer
, -1);
553 * Set the layer and position of a component, within this container.
555 * @param c the child component to set the layer property for.
556 * @param layer the layer number to assign to the component.
557 * @param position the position number to assign to the component.
559 public void setLayer(Component c
, int layer
, int position
)
561 Integer layerObj
= getObjectForLayer(layer
);
562 if (c
instanceof JComponent
)
564 JComponent jc
= (JComponent
) c
;
565 jc
.putClientProperty(LAYER_PROPERTY
, layerObj
);
568 componentToLayer
.put (c
, layerObj
);
570 // Set position only of component is already added to this layered pane.
571 if (getIndexOf(c
) != -1)
572 setPosition(c
, position
);
576 * Overrides the default implementation from {@link java.awt.Container}
577 * such that <code>layerConstraint</code> is interpreted as an {@link
578 * Integer}, specifying the layer to which the component will be added
579 * (at the bottom position).
581 * The argument <code>index</code> specifies the position within the layer
582 * at which the component should be added, where <code>0</code> is the top
583 * position greater values specify positions below that and <code>-1</code>
584 * specifies the bottom position.
586 * @param comp the component to add
587 * @param layerConstraint an integer specifying the layer to add the
589 * @param index the position within the layer
591 protected void addImpl(Component comp
, Object layerConstraint
, int index
)
594 if (layerConstraint
!= null && layerConstraint
instanceof Integer
)
595 layer
= ((Integer
) layerConstraint
).intValue();
597 layer
= getLayer(comp
);
599 int newIdx
= insertIndexForLayer(layer
, index
);
600 setLayer(comp
, layer
);
601 super.addImpl(comp
, layerConstraint
, newIdx
);
602 repaint(comp
.getX(), comp
.getY(), comp
.getWidth(), comp
.getHeight());
606 * Sets the layer property for a JComponent.
608 * @param component the component for which to set the layer
609 * @param layer the layer property to set
611 public static void putLayer(JComponent component
, int layer
)
613 component
.putClientProperty(LAYER_PROPERTY
, new Integer(layer
));
617 * Returns the accessible context for this <code>JLayeredPane</code>.
619 * @return the accessible context for this <code>JLayeredPane</code>
621 public AccessibleContext
getAccessibleContext()
623 if (accessibleContext
== null)
624 accessibleContext
= new AccessibleJLayeredPane();
625 return accessibleContext
;
629 * This method is overridden order to provide a reasonable painting
630 * mechanism for <code>JLayeredPane</code>. This is necessary since
631 * <code>JLayeredPane</code>'s do not have an own UI delegate.
633 * Basically this method clears the background for the
634 * <code>JLayeredPane</code> and then calls <code>super.paint(g)</code>.
636 * @param g the graphics context to use
638 public void paint(Graphics g
)
642 Color oldColor
= g
.getColor();
643 Rectangle clip
= g
.getClipBounds();
644 g
.setColor(getBackground());
645 g
.fillRect(clip
.x
, clip
.y
, clip
.width
, clip
.height
);
646 g
.setColor(oldColor
);
652 * Returns <code>false</code> if components in this layered pane can overlap,
653 * otherwise <code>true</code>.
655 * @return <code>false</code> if components in this layered pane can overlap,
656 * otherwise <code>true</code>
658 public boolean isOptimizedDrawingEnabled()
660 int numChildren
= getComponentCount();
661 boolean result
= true;
662 for (int i
= 0; i
< numChildren
; ++i
)
664 Component c1
= getComponent(i
);
665 if (! c1
.isVisible())
667 Rectangle r1
= c1
.getBounds();
671 for (int j
= i
+ 1; j
< numChildren
; ++j
)
673 Component c2
= getComponent(j
);
674 if (! c2
.isVisible())
676 Rectangle r2
= c2
.getBounds();
679 if (r1
.intersects(r2
))