1 /*
2 * Copyright (c) 2009, 2014, 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 package javafx.scene.layout;
27
28 import java.util.ArrayList;
29 import java.util.Collections;
30 import java.util.List;
31 import javafx.beans.property.ObjectProperty;
32 import javafx.css.CssMetaData;
33 import javafx.css.StyleableObjectProperty;
34 import javafx.css.StyleableProperty;
35 import javafx.geometry.Insets;
36 import javafx.geometry.Orientation;
37 import javafx.geometry.Pos;
38 import javafx.geometry.VPos;
39 import javafx.scene.Node;
40 import javafx.css.converter.EnumConverter;
41 import javafx.css.Styleable;
42 import javafx.geometry.HPos;
43 import javafx.util.Callback;
44
45 /**
46 *
47 * StackPane lays out its children in a back-to-front stack.
48 * <p>
49 * The z-order of the children is defined by the order of the children list
50 * with the 0th child being the bottom and last child on top. If a border and/or
51 * padding have been set, the children will be layed out within those insets.
52 * <p>
53 * The stackpane will attempt to resize each child to fill its content area.
54 * If the child could not be sized to fill the stackpane (either because it was
55 * not resizable or its max size prevented it) then it will be aligned within
56 * the area using the alignment property, which defaults to Pos.CENTER.
57 * <p>
58 * StackPane example:
59 * <pre><code> StackPane stack = new StackPane();
60 * stack.getChildren().addAll(new Rectangle(100,100,Color.BLUE), new Label("Go!));
61 * </code></pre>
62 * <p>
63 * StackPane lays out each managed child regardless of the child's
64 * visible property value; unmanaged children are ignored.</p>
65 * <p>
66 * StackPane may be styled with backgrounds and borders using CSS. See
67 * {@link javafx.scene.layout.Region Region} for details.</p>
68 *
69 * <h4>Resizable Range</h4>
70 *
71 * A stackpane's parent will resize the stackpane within the stackpane's resizable range
72 * during layout. By default the stackpane computes this range based on its content
73 * as outlined in the table below.
74 * <p>
75 * <table border="1">
76 * <tr><td></td><th>width</th><th>height</th></tr>
77 * <tr><th>minimum</th>
78 * <td>left/right insets plus the largest of the children's min widths.</td>
79 * <td>top/bottom insets plus the largest of the children's min heights.</td></tr>
80 * <tr><th>preferred</th>
81 * <td>left/right insets plus the largest of the children's pref widths.</td>
82 * <td>top/bottom insets plus the largest of the children's pref heights.</td></tr>
83 * <tr><th>maximum</th>
84 * <td>Double.MAX_VALUE</td><td>Double.MAX_VALUE</td></tr>
85 * </table>
86 * <p>
87 * A stackpane's unbounded maximum width and height are an indication to the parent that
88 * it may be resized beyond its preferred size to fill whatever space is assigned
89 * to it.
90 * <p>
91 * StackPane provides properties for setting the size range directly. These
92 * properties default to the sentinel value USE_COMPUTED_SIZE, however the
93 * application may set them to other values as needed:
94 * <pre><code> // ensure stackpane is never resized beyond it's preferred size
95 * <b>stackpane.setMaxSize(Region.USE_PREF_SIZE, Region.USE_PREF_SIZE);</b>
96 * </code></pre>
97 * Applications may restore the computed values by setting these properties back
98 * to USE_COMPUTED_SIZE.
99 *
100 * <p>
101 * StackPane does not clip its content by default, so it is possible that childrens'
102 * bounds may extend outside its own bounds if a child's min size prevents it from
103 * being fit within the stackpane.</p>
104 *
105 * <h4>Optional Layout Constraints</h4>
106 *
107 * An application may set constraints on individual children to customize StackPane's layout.
108 * For each constraint, StackPane provides a static method for setting it on the child.
109 * <p>
110 * <table border="1">
111 * <tr><th>Constraint</th><th>Type</th><th>Description</th></tr>
112 * <tr><td>alignment</td><td>javafx.geometry.Pos</td><td>The alignment of the child within the stackpane.</td></tr>
113 * <tr><td>margin</td><td>javafx.geometry.Insets</td><td>Margin space around the outside of the child.</td></tr>
114 * </table>
115 * <p>
116 * Examples:
117 * <pre><code> // Align the title Label at the bottom-center of the stackpane
118 * Label title = new Label();
119 * <b>StackPane.setAlignment(title, Pos.BOTTOM_CENTER);</b>
120 * stackpane.getChildren.addAll(new ImageView(...), title);
121 *
122 * // Create an 8 pixel margin around a listview in the stackpane
123 * ListView list = new ListView();
124 * <b>StackPane.setMargin(list, new Insets(8,8,8,8);</b>
125 * stackpane.getChildren().add(list);
126 * </code></pre>
127 *
128 * @since JavaFX 2.0
129 */
130
131 public class StackPane extends Pane {
132
133 private boolean biasDirty = true;
134 private boolean performingLayout = false;
135 private Orientation bias;
136
137 /********************************************************************
138 * BEGIN static methods
139 ********************************************************************/
140
141 private static final String MARGIN_CONSTRAINT = "stackpane-margin";
142 private static final String ALIGNMENT_CONSTRAINT = "stackpane-alignment";
143
144 /**
145 * Sets the alignment for the child when contained by a stackpane.
146 * If set, will override the stackpane's default alignment.
147 * Setting the value to null will remove the constraint.
148 * @param child the child node of a stackpane
149 * @param value the alignment position for the child
150 */
151 public static void setAlignment(Node child, Pos value) {
152 setConstraint(child, ALIGNMENT_CONSTRAINT, value);
153 }
154
155 /**
156 * Returns the child's alignment constraint if set.
157 * @param child the child node of a stackpane
158 * @return the alignment position for the child or null if no alignment was set
159 */
160 public static Pos getAlignment(Node child) {
161 return (Pos)getConstraint(child, ALIGNMENT_CONSTRAINT);
162 }
163
164 /**
165 * Sets the margin for the child when contained by a stackpane.
166 * If set, the stackpane will layout the child with the margin space around it.
167 * Setting the value to null will remove the constraint.
168 * @param child the child node of a stackpane
169 * @param value the margin of space around the child
170 */
171 public static void setMargin(Node child, Insets value) {
172 setConstraint(child, MARGIN_CONSTRAINT, value);
173 }
174
175 /**
176 * Returns the child's margin constraints if set.
177 * @param child the child node of a stackpane
178 * @return the margin for the child or null if no margin was set
179 */
180 public static Insets getMargin(Node child) {
181 return (Insets)getConstraint(child, MARGIN_CONSTRAINT);
182 }
183
184 private static final Callback<Node, Insets> marginAccessor = n -> getMargin(n);
185
186 /**
187 * Removes all stackpane constraints from the child node.
188 * @param child the child node
189 */
190 public static void clearConstraints(Node child) {
191 setAlignment(child, null);
192 setMargin(child, null);
193 }
194 /********************************************************************
195 * END static methods
196 ********************************************************************/
197
198 /**
199 * Creates a StackPane layout with default CENTER alignment.
200 */
201 public StackPane() {
202 super();
203 }
204
205 /**
206 * Creates a StackPane layout with default CENTER alignment.
207 * @param children The initial set of children for this pane.
208 * @since JavaFX 8.0
209 */
210 public StackPane(Node... children) {
211 super();
212 getChildren().addAll(children);
213 }
214
215 /**
216 * The default alignment of children within the stackpane's width and height.
217 * This may be overridden on individual children by setting the child's
218 * alignment constraint.
219 */
220 public final ObjectProperty<Pos> alignmentProperty() {
221 if (alignment == null) {
222 alignment = new StyleableObjectProperty<Pos>(Pos.CENTER) {
223 @Override
224 public void invalidated() {
225 requestLayout();
226 }
227
228 @Override
229 public CssMetaData<StackPane, Pos> getCssMetaData() {
230 return StyleableProperties.ALIGNMENT;
231 }
232
233 @Override
234 public Object getBean() {
235 return StackPane.this;
236 }
237
238 @Override
239 public String getName() {
240 return "alignment";
241 }
242 };
243 }
244 return alignment;
245 }
246
247 private ObjectProperty<Pos> alignment;
248 public final void setAlignment(Pos value) { alignmentProperty().set(value); }
249 public final Pos getAlignment() { return alignment == null ? Pos.CENTER : alignment.get(); }
250 private Pos getAlignmentInternal() {
251 Pos localPos = getAlignment();
252 return localPos == null ? Pos.CENTER : localPos;
253 }
254
255 /**
256 *
257 * @return the first non-null contentBias of its managed children or null if no managed children
258 * have a content bias.
259 */
260 @Override public Orientation getContentBias() {
261 if (biasDirty) {
262 bias = null;
263 final List<Node> children = getManagedChildren();
264 for (Node child : children) {
265 Orientation contentBias = child.getContentBias();
266 if (contentBias != null) {
267 bias = contentBias;
268 if (contentBias == Orientation.HORIZONTAL) {
269 break;
270 }
271 }
272 }
273 biasDirty = false;
274 }
275 return bias;
276 }
277
278 @Override protected double computeMinWidth(double height) {
279 List<Node>managed = getManagedChildren();
280 return getInsets().getLeft() +
281 computeMaxMinAreaWidth(managed, marginAccessor, height, true) +
282 getInsets().getRight();
283 }
284
285 @Override protected double computeMinHeight(double width) {
286 List<Node>managed = getManagedChildren();
287 return getInsets().getTop() +
288 computeMaxMinAreaHeight(managed, marginAccessor, getAlignmentInternal().getVpos(), width) +
289 getInsets().getBottom();
290 }
291
292 @Override protected double computePrefWidth(double height) {
293 List<Node>managed = getManagedChildren();
294 Insets padding = getInsets();
295 return padding.getLeft() +
296 computeMaxPrefAreaWidth(managed, marginAccessor,
297 (height == -1) ? -1 : (height - padding.getTop() - padding.getBottom()), true) +
298 padding.getRight();
299 }
300
301 @Override protected double computePrefHeight(double width) {
302 List<Node>managed = getManagedChildren();
303 Insets padding = getInsets();
304 return padding.getTop() +
305 computeMaxPrefAreaHeight(managed, marginAccessor,
306 (width == -1) ? -1 : (width - padding.getLeft() - padding.getRight()),
307 getAlignmentInternal().getVpos()) +
308 padding.getBottom();
309 }
310
311
312 @Override public void requestLayout() {
313 if (performingLayout) {
314 return;
315 }
316 biasDirty = true;
317 bias = null;
318 super.requestLayout();
319 }
320
321 @Override protected void layoutChildren() {
322 performingLayout = true;
323 List<Node> managed = getManagedChildren();
324 Pos align = getAlignmentInternal();
325 HPos alignHpos = align.getHpos();
326 VPos alignVpos = align.getVpos();
327 final double width = getWidth();
328 double height = getHeight();
329 double top = getInsets().getTop();
330 double right = getInsets().getRight();
331 double left = getInsets().getLeft();
332 double bottom = getInsets().getBottom();
333 double contentWidth = width - left - right;
334 double contentHeight = height - top - bottom;
335 double baselineOffset = alignVpos == VPos.BASELINE ?
336 getAreaBaselineOffset(managed, marginAccessor, i -> width, contentHeight, true)
337 : 0;
338 for (int i = 0, size = managed.size(); i < size; i++) {
339 Node child = managed.get(i);
340 Pos childAlignment = StackPane.getAlignment(child);
341 layoutInArea(child, left, top,
342 contentWidth, contentHeight,
343 baselineOffset, getMargin(child),
344 childAlignment != null? childAlignment.getHpos() : alignHpos,
345 childAlignment != null? childAlignment.getVpos() : alignVpos);
346 }
347 performingLayout = false;
348 }
349
350 /***************************************************************************
351 * *
352 * Stylesheet Handling *
353 * *
354 **************************************************************************/
355
356 /**
357 * Super-lazy instantiation pattern from Bill Pugh.
358 * @treatAsPrivate implementation detail
359 */
360 private static class StyleableProperties {
361 private static final CssMetaData<StackPane,Pos> ALIGNMENT =
362 new CssMetaData<StackPane,Pos>("-fx-alignment",
363 new EnumConverter<Pos>(Pos.class),
364 Pos.CENTER) {
365
366 @Override
367 public boolean isSettable(StackPane node) {
368 return node.alignment == null ||
369 !node.alignment.isBound();
370 }
371
372 @Override
373 public StyleableProperty<Pos> getStyleableProperty(StackPane node) {
374 return (StyleableProperty<Pos>)node.alignmentProperty();
375 }
376 };
377
378 private static final List<CssMetaData<? extends Styleable, ?>> STYLEABLES;
379 static {
380 final List<CssMetaData<? extends Styleable, ?>> styleables =
381 new ArrayList<CssMetaData<? extends Styleable, ?>>(Region.getClassCssMetaData());
382 styleables.add(ALIGNMENT);
383 STYLEABLES = Collections.unmodifiableList(styleables);
384 }
385 }
386
387 /**
388 * @return The CssMetaData associated with this class, which may include the
389 * CssMetaData of its super classes.
390 * @since JavaFX 8.0
391 */
392 public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {
393 return StyleableProperties.STYLEABLES;
394 }
395
396 /**
397 * {@inheritDoc}
398 *
399 * @since JavaFX 8.0
400 */
401
402
403 @Override
404 public List<CssMetaData<? extends Styleable, ?>> getCssMetaData() {
405 return getClassCssMetaData();
406 }
407
408 }