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} 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}.  Instead use the static method
  38  * {@code getInstance} 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}.  Specifying
  45      * {@code null} results in using the {@code LayoutStyle} from
  46      * the current {@code LookAndFeel}.
  47      *
  48      * @param style the {@code LayoutStyle}, or {@code null}
  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}.  If an instance
  64      * has not been specified in {@code setInstance}, this will return
  65      * the {@code LayoutStyle} from the current {@code LookAndFeel}.
  66      *
  67      * @see LookAndFeel#getLayoutStyle
  68      * @return the shared instance of {@code LayoutStyle}
  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} is an enumeration of the
  85      * possible ways two components can be placed relative to each
  86      * other.  {@code ComponentPlacement} is used by the
  87      * {@code LayoutStyle} method {@code getPreferredGap}.  Refer to
  88      * {@code LayoutStyle} 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} providing a label for a
  99          * {@code JTextField} is typically visually associated
 100          * with the {@code JTextField}; the constant {@code RELATED}
 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} 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} type.
 119          * <p>
 120          * This value is typically only useful with a direction of
 121          * {@code EAST} or {@code WEST}.
 122          */
 123         INDENT;
 124     }
 125 
 126 
 127     /**
 128      * Creates a new {@code LayoutStyle}.  You generally don't
 129      * create a {@code LayoutStyle}.  Instead use the method
 130      * {@code getInstance} to obtain the current
 131      * {@code LayoutStyle}.
 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} relative to {@code component1}.
 140      * For example, the following returns the amount of space to place
 141      * between {@code component2} and {@code component1}
 142      * when {@code component2} is placed vertically above
 143      * {@code component1}:
 144      * <pre>
 145      *   int gap = getPreferredGap(component1, component2,
 146      *                             ComponentPlacement.RELATED,
 147      *                             SwingConstants.NORTH, parent);
 148      * </pre>
 149      * The {@code type} 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}.  If the two components will be
 153      * contained in the same parent but show logically unrelated items
 154      * use {@code UNRELATED}.  Some look and feels may not
 155      * distinguish between the {@code RELATED} and
 156      * {@code UNRELATED} types.
 157      * <p>
 158      * The return value is not intended to take into account the
 159      * current size and position of {@code component2} or
 160      * {@code component1}.  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}
 166      *               {@code component2} is being placed relative to
 167      * @param component2 the {@code JComponent} being placed
 168      * @param position the position {@code component2} is being placed
 169      *        relative to {@code component1}; one of
 170      *        {@code SwingConstants.NORTH},
 171      *        {@code SwingConstants.SOUTH},
 172      *        {@code SwingConstants.EAST} or
 173      *        {@code SwingConstants.WEST}
 174      * @param type how the two components are being placed
 175      * @param parent the parent of {@code component2}; this may differ
 176      *        from the actual parent and it may be {@code null}
 177      * @return the amount of space to place between the two components
 178      * @throws NullPointerException if {@code component1},
 179      *         {@code component2} or {@code type} is
 180      *         {@code null}
 181      * @throws IllegalArgumentException if {@code position} is not
 182      *         one of {@code SwingConstants.NORTH},
 183      *         {@code SwingConstants.SOUTH},
 184      *         {@code SwingConstants.EAST} or
 185      *         {@code SwingConstants.WEST}
 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} being positioned
 199      * @param position the position {@code component} is being placed
 200      *        relative to its parent; one of
 201      *        {@code SwingConstants.NORTH},
 202      *        {@code SwingConstants.SOUTH},
 203      *        {@code SwingConstants.EAST} or
 204      *        {@code SwingConstants.WEST}
 205      * @param parent the parent of {@code component}; this may differ
 206      *        from the actual parent and may be {@code null}
 207      * @return the amount of space to place between the component and specified
 208      *         edge
 209      * @throws IllegalArgumentException if {@code position} is not
 210      *         one of {@code SwingConstants.NORTH},
 211      *         {@code SwingConstants.SOUTH},
 212      *         {@code SwingConstants.EAST} or
 213      *         {@code SwingConstants.WEST}
 214      */
 215     public abstract int getContainerGap(JComponent component, int position,
 216                                         Container parent);
 217 }
--- EOF ---