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 */ setInstance(LayoutStyle style)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 */ getInstance()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 */ LayoutStyle()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 */ getPreferredGap(JComponent component1, JComponent component2, ComponentPlacement type, int position, Container parent)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 */ getContainerGap(JComponent component, int position, Container parent)215 public abstract int getContainerGap(JComponent component, int position, 216 Container parent); 217 } 218