< prev index next >

src/java.desktop/share/classes/javax/swing/JLayeredPane.java

Print this page




  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javax.swing;
  26 
  27 import java.awt.Component;
  28 import java.util.ArrayList;
  29 import java.util.Hashtable;
  30 import java.awt.Color;
  31 import java.awt.Graphics;
  32 import java.awt.Rectangle;
  33 import sun.awt.SunToolkit;
  34 
  35 import javax.accessibility.*;
  36 
  37 /**
  38  * <code>JLayeredPane</code> adds depth to a JFC/Swing container,
  39  * allowing components to overlap each other when needed.
  40  * An <code>Integer</code> object specifies each component's depth in the
  41  * container, where higher-numbered components sit &quot;on top&quot; of other
  42  * components.
  43  * For task-oriented documentation and examples of using layered panes see
  44  * <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/layeredpane.html">How to Use a Layered Pane</a>,
  45  * a section in <em>The Java Tutorial</em>.
  46  *
  47  * <TABLE STYLE="FLOAT:RIGHT" BORDER="0" SUMMARY="layout">
  48  * <TR>
  49  *   <TD ALIGN="CENTER">
  50  *     <P STYLE="TEXT-ALIGN:CENTER"><IMG SRC="doc-files/JLayeredPane-1.gif"
  51  *     alt="The following text describes this image."
  52  *     WIDTH="269" HEIGHT="264" STYLE="FLOAT:BOTTOM; BORDER=0">
  53  *   </TD>
  54  * </TR>
  55  * </TABLE>
  56  * For convenience, <code>JLayeredPane</code> divides the depth-range
  57  * into several different layers. Putting a component into one of those
  58  * layers makes it easy to ensure that components overlap properly,
  59  * without having to worry about specifying numbers for specific depths:
  60  * <DL>
  61  *    <DT>DEFAULT_LAYER</DT>
  62  *         <DD>The standard layer, where most components go. This the bottommost
  63  *         layer.
  64  *    <DT>PALETTE_LAYER</DT>
  65  *         <DD>The palette layer sits over the default layer. Useful for floating
  66  *         toolbars and palettes, so they can be positioned above other components.
  67  *    <DT>MODAL_LAYER</DT>
  68  *         <DD>The layer used for modal dialogs. They will appear on top of any
  69  *         toolbars, palettes, or standard components in the container.
  70  *    <DT>POPUP_LAYER</DT>
  71  *         <DD>The popup layer displays above dialogs. That way, the popup windows
  72  *         associated with combo boxes, tooltips, and other help text will appear
  73  *         above the component, palette, or dialog that generated them.
  74  *    <DT>DRAG_LAYER</DT>
  75  *         <DD>When dragging a component, reassigning it to the drag layer ensures
  76  *         that it is positioned over every other component in the container. When
  77  *         finished dragging, it can be reassigned to its normal layer.
  78  * </DL>
  79  * The <code>JLayeredPane</code> methods <code>moveToFront(Component)</code>,
  80  * <code>moveToBack(Component)</code> and <code>setPosition</code> can be used
  81  * to reposition a component within its layer. The <code>setLayer</code> method
  82  * can also be used to change the component's current layer.
  83  *
  84  * <h2>Details</h2>
  85  * <code>JLayeredPane</code> manages its list of children like
  86  * <code>Container</code>, but allows for the definition of a several
  87  * layers within itself. Children in the same layer are managed exactly
  88  * like the normal <code>Container</code> object,
  89  * with the added feature that when children components overlap, children
  90  * in higher layers display above the children in lower layers.
  91  * <p>
  92  * Each layer is a distinct integer number. The layer attribute can be set
  93  * on a <code>Component</code> by passing an <code>Integer</code>
  94  * object during the add call.<br> For example:
  95  * <PRE>
  96  *     layeredPane.add(child, JLayeredPane.DEFAULT_LAYER);
  97  * or
  98  *     layeredPane.add(child, new Integer(10));
  99  * </PRE>
 100  * The layer attribute can also be set on a Component by calling<PRE>
 101  *     layeredPaneParent.setLayer(child, 10)</PRE>
 102  * on the <code>JLayeredPane</code> that is the parent of component. The layer
 103  * should be set <i>before</i> adding the child to the parent.
 104  * <p>
 105  * Higher number layers display above lower number layers. So, using
 106  * numbers for the layers and letters for individual components, a
 107  * representative list order would look like this:<PRE>
 108  *       5a, 5b, 5c, 2a, 2b, 2c, 1a </PRE>
 109  * where the leftmost components are closest to the top of the display.
 110  * <p>
 111  * A component can be moved to the top or bottom position within its
 112  * layer by calling <code>moveToFront</code> or <code>moveToBack</code>.
 113  * <p>
 114  * The position of a component within a layer can also be specified directly.
 115  * Valid positions range from 0 up to one less than the number of
 116  * components in that layer. A value of -1 indicates the bottommost
 117  * position. A value of 0 indicates the topmost position. Unlike layer
 118  * numbers, higher position values are <i>lower</i> in the display.
 119  * <blockquote>
 120  * <b>Note:</b> This sequence (defined by java.awt.Container) is the reverse
 121  * of the layer numbering sequence. Usually though, you will use <code>moveToFront</code>,
 122  * <code>moveToBack</code>, and <code>setLayer</code>.
 123  * </blockquote>
 124  * Here are some examples using the method add(Component, layer, position):
 125  * Calling add(5x, 5, -1) results in:<PRE>
 126  *       5a, 5b, 5c, 5x, 2a, 2b, 2c, 1a </PRE>
 127  *
 128  * Calling add(5z, 5, 2) results in:<PRE>
 129  *       5a, 5b, 5z, 5c, 5x, 2a, 2b, 2c, 1a </PRE>
 130  *
 131  * Calling add(3a, 3, 7) results in:<PRE>
 132  *       5a, 5b, 5z, 5c, 5x, 3a, 2a, 2b, 2c, 1a </PRE>
 133  *
 134  * Using normal paint/event mechanics results in 1a appearing at the bottom
 135  * and 5a being above all other components.
 136  * <p>
 137  * <b>Note:</b> that these layers are simply a logical construct and LayoutManagers
 138  * will affect all child components of this container without regard for
 139  * layer settings.
 140  * <p>
 141  * <strong>Warning:</strong> Swing is not thread safe. For more
 142  * information see <a
 143  * href="package-summary.html#threading">Swing's Threading
 144  * Policy</a>.
 145  * <p>
 146  * <strong>Warning:</strong>
 147  * Serialized objects of this class will not be compatible with
 148  * future Swing releases. The current serialization support is
 149  * appropriate for short term storage or RMI between applications running
 150  * the same version of Swing.  As of 1.4, support for long term storage
 151  * of all JavaBeans&trade;
 152  * has been added to the <code>java.beans</code> package.
 153  * Please see {@link java.beans.XMLEncoder}.
 154  *
 155  * @author David Kloba
 156  * @since 1.2
 157  */
 158 @SuppressWarnings("serial")
 159 public class JLayeredPane extends JComponent implements Accessible {
 160     /// Watch the values in getObjectForLayer()
 161     /** Convenience object defining the Default layer. Equivalent to new Integer(0).*/
 162     public static final Integer DEFAULT_LAYER = 0;
 163     /** Convenience object defining the Palette layer. Equivalent to new Integer(100).*/
 164     public static final Integer PALETTE_LAYER = 100;
 165     /** Convenience object defining the Modal layer. Equivalent to new Integer(200).*/
 166     public static final Integer MODAL_LAYER = 200;
 167     /** Convenience object defining the Popup layer. Equivalent to new Integer(300).*/
 168     public static final Integer POPUP_LAYER = 300;
 169     /** Convenience object defining the Drag layer. Equivalent to new Integer(400).*/
 170     public static final Integer DRAG_LAYER = 400;
 171     /** Convenience object defining the Frame Content layer.
 172       * This layer is normally only use to position the contentPane and menuBar


 423      *
 424      * @param c the Component to move
 425      * @see #setPosition(Component, int)
 426      */
 427     public void moveToFront(Component c) {
 428         setPosition(c, 0);
 429     }
 430 
 431     /**
 432      * Moves the component to the bottom of the components in its current layer
 433      * (position -1).
 434      *
 435      * @param c the Component to move
 436      * @see #setPosition(Component, int)
 437      */
 438     public void moveToBack(Component c) {
 439         setPosition(c, -1);
 440     }
 441 
 442     /**
 443      * Moves the component to <code>position</code> within its current layer,
 444      * where 0 is the topmost position within the layer and -1 is the bottommost
 445      * position.
 446      * <p>
 447      * <b>Note:</b> Position numbering is defined by java.awt.Container, and
 448      * is the opposite of layer numbering. Lower position numbers are closer
 449      * to the top (0 is topmost), and higher position numbers are closer to
 450      * the bottom.
 451      *
 452      * @param c         the Component to move
 453      * @param position  an int in the range -1..N-1, where N is the number of
 454      *                  components in the component's current layer
 455      */
 456     public void setPosition(Component c, int position) {
 457         setLayer(c, getLayer(c), position);
 458     }
 459 
 460     /**
 461      * Get the relative position of the component within its layer.
 462      *
 463      * @param c  the Component to check


 696             layerStart = layerEnd;
 697 
 698         // If we are adding to the bottom, return the last element
 699         if (position == -1)
 700             return layerEnd;
 701 
 702         // Otherwise make sure the requested position falls in the
 703         // proper range
 704         if (position > -1 && layerStart + position <= layerEnd)
 705             return layerStart + position;
 706 
 707         // Otherwise return the end of the layer
 708         return layerEnd;
 709     }
 710 
 711     /**
 712      * Returns a string representation of this JLayeredPane. This method
 713      * is intended to be used only for debugging purposes, and the
 714      * content and format of the returned string may vary between
 715      * implementations. The returned string may be empty but may not
 716      * be <code>null</code>.
 717      *
 718      * @return  a string representation of this JLayeredPane.
 719      */
 720     protected String paramString() {
 721         String optimizedDrawingPossibleString = (optimizedDrawingPossible ?
 722                                                  "true" : "false");
 723 
 724         return super.paramString() +
 725         ",optimizedDrawingPossible=" + optimizedDrawingPossibleString;
 726     }
 727 
 728 /////////////////
 729 // Accessibility support
 730 ////////////////
 731 
 732     /**
 733      * Gets the AccessibleContext associated with this JLayeredPane.
 734      * For layered panes, the AccessibleContext takes the form of an
 735      * AccessibleJLayeredPane.
 736      * A new AccessibleJLayeredPane instance is created if necessary.
 737      *
 738      * @return an AccessibleJLayeredPane that serves as the
 739      *         AccessibleContext of this JLayeredPane
 740      */
 741     public AccessibleContext getAccessibleContext() {
 742         if (accessibleContext == null) {
 743             accessibleContext = new AccessibleJLayeredPane();
 744         }
 745         return accessibleContext;
 746     }
 747 
 748     /**
 749      * This class implements accessibility support for the
 750      * <code>JLayeredPane</code> class.  It provides an implementation of the
 751      * Java Accessibility API appropriate to layered pane user-interface
 752      * elements.
 753      * <p>
 754      * <strong>Warning:</strong>
 755      * Serialized objects of this class will not be compatible with
 756      * future Swing releases. The current serialization support is
 757      * appropriate for short term storage or RMI between applications running
 758      * the same version of Swing.  As of 1.4, support for long term storage
 759      * of all JavaBeans&trade;
 760      * has been added to the <code>java.beans</code> package.
 761      * Please see {@link java.beans.XMLEncoder}.
 762      */
 763     @SuppressWarnings("serial")
 764     protected class AccessibleJLayeredPane extends AccessibleJComponent {
 765 
 766         /**
 767          * Get the role of this object.
 768          *
 769          * @return an instance of AccessibleRole describing the role of the
 770          * object
 771          * @see AccessibleRole
 772          */
 773         public AccessibleRole getAccessibleRole() {
 774             return AccessibleRole.LAYERED_PANE;
 775         }
 776     }
 777 }


  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javax.swing;
  26 
  27 import java.awt.Component;
  28 import java.util.ArrayList;
  29 import java.util.Hashtable;
  30 import java.awt.Color;
  31 import java.awt.Graphics;
  32 import java.awt.Rectangle;
  33 import sun.awt.SunToolkit;
  34 
  35 import javax.accessibility.*;
  36 
  37 /**
  38  * {@code JLayeredPane} adds depth to a JFC/Swing container,
  39  * allowing components to overlap each other when needed.
  40  * An {@code Integer} object specifies each component's depth in the
  41  * container, where higher-numbered components sit &quot;on top&quot; of other
  42  * components.
  43  * For task-oriented documentation and examples of using layered panes see
  44  * <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/layeredpane.html">How to Use a Layered Pane</a>,
  45  * a section in <em>The Java Tutorial</em>.
  46  *
  47  * <TABLE STYLE="FLOAT:RIGHT" BORDER="0" SUMMARY="layout">
  48  * <TR>
  49  *   <TD ALIGN="CENTER">
  50  *     <P STYLE="TEXT-ALIGN:CENTER"><IMG SRC="doc-files/JLayeredPane-1.gif"
  51  *     alt="The following text describes this image."
  52  *     WIDTH="269" HEIGHT="264" STYLE="FLOAT:BOTTOM; BORDER=0">
  53  *   </TD>
  54  * </TR>
  55  * </TABLE>
  56  * For convenience, {@code JLayeredPane} divides the depth-range
  57  * into several different layers. Putting a component into one of those
  58  * layers makes it easy to ensure that components overlap properly,
  59  * without having to worry about specifying numbers for specific depths:
  60  * <DL>
  61  *    <DT>DEFAULT_LAYER</DT>
  62  *         <DD>The standard layer, where most components go. This the bottommost
  63  *         layer.
  64  *    <DT>PALETTE_LAYER</DT>
  65  *         <DD>The palette layer sits over the default layer. Useful for floating
  66  *         toolbars and palettes, so they can be positioned above other components.
  67  *    <DT>MODAL_LAYER</DT>
  68  *         <DD>The layer used for modal dialogs. They will appear on top of any
  69  *         toolbars, palettes, or standard components in the container.
  70  *    <DT>POPUP_LAYER</DT>
  71  *         <DD>The popup layer displays above dialogs. That way, the popup windows
  72  *         associated with combo boxes, tooltips, and other help text will appear
  73  *         above the component, palette, or dialog that generated them.
  74  *    <DT>DRAG_LAYER</DT>
  75  *         <DD>When dragging a component, reassigning it to the drag layer ensures
  76  *         that it is positioned over every other component in the container. When
  77  *         finished dragging, it can be reassigned to its normal layer.
  78  * </DL>
  79  * The {@code JLayeredPane} methods {@code moveToFront(Component)},
  80  * {@code moveToBack(Component)} and {@code setPosition} can be used
  81  * to reposition a component within its layer. The {@code setLayer} method
  82  * can also be used to change the component's current layer.
  83  *
  84  * <h2>Details</h2>
  85  * {@code JLayeredPane} manages its list of children like
  86  * {@code Container}, but allows for the definition of a several
  87  * layers within itself. Children in the same layer are managed exactly
  88  * like the normal {@code Container} object,
  89  * with the added feature that when children components overlap, children
  90  * in higher layers display above the children in lower layers.
  91  * <p>
  92  * Each layer is a distinct integer number. The layer attribute can be set
  93  * on a {@code Component} by passing an {@code Integer}
  94  * object during the add call.<br> For example:
  95  * <PRE>
  96  *     layeredPane.add(child, JLayeredPane.DEFAULT_LAYER);
  97  * or
  98  *     layeredPane.add(child, new Integer(10));
  99  * </PRE>
 100  * The layer attribute can also be set on a Component by calling<PRE>
 101  *     layeredPaneParent.setLayer(child, 10)</PRE>
 102  * on the {@code JLayeredPane} that is the parent of component. The layer
 103  * should be set <i>before</i> adding the child to the parent.
 104  * <p>
 105  * Higher number layers display above lower number layers. So, using
 106  * numbers for the layers and letters for individual components, a
 107  * representative list order would look like this:<PRE>
 108  *       5a, 5b, 5c, 2a, 2b, 2c, 1a </PRE>
 109  * where the leftmost components are closest to the top of the display.
 110  * <p>
 111  * A component can be moved to the top or bottom position within its
 112  * layer by calling {@code moveToFront} or {@code moveToBack}.
 113  * <p>
 114  * The position of a component within a layer can also be specified directly.
 115  * Valid positions range from 0 up to one less than the number of
 116  * components in that layer. A value of -1 indicates the bottommost
 117  * position. A value of 0 indicates the topmost position. Unlike layer
 118  * numbers, higher position values are <i>lower</i> in the display.
 119  * <blockquote>
 120  * <b>Note:</b> This sequence (defined by java.awt.Container) is the reverse
 121  * of the layer numbering sequence. Usually though, you will use {@code moveToFront},
 122  * {@code moveToBack}, and {@code setLayer}.
 123  * </blockquote>
 124  * Here are some examples using the method add(Component, layer, position):
 125  * Calling add(5x, 5, -1) results in:<PRE>
 126  *       5a, 5b, 5c, 5x, 2a, 2b, 2c, 1a </PRE>
 127  *
 128  * Calling add(5z, 5, 2) results in:<PRE>
 129  *       5a, 5b, 5z, 5c, 5x, 2a, 2b, 2c, 1a </PRE>
 130  *
 131  * Calling add(3a, 3, 7) results in:<PRE>
 132  *       5a, 5b, 5z, 5c, 5x, 3a, 2a, 2b, 2c, 1a </PRE>
 133  *
 134  * Using normal paint/event mechanics results in 1a appearing at the bottom
 135  * and 5a being above all other components.
 136  * <p>
 137  * <b>Note:</b> that these layers are simply a logical construct and LayoutManagers
 138  * will affect all child components of this container without regard for
 139  * layer settings.
 140  * <p>
 141  * <strong>Warning:</strong> Swing is not thread safe. For more
 142  * information see <a
 143  * href="package-summary.html#threading">Swing's Threading
 144  * Policy</a>.
 145  * <p>
 146  * <strong>Warning:</strong>
 147  * Serialized objects of this class will not be compatible with
 148  * future Swing releases. The current serialization support is
 149  * appropriate for short term storage or RMI between applications running
 150  * the same version of Swing.  As of 1.4, support for long term storage
 151  * of all JavaBeans&trade;
 152  * has been added to the {@code java.beans} package.
 153  * Please see {@link java.beans.XMLEncoder}.
 154  *
 155  * @author David Kloba
 156  * @since 1.2
 157  */
 158 @SuppressWarnings("serial")
 159 public class JLayeredPane extends JComponent implements Accessible {
 160     /// Watch the values in getObjectForLayer()
 161     /** Convenience object defining the Default layer. Equivalent to new Integer(0).*/
 162     public static final Integer DEFAULT_LAYER = 0;
 163     /** Convenience object defining the Palette layer. Equivalent to new Integer(100).*/
 164     public static final Integer PALETTE_LAYER = 100;
 165     /** Convenience object defining the Modal layer. Equivalent to new Integer(200).*/
 166     public static final Integer MODAL_LAYER = 200;
 167     /** Convenience object defining the Popup layer. Equivalent to new Integer(300).*/
 168     public static final Integer POPUP_LAYER = 300;
 169     /** Convenience object defining the Drag layer. Equivalent to new Integer(400).*/
 170     public static final Integer DRAG_LAYER = 400;
 171     /** Convenience object defining the Frame Content layer.
 172       * This layer is normally only use to position the contentPane and menuBar


 423      *
 424      * @param c the Component to move
 425      * @see #setPosition(Component, int)
 426      */
 427     public void moveToFront(Component c) {
 428         setPosition(c, 0);
 429     }
 430 
 431     /**
 432      * Moves the component to the bottom of the components in its current layer
 433      * (position -1).
 434      *
 435      * @param c the Component to move
 436      * @see #setPosition(Component, int)
 437      */
 438     public void moveToBack(Component c) {
 439         setPosition(c, -1);
 440     }
 441 
 442     /**
 443      * Moves the component to {@code position} within its current layer,
 444      * where 0 is the topmost position within the layer and -1 is the bottommost
 445      * position.
 446      * <p>
 447      * <b>Note:</b> Position numbering is defined by java.awt.Container, and
 448      * is the opposite of layer numbering. Lower position numbers are closer
 449      * to the top (0 is topmost), and higher position numbers are closer to
 450      * the bottom.
 451      *
 452      * @param c         the Component to move
 453      * @param position  an int in the range -1..N-1, where N is the number of
 454      *                  components in the component's current layer
 455      */
 456     public void setPosition(Component c, int position) {
 457         setLayer(c, getLayer(c), position);
 458     }
 459 
 460     /**
 461      * Get the relative position of the component within its layer.
 462      *
 463      * @param c  the Component to check


 696             layerStart = layerEnd;
 697 
 698         // If we are adding to the bottom, return the last element
 699         if (position == -1)
 700             return layerEnd;
 701 
 702         // Otherwise make sure the requested position falls in the
 703         // proper range
 704         if (position > -1 && layerStart + position <= layerEnd)
 705             return layerStart + position;
 706 
 707         // Otherwise return the end of the layer
 708         return layerEnd;
 709     }
 710 
 711     /**
 712      * Returns a string representation of this JLayeredPane. This method
 713      * is intended to be used only for debugging purposes, and the
 714      * content and format of the returned string may vary between
 715      * implementations. The returned string may be empty but may not
 716      * be {@code null}.
 717      *
 718      * @return  a string representation of this JLayeredPane.
 719      */
 720     protected String paramString() {
 721         String optimizedDrawingPossibleString = (optimizedDrawingPossible ?
 722                                                  "true" : "false");
 723 
 724         return super.paramString() +
 725         ",optimizedDrawingPossible=" + optimizedDrawingPossibleString;
 726     }
 727 
 728 /////////////////
 729 // Accessibility support
 730 ////////////////
 731 
 732     /**
 733      * Gets the AccessibleContext associated with this JLayeredPane.
 734      * For layered panes, the AccessibleContext takes the form of an
 735      * AccessibleJLayeredPane.
 736      * A new AccessibleJLayeredPane instance is created if necessary.
 737      *
 738      * @return an AccessibleJLayeredPane that serves as the
 739      *         AccessibleContext of this JLayeredPane
 740      */
 741     public AccessibleContext getAccessibleContext() {
 742         if (accessibleContext == null) {
 743             accessibleContext = new AccessibleJLayeredPane();
 744         }
 745         return accessibleContext;
 746     }
 747 
 748     /**
 749      * This class implements accessibility support for the
 750      * {@code JLayeredPane} class.  It provides an implementation of the
 751      * Java Accessibility API appropriate to layered pane user-interface
 752      * elements.
 753      * <p>
 754      * <strong>Warning:</strong>
 755      * Serialized objects of this class will not be compatible with
 756      * future Swing releases. The current serialization support is
 757      * appropriate for short term storage or RMI between applications running
 758      * the same version of Swing.  As of 1.4, support for long term storage
 759      * of all JavaBeans&trade;
 760      * has been added to the {@code java.beans} package.
 761      * Please see {@link java.beans.XMLEncoder}.
 762      */
 763     @SuppressWarnings("serial")
 764     protected class AccessibleJLayeredPane extends AccessibleJComponent {
 765 
 766         /**
 767          * Get the role of this object.
 768          *
 769          * @return an instance of AccessibleRole describing the role of the
 770          * object
 771          * @see AccessibleRole
 772          */
 773         public AccessibleRole getAccessibleRole() {
 774             return AccessibleRole.LAYERED_PANE;
 775         }
 776     }
 777 }
< prev index next >