1 /*
   2  * Copyright (c) 2005, 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 package javax.swing;
  26 
  27 import java.awt.Container;
  28 import javax.swing.plaf.ComponentUI;
  29 import sun.awt.AppContext;
  30 
  31 /**
  32  * <code>LayoutStyle</code> provides information about how to position
  33  * components.  This class is primarily useful for visual tools and
  34  * layout managers.  Most developers will not need to use this class.
  35  * <p>
  36  * You typically don't set or create a
  37  * <code>LayoutStyle</code>.  Instead use the static method
  38  * <code>getInstance</code> to obtain the current instance.
  39  *
  40  * @since 1.6
  41  */
  42 public abstract class LayoutStyle {
  43     /**
  44      * Sets the shared instance of <code>LayoutStyle</code>.  Specifying
  45      * <code>null</code> results in using the <code>LayoutStyle</code> from
  46      * the current <code>LookAndFeel</code>.
  47      *
  48      * @param style the <code>LayoutStyle</code>, or <code>null</code>
  49      * @see #getInstance
  50      */
  51     public static void setInstance(LayoutStyle style) {
  52         synchronized(LayoutStyle.class) {
  53             if (style == null) {
  54                 AppContext.getAppContext().remove(LayoutStyle.class);
  55             }
  56             else {
  57                 AppContext.getAppContext().put(LayoutStyle.class, style);
  58             }
  59         }
  60     }
  61 
  62     /**
  63      * Returns the shared instance of <code>LayoutStyle</code>.  If an instance
  64      * has not been specified in <code>setInstance</code>, this will return
  65      * the <code>LayoutStyle</code> from the current <code>LookAndFeel</code>.
  66      *
  67      * @see LookAndFeel#getLayoutStyle
  68      * @return the shared instance of <code>LayoutStyle</code>
  69      */
  70     public static LayoutStyle getInstance() {
  71         LayoutStyle style;
  72         synchronized(LayoutStyle.class) {
  73             style = (LayoutStyle)AppContext.getAppContext().
  74                     get(LayoutStyle.class);
  75         }
  76         if (style == null) {
  77             return UIManager.getLookAndFeel().getLayoutStyle();
  78         }
  79         return style;
  80     }
  81 
  82 
  83     /**
  84      * <code>ComponentPlacement</code> is an enumeration of the
  85      * possible ways two components can be placed relative to each
  86      * other.  <code>ComponentPlacement</code> is used by the
  87      * <code>LayoutStyle</code> method <code>getPreferredGap</code>.  Refer to
  88      * <code>LayoutStyle</code> for more information.
  89      *
  90      * @see LayoutStyle#getPreferredGap(JComponent,JComponent,
  91      *      ComponentPlacement,int,Container)
  92      * @since 1.6
  93      */
  94     public enum ComponentPlacement {
  95         /**
  96          * Enumeration value indicating the two components are
  97          * visually related and will be placed in the same parent.
  98          * For example, a <code>JLabel</code> providing a label for a
  99          * <code>JTextField</code> is typically visually associated
 100          * with the <code>JTextField</code>; the constant <code>RELATED</code>
 101          * is used for this.
 102          */
 103         RELATED,
 104 
 105         /**
 106          * Enumeration value indicating the two components are
 107          * visually unrelated and will be placed in the same parent.
 108          * For example, groupings of components are usually visually
 109          * separated; the constant <code>UNRELATED</code> is used for this.
 110          */
 111         UNRELATED,
 112 
 113         /**
 114          * Enumeration value indicating the distance to indent a component
 115          * is being requested.  For example, often times the children of
 116          * a label will be horizontally indented from the label.  To determine
 117          * the preferred distance for such a gap use the
 118          * <code>INDENT</code> type.
 119          * <p>
 120          * This value is typically only useful with a direction of
 121          * <code>EAST</code> or <code>WEST</code>.
 122          */
 123         INDENT;
 124     }
 125 
 126 
 127     /**
 128      * Creates a new <code>LayoutStyle</code>.  You generally don't
 129      * create a <code>LayoutStyle</code>.  Instead use the method
 130      * <code>getInstance</code> to obtain the current
 131      * <code>LayoutStyle</code>.
 132      */
 133     public LayoutStyle() {
 134     }
 135 
 136     /**
 137      * Returns the amount of space to use between two components.
 138      * The return value indicates the distance to place
 139      * <code>component2</code> relative to <code>component1</code>.
 140      * For example, the following returns the amount of space to place
 141      * between <code>component2</code> and <code>component1</code>
 142      * when <code>component2</code> is placed vertically above
 143      * <code>component1</code>:
 144      * <pre>
 145      *   int gap = getPreferredGap(component1, component2,
 146      *                             ComponentPlacement.RELATED,
 147      *                             SwingConstants.NORTH, parent);
 148      * </pre>
 149      * The <code>type</code> parameter indicates the relation between
 150      * the two components.  If the two components will be contained in
 151      * the same parent and are showing similar logically related
 152      * items, use <code>RELATED</code>.  If the two components will be
 153      * contained in the same parent but show logically unrelated items
 154      * use <code>UNRELATED</code>.  Some look and feels may not
 155      * distinguish between the <code>RELATED</code> and
 156      * <code>UNRELATED</code> types.
 157      * <p>
 158      * The return value is not intended to take into account the
 159      * current size and position of <code>component2</code> or
 160      * <code>component1</code>.  The return value may take into
 161      * consideration various properties of the components.  For
 162      * example, the space may vary based on font size, or the preferred
 163      * size of the component.
 164      *
 165      * @param component1 the <code>JComponent</code>
 166      *               <code>component2</code> is being placed relative to
 167      * @param component2 the <code>JComponent</code> being placed
 168      * @param position the position <code>component2</code> is being placed
 169      *        relative to <code>component1</code>; one of
 170      *        <code>SwingConstants.NORTH</code>,
 171      *        <code>SwingConstants.SOUTH</code>,
 172      *        <code>SwingConstants.EAST</code> or
 173      *        <code>SwingConstants.WEST</code>
 174      * @param type how the two components are being placed
 175      * @param parent the parent of <code>component2</code>; this may differ
 176      *        from the actual parent and it may be <code>null</code>
 177      * @return the amount of space to place between the two components
 178      * @throws NullPointerException if <code>component1</code>,
 179      *         <code>component2</code> or <code>type</code> is
 180      *         <code>null</code>
 181      * @throws IllegalArgumentException if <code>position</code> is not
 182      *         one of <code>SwingConstants.NORTH</code>,
 183      *         <code>SwingConstants.SOUTH</code>,
 184      *         <code>SwingConstants.EAST</code> or
 185      *         <code>SwingConstants.WEST</code>
 186      * @see LookAndFeel#getLayoutStyle
 187      * @since 1.6
 188      */
 189     public abstract int getPreferredGap(JComponent component1,
 190                                         JComponent component2,
 191                                         ComponentPlacement type, int position,
 192                                         Container parent);
 193 
 194     /**
 195      * Returns the amount of space to place between the component and specified
 196      * edge of its parent.
 197      *
 198      * @param component the <code>JComponent</code> being positioned
 199      * @param position the position <code>component</code> is being placed
 200      *        relative to its parent; one of
 201      *        <code>SwingConstants.NORTH</code>,
 202      *        <code>SwingConstants.SOUTH</code>,
 203      *        <code>SwingConstants.EAST</code> or
 204      *        <code>SwingConstants.WEST</code>
 205      * @param parent the parent of <code>component</code>; this may differ
 206      *        from the actual parent and may be <code>null</code>
 207      * @return the amount of space to place between the component and specified
 208      *         edge
 209      * @throws IllegalArgumentException if <code>position</code> is not
 210      *         one of <code>SwingConstants.NORTH</code>,
 211      *         <code>SwingConstants.SOUTH</code>,
 212      *         <code>SwingConstants.EAST</code> or
 213      *         <code>SwingConstants.WEST</code>
 214      */
 215     public abstract int getContainerGap(JComponent component, int position,
 216                                         Container parent);
 217 }
--- EOF ---