Home » openjdk-7 » javax » swing » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2007, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   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   
   26   
   27   package javax.swing;
   28   
   29   import java.awt;
   30   import java.awt.event;
   31   import java.beans.ConstructorProperties;
   32   import java.util.Locale;
   33   import java.io.Serializable;
   34   import javax.accessibility;
   35   
   36   /**
   37    * A lightweight container
   38    * that uses a BoxLayout object as its layout manager.
   39    * Box provides several class methods
   40    * that are useful for containers using BoxLayout --
   41    * even non-Box containers.
   42    *
   43    * <p>
   44    * The <code>Box</code> class can create several kinds
   45    * of invisible components
   46    * that affect layout:
   47    * glue, struts, and rigid areas.
   48    * If all the components your <code>Box</code> contains
   49    * have a fixed size,
   50    * you might want to use a glue component
   51    * (returned by <code>createGlue</code>)
   52    * to control the components' positions.
   53    * If you need a fixed amount of space between two components,
   54    * try using a strut
   55    * (<code>createHorizontalStrut</code> or <code>createVerticalStrut</code>).
   56    * If you need an invisible component
   57    * that always takes up the same amount of space,
   58    * get it by invoking <code>createRigidArea</code>.
   59    * <p>
   60    * If you are implementing a <code>BoxLayout</code> you
   61    * can find further information and examples in
   62    * <a
   63    href="http://java.sun.com/docs/books/tutorial/uiswing/layout/box.html">How to Use BoxLayout</a>,
   64    * a section in <em>The Java Tutorial.</em>
   65    * <p>
   66    * <strong>Warning:</strong>
   67    * Serialized objects of this class will not be compatible with
   68    * future Swing releases. The current serialization support is
   69    * appropriate for short term storage or RMI between applications running
   70    * the same version of Swing.  As of 1.4, support for long term storage
   71    * of all JavaBeans<sup><font size="-2">TM</font></sup>
   72    * has been added to the <code>java.beans</code> package.
   73    * Please see {@link java.beans.XMLEncoder}.
   74    *
   75    * @see BoxLayout
   76    *
   77    * @author  Timothy Prinzing
   78    */
   79   public class Box extends JComponent implements Accessible {
   80   
   81       /**
   82        * Creates a <code>Box</code> that displays its components
   83        * along the the specified axis.
   84        *
   85        * @param axis  can be {@link BoxLayout#X_AXIS},
   86        *              {@link BoxLayout#Y_AXIS},
   87        *              {@link BoxLayout#LINE_AXIS} or
   88        *              {@link BoxLayout#PAGE_AXIS}.
   89        * @throws AWTError if the <code>axis</code> is invalid
   90        * @see #createHorizontalBox
   91        * @see #createVerticalBox
   92        */
   93       public Box(int axis) {
   94           super();
   95           super.setLayout(new BoxLayout(this, axis));
   96       }
   97   
   98       /**
   99        * Creates a <code>Box</code> that displays its components
  100        * from left to right. If you want a <code>Box</code> that
  101        * respects the component orientation you should create the
  102        * <code>Box</code> using the constructor and pass in
  103        * <code>BoxLayout.LINE_AXIS</code>, eg:
  104        * <pre>
  105        *   Box lineBox = new Box(BoxLayout.LINE_AXIS);
  106        * </pre>
  107        *
  108        * @return the box
  109        */
  110       public static Box createHorizontalBox() {
  111           return new Box(BoxLayout.X_AXIS);
  112       }
  113   
  114       /**
  115        * Creates a <code>Box</code> that displays its components
  116        * from top to bottom. If you want a <code>Box</code> that
  117        * respects the component orientation you should create the
  118        * <code>Box</code> using the constructor and pass in
  119        * <code>BoxLayout.PAGE_AXIS</code>, eg:
  120        * <pre>
  121        *   Box lineBox = new Box(BoxLayout.PAGE_AXIS);
  122        * </pre>
  123        *
  124        * @return the box
  125        */
  126       public static Box createVerticalBox() {
  127           return new Box(BoxLayout.Y_AXIS);
  128       }
  129   
  130       /**
  131        * Creates an invisible component that's always the specified size.
  132        * <!-- WHEN WOULD YOU USE THIS AS OPPOSED TO A STRUT? -->
  133        *
  134        * @param d the dimensions of the invisible component
  135        * @return the component
  136        * @see #createGlue
  137        * @see #createHorizontalStrut
  138        * @see #createVerticalStrut
  139        */
  140       public static Component createRigidArea(Dimension d) {
  141           return new Filler(d, d, d);
  142       }
  143   
  144       /**
  145        * Creates an invisible, fixed-width component.
  146        * In a horizontal box,
  147        * you typically use this method
  148        * to force a certain amount of space between two components.
  149        * In a vertical box,
  150        * you might use this method
  151        * to force the box to be at least the specified width.
  152        * The invisible component has no height
  153        * unless excess space is available,
  154        * in which case it takes its share of available space,
  155        * just like any other component that has no maximum height.
  156        *
  157        * @param width the width of the invisible component, in pixels >= 0
  158        * @return the component
  159        * @see #createVerticalStrut
  160        * @see #createGlue
  161        * @see #createRigidArea
  162        */
  163       public static Component createHorizontalStrut(int width) {
  164           return new Filler(new Dimension(width,0), new Dimension(width,0),
  165                             new Dimension(width, Short.MAX_VALUE));
  166       }
  167   
  168       /**
  169        * Creates an invisible, fixed-height component.
  170        * In a vertical box,
  171        * you typically use this method
  172        * to force a certain amount of space between two components.
  173        * In a horizontal box,
  174        * you might use this method
  175        * to force the box to be at least the specified height.
  176        * The invisible component has no width
  177        * unless excess space is available,
  178        * in which case it takes its share of available space,
  179        * just like any other component that has no maximum width.
  180        *
  181        * @param height the height of the invisible component, in pixels >= 0
  182        * @return the component
  183        * @see #createHorizontalStrut
  184        * @see #createGlue
  185        * @see #createRigidArea
  186        */
  187       public static Component createVerticalStrut(int height) {
  188           return new Filler(new Dimension(0,height), new Dimension(0,height),
  189                             new Dimension(Short.MAX_VALUE, height));
  190       }
  191   
  192       /**
  193        * Creates an invisible "glue" component
  194        * that can be useful in a Box
  195        * whose visible components have a maximum width
  196        * (for a horizontal box)
  197        * or height (for a vertical box).
  198        * You can think of the glue component
  199        * as being a gooey substance
  200        * that expands as much as necessary
  201        * to fill the space between its neighboring components.
  202        *
  203        * <p>
  204        *
  205        * For example, suppose you have
  206        * a horizontal box that contains two fixed-size components.
  207        * If the box gets extra space,
  208        * the fixed-size components won't become larger,
  209       * so where does the extra space go?
  210        * Without glue,
  211        * the extra space goes to the right of the second component.
  212        * If you put glue between the fixed-size components,
  213        * then the extra space goes there.
  214        * If you put glue before the first fixed-size component,
  215        * the extra space goes there,
  216        * and the fixed-size components are shoved against the right
  217        * edge of the box.
  218        * If you put glue before the first fixed-size component
  219        * and after the second fixed-size component,
  220        * the fixed-size components are centered in the box.
  221        *
  222        * <p>
  223        *
  224        * To use glue,
  225        * call <code>Box.createGlue</code>
  226        * and add the returned component to a container.
  227        * The glue component has no minimum or preferred size,
  228        * so it takes no space unless excess space is available.
  229        * If excess space is available,
  230        * then the glue component takes its share of available
  231        * horizontal or vertical space,
  232        * just like any other component that has no maximum width or height.
  233        *
  234        * @return the component
  235        */
  236       public static Component createGlue() {
  237           return new Filler(new Dimension(0,0), new Dimension(0,0),
  238                             new Dimension(Short.MAX_VALUE, Short.MAX_VALUE));
  239       }
  240   
  241       /**
  242        * Creates a horizontal glue component.
  243        *
  244        * @return the component
  245        */
  246       public static Component createHorizontalGlue() {
  247           return new Filler(new Dimension(0,0), new Dimension(0,0),
  248                             new Dimension(Short.MAX_VALUE, 0));
  249       }
  250   
  251       /**
  252        * Creates a vertical glue component.
  253        *
  254        * @return the component
  255        */
  256       public static Component createVerticalGlue() {
  257           return new Filler(new Dimension(0,0), new Dimension(0,0),
  258                             new Dimension(0, Short.MAX_VALUE));
  259       }
  260   
  261       /**
  262        * Throws an AWTError, since a Box can use only a BoxLayout.
  263        *
  264        * @param l the layout manager to use
  265        */
  266       public void setLayout(LayoutManager l) {
  267           throw new AWTError("Illegal request");
  268       }
  269   
  270       /**
  271        * Paints this <code>Box</code>.  If this <code>Box</code> has a UI this
  272        * method invokes super's implementation, otherwise if this
  273        * <code>Box</code> is opaque the <code>Graphics</code> is filled
  274        * using the background.
  275        *
  276        * @param g the <code>Graphics</code> to paint to
  277        * @throws NullPointerException if <code>g</code> is null
  278        * @since 1.6
  279        */
  280       protected void paintComponent(Graphics g) {
  281           if (ui != null) {
  282               // On the off chance some one created a UI, honor it
  283               super.paintComponent(g);
  284           } else if (isOpaque()) {
  285               g.setColor(getBackground());
  286               g.fillRect(0, 0, getWidth(), getHeight());
  287           }
  288       }
  289   
  290   
  291       /**
  292        * An implementation of a lightweight component that participates in
  293        * layout but has no view.
  294        * <p>
  295        * <strong>Warning:</strong>
  296        * Serialized objects of this class will not be compatible with
  297        * future Swing releases. The current serialization support is
  298        * appropriate for short term storage or RMI between applications running
  299        * the same version of Swing.  As of 1.4, support for long term storage
  300        * of all JavaBeans<sup><font size="-2">TM</font></sup>
  301        * has been added to the <code>java.beans</code> package.
  302        * Please see {@link java.beans.XMLEncoder}.
  303        */
  304       public static class Filler extends JComponent implements Accessible {
  305   
  306           /**
  307            * Constructor to create shape with the given size ranges.
  308            *
  309            * @param min   Minimum size
  310            * @param pref  Preferred size
  311            * @param max   Maximum size
  312            */
  313           @ConstructorProperties({"minimumSize", "preferredSize", "maximumSize"})
  314           public Filler(Dimension min, Dimension pref, Dimension max) {
  315               setMinimumSize(min);
  316               setPreferredSize(pref);
  317               setMaximumSize(max);
  318           }
  319   
  320           /**
  321            * Change the size requests for this shape.  An invalidate() is
  322            * propagated upward as a result so that layout will eventually
  323            * happen with using the new sizes.
  324            *
  325            * @param min   Value to return for getMinimumSize
  326            * @param pref  Value to return for getPreferredSize
  327            * @param max   Value to return for getMaximumSize
  328            */
  329           public void changeShape(Dimension min, Dimension pref, Dimension max) {
  330               setMinimumSize(min);
  331               setPreferredSize(pref);
  332               setMaximumSize(max);
  333               revalidate();
  334           }
  335   
  336           // ---- Component methods ------------------------------------------
  337   
  338           /**
  339            * Paints this <code>Filler</code>.  If this
  340            * <code>Filler</code> has a UI this method invokes super's
  341            * implementation, otherwise if this <code>Filler</code> is
  342            * opaque the <code>Graphics</code> is filled using the
  343            * background.
  344            *
  345            * @param g the <code>Graphics</code> to paint to
  346            * @throws NullPointerException if <code>g</code> is null
  347            * @since 1.6
  348            */
  349           protected void paintComponent(Graphics g) {
  350               if (ui != null) {
  351                   // On the off chance some one created a UI, honor it
  352                   super.paintComponent(g);
  353               } else if (isOpaque()) {
  354                   g.setColor(getBackground());
  355                   g.fillRect(0, 0, getWidth(), getHeight());
  356               }
  357           }
  358   
  359   /////////////////
  360   // Accessibility support for Box$Filler
  361   ////////////////
  362   
  363           /**
  364            * Gets the AccessibleContext associated with this Box.Filler.
  365            * For box fillers, the AccessibleContext takes the form of an
  366            * AccessibleBoxFiller.
  367            * A new AccessibleAWTBoxFiller instance is created if necessary.
  368            *
  369            * @return an AccessibleBoxFiller that serves as the
  370            *         AccessibleContext of this Box.Filler.
  371            */
  372           public AccessibleContext getAccessibleContext() {
  373               if (accessibleContext == null) {
  374                   accessibleContext = new AccessibleBoxFiller();
  375               }
  376               return accessibleContext;
  377           }
  378   
  379           /**
  380            * This class implements accessibility support for the
  381            * <code>Box.Filler</code> class.
  382            */
  383           protected class AccessibleBoxFiller extends AccessibleAWTComponent {
  384               // AccessibleContext methods
  385               //
  386               /**
  387                * Gets the role of this object.
  388                *
  389                * @return an instance of AccessibleRole describing the role of
  390                *   the object (AccessibleRole.FILLER)
  391                * @see AccessibleRole
  392                */
  393               public AccessibleRole getAccessibleRole() {
  394                   return AccessibleRole.FILLER;
  395               }
  396           }
  397       }
  398   
  399   /////////////////
  400   // Accessibility support for Box
  401   ////////////////
  402   
  403       /**
  404        * Gets the AccessibleContext associated with this Box.
  405        * For boxes, the AccessibleContext takes the form of an
  406        * AccessibleBox.
  407        * A new AccessibleAWTBox instance is created if necessary.
  408        *
  409        * @return an AccessibleBox that serves as the
  410        *         AccessibleContext of this Box
  411        */
  412       public AccessibleContext getAccessibleContext() {
  413           if (accessibleContext == null) {
  414               accessibleContext = new AccessibleBox();
  415           }
  416           return accessibleContext;
  417       }
  418   
  419       /**
  420        * This class implements accessibility support for the
  421        * <code>Box</code> class.
  422        */
  423       protected class AccessibleBox extends AccessibleAWTContainer {
  424           // AccessibleContext methods
  425           //
  426           /**
  427            * Gets the role of this object.
  428            *
  429            * @return an instance of AccessibleRole describing the role of the
  430            *   object (AccessibleRole.FILLER)
  431            * @see AccessibleRole
  432            */
  433           public AccessibleRole getAccessibleRole() {
  434               return AccessibleRole.FILLER;
  435           }
  436       } // inner class AccessibleBox
  437   }

Home » openjdk-7 » javax » swing » [javadoc | source]