001 /*
002 * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package javax.swing;
026
027 import java.awt.Container;
028 import javax.swing.plaf.ComponentUI;
029 import sun.awt.AppContext;
030
031 /**
032 * <code>LayoutStyle</code> provides information about how to position
033 * components. This class is primarily useful for visual tools and
034 * layout managers. Most developers will not need to use this class.
035 * <p>
036 * You typically don't set or create a
037 * <code>LayoutStyle</code>. Instead use the static method
038 * <code>getInstance</code> to obtain the current instance.
039 *
040 * @version 1.8, 05/05/07
041 * @since 1.6
042 */
043 public abstract class LayoutStyle {
044 /**
045 * Sets the shared instance of <code>LayoutStyle</code>. Specifying
046 * <code>null</code> results in using the <code>LayoutStyle</code> from
047 * the current <code>LookAndFeel</code>.
048 *
049 * @param style the <code>LayoutStyle</code>, or <code>null</code>
050 * @see #getInstance
051 */
052 public static void setInstance(LayoutStyle style) {
053 synchronized (LayoutStyle.class) {
054 if (style == null) {
055 AppContext.getAppContext().remove(LayoutStyle.class);
056 } else {
057 AppContext.getAppContext()
058 .put(LayoutStyle.class, style);
059 }
060 }
061 }
062
063 /**
064 * Returns the shared instance of <code>LayoutStyle</code>. If an instance
065 * has not been specified in <code>setInstance</code>, this will return
066 * the <code>LayoutStyle</code> from the current <code>LookAndFeel</code>.
067 *
068 * @see LookAndFeel#getLayoutStyle
069 * @return the shared instance of <code>LayoutStyle</code>
070 */
071 public static LayoutStyle getInstance() {
072 LayoutStyle style;
073 synchronized (LayoutStyle.class) {
074 style = (LayoutStyle) AppContext.getAppContext().get(
075 LayoutStyle.class);
076 }
077 if (style == null) {
078 return UIManager.getLookAndFeel().getLayoutStyle();
079 }
080 return style;
081 }
082
083 /**
084 * <code>ComponentPlacement</code> is an enumeration of the
085 * possible ways two components can be placed relative to each
086 * other. <code>ComponentPlacement</code> is used by the
087 * <code>LayoutStyle</code> method <code>getPreferredGap</code>. Refer to
088 * <code>LayoutStyle</code> for more information.
089 *
090 * @see LayoutStyle#getPreferredGap(JComponent,JComponent,
091 * ComponentPlacement,int,Container)
092 * @since 1.6
093 */
094 public enum ComponentPlacement {
095 /**
096 * Enumeration value indicating the two components are
097 * visually related and will be placed in the same parent.
098 * For example, a <code>JLabel</code> providing a label for a
099 * <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 * Creates a new <code>LayoutStyle</code>. You generally don't
128 * create a <code>LayoutStyle</code>. Instead use the method
129 * <code>getInstance</code> to obtain the current
130 * <code>LayoutStyle</code>.
131 */
132 public LayoutStyle() {
133 }
134
135 /**
136 * Returns the amount of space to use between two components.
137 * The return value indicates the distance to place
138 * <code>component2</code> relative to <code>component1</code>.
139 * For example, the following returns the amount of space to place
140 * between <code>component2</code> and <code>component1</code>
141 * when <code>component2</code> is placed vertically above
142 * <code>component1</code>:
143 * <pre>
144 * int gap = getPreferredGap(component1, component2,
145 * ComponentPlacement.RELATED,
146 * SwingConstants.NORTH, parent);
147 * </pre>
148 * The <code>type</code> parameter indicates the relation between
149 * the two components. If the two components will be contained in
150 * the same parent and are showing similar logically related
151 * items, use <code>RELATED</code>. If the two components will be
152 * contained in the same parent but show logically unrelated items
153 * use <code>UNRELATED</code>. Some look and feels may not
154 * distinguish between the <code>RELATED</code> and
155 * <code>UNRELATED</code> types.
156 * <p>
157 * The return value is not intended to take into account the
158 * current size and position of <code>component2</code> or
159 * <code>component1</code>. The return value may take into
160 * consideration various properties of the components. For
161 * example, the space may vary based on font size, or the preferred
162 * size of the component.
163 *
164 * @param component1 the <code>JComponent</code>
165 * <code>component2</code> is being placed relative to
166 * @param component2 the <code>JComponent</code> being placed
167 * @param position the position <code>component2</code> is being placed
168 * relative to <code>component1</code>; one of
169 * <code>SwingConstants.NORTH</code>,
170 * <code>SwingConstants.SOUTH</code>,
171 * <code>SwingConstants.EAST</code> or
172 * <code>SwingConstants.WEST</code>
173 * @param type how the two components are being placed
174 * @param parent the parent of <code>component2</code>; this may differ
175 * from the actual parent and it may be <code>null</code>
176 * @return the amount of space to place between the two components
177 * @throws NullPointerException if <code>component1</code>,
178 * <code>component2</code> or <code>type</code> is
179 * <code>null</code>
180 * @throws IllegalArgumentException if <code>position</code> is not
181 * one of <code>SwingConstants.NORTH</code>,
182 * <code>SwingConstants.SOUTH</code>,
183 * <code>SwingConstants.EAST</code> or
184 * <code>SwingConstants.WEST</code>
185 * @see LookAndFeel#getLayoutStyle
186 * @since 1.6
187 */
188 public abstract int getPreferredGap(JComponent component1,
189 JComponent component2, ComponentPlacement type,
190 int position, Container parent);
191
192 /**
193 * Returns the amount of space to place between the component and specified
194 * edge of its parent.
195 *
196 * @param component the <code>JComponent</code> being positioned
197 * @param position the position <code>component</code> is being placed
198 * relative to its parent; one of
199 * <code>SwingConstants.NORTH</code>,
200 * <code>SwingConstants.SOUTH</code>,
201 * <code>SwingConstants.EAST</code> or
202 * <code>SwingConstants.WEST</code>
203 * @param parent the parent of <code>component</code>; this may differ
204 * from the actual parent and may be <code>null</code>
205 * @return the amount of space to place between the component and specified
206 * edge
207 * @throws IllegalArgumentException if <code>position</code> is not
208 * one of <code>SwingConstants.NORTH</code>,
209 * <code>SwingConstants.SOUTH</code>,
210 * <code>SwingConstants.EAST</code> or
211 * <code>SwingConstants.WEST</code>
212 */
213 public abstract int getContainerGap(JComponent component,
214 int position, Container parent);
215 }
|