1 /*
2 * Copyright (c) 2009, 2017, 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 * }</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 * <h3>Resizable Range</h3>
70 *
71 * <p>
72 * A stackpane's parent will resize the stackpane within the stackpane's resizable range
73 * during layout. By default the stackpane computes this range based on its content
74 * as outlined in the table below.
75 * </p>
76 *
77 * <table border="1">
78 * <caption>StackPane Resize Table</caption>
79 * <tr><td></td><th scope="col">width</th><th scope="col">height</th></tr>
80 * <tr><th scope="row">minimum</th>
81 * <td>left/right insets plus the largest of the children's min widths.</td>
82 * <td>top/bottom insets plus the largest of the children's min heights.</td></tr>
83 * <tr><th scope="row">preferred</th>
84 * <td>left/right insets plus the largest of the children's pref widths.</td>
85 * <td>top/bottom insets plus the largest of the children's pref heights.</td></tr>
86 * <tr><th scope="row">maximum</th>
87 * <td>Double.MAX_VALUE</td><td>Double.MAX_VALUE</td></tr>
88 * </table>
89 * <p>
90 * A stackpane's unbounded maximum width and height are an indication to the parent that
91 * it may be resized beyond its preferred size to fill whatever space is assigned
92 * to it.
93 * <p>
94 * StackPane provides properties for setting the size range directly. These
95 * properties default to the sentinel value USE_COMPUTED_SIZE, however the
96 * application may set them to other values as needed:
97 * <pre><code> // ensure stackpane is never resized beyond it's preferred size
98 * <b>stackpane.setMaxSize(Region.USE_PREF_SIZE, Region.USE_PREF_SIZE);</b>
99 * </code></pre>
100 * Applications may restore the computed values by setting these properties back
101 * to USE_COMPUTED_SIZE.
102 *
103 * <p>
104 * StackPane does not clip its content by default, so it is possible that childrens'
105 * bounds may extend outside its own bounds if a child's min size prevents it from
106 * being fit within the stackpane.</p>
107 *
108 * <h3>Optional Layout Constraints</h3>
109 *
110 * <p>
111 * An application may set constraints on individual children to customize StackPane's layout.
112 * For each constraint, StackPane provides a static method for setting it on the child.
113 * </p>
114 *
115 * <table border="1">
116 * <caption>StackPane Constraint Table</caption>
117 * <tr><th>Constraint</th><th scope="col">Type</th><th scope="col">Description</th></tr>
118 * <tr><th scope="row">alignment</th><td>javafx.geometry.Pos</td><td>The alignment of the child within the stackpane.</td></tr>
119 * <tr><th scope="row">margin</th><td>javafx.geometry.Insets</td><td>Margin space around the outside of the child.</td></tr>
120 * </table>
121 * <p>
122 * Examples:
123 * <pre><code> // Align the title Label at the bottom-center of the stackpane
124 * Label title = new Label();
125 * <b>StackPane.setAlignment(title, Pos.BOTTOM_CENTER);</b>
126 * stackpane.getChildren.addAll(new ImageView(...), title);
127 *
128 * // Create an 8 pixel margin around a listview in the stackpane
129 * ListView list = new ListView();
130 * <b>StackPane.setMargin(list, new Insets(8,8,8,8);</b>
131 * stackpane.getChildren().add(list);
132 * </code></pre>
133 *
134 * @since JavaFX 2.0
135 */
136
137 public class StackPane extends Pane {
138
139 private boolean biasDirty = true;
140 private Orientation bias;
141
142 /********************************************************************
143 * BEGIN static methods
144 ********************************************************************/
145
146 private static final String MARGIN_CONSTRAINT = "stackpane-margin";
147 private static final String ALIGNMENT_CONSTRAINT = "stackpane-alignment";
148
149 /**
150 * Sets the alignment for the child when contained by a stackpane.
151 * If set, will override the stackpane's default alignment.
152 * Setting the value to null will remove the constraint.
153 * @param child the child node of a stackpane
154 * @param value the alignment position for the child
155 */
156 public static void setAlignment(Node child, Pos value) {
157 setConstraint(child, ALIGNMENT_CONSTRAINT, value);
158 }
159
160 /**
161 * Returns the child's alignment constraint if set.
162 * @param child the child node of a stackpane
163 * @return the alignment position for the child or null if no alignment was set
164 */
165 public static Pos getAlignment(Node child) {
166 return (Pos)getConstraint(child, ALIGNMENT_CONSTRAINT);
167 }
168
169 /**
170 * Sets the margin for the child when contained by a stackpane.
171 * If set, the stackpane will layout the child with the margin space around it.
172 * Setting the value to null will remove the constraint.
173 * @param child the child node of a stackpane
174 * @param value the margin of space around the child
175 */
176 public static void setMargin(Node child, Insets value) {
177 setConstraint(child, MARGIN_CONSTRAINT, value);
178 }
179
180 /**
181 * Returns the child's margin constraints if set.
182 * @param child the child node of a stackpane
183 * @return the margin for the child or null if no margin was set
184 */
185 public static Insets getMargin(Node child) {
186 return (Insets)getConstraint(child, MARGIN_CONSTRAINT);
187 }
188
189 private static final Callback<Node, Insets> marginAccessor = n -> getMargin(n);
190
191 /**
192 * Removes all stackpane constraints from the child node.
193 * @param child the child node
194 */
195 public static void clearConstraints(Node child) {
196 setAlignment(child, null);
197 setMargin(child, null);
198 }
199 /********************************************************************
200 * END static methods
201 ********************************************************************/
202
203 /**
204 * Creates a StackPane layout with default CENTER alignment.
205 */
206 public StackPane() {
207 super();
208 }
209
210 /**
211 * Creates a StackPane layout with default CENTER alignment.
212 * @param children The initial set of children for this pane.
213 * @since JavaFX 8.0
214 */
215 public StackPane(Node... children) {
216 super();
217 getChildren().addAll(children);
218 }
219
220 /**
221 * The default alignment of children within the stackpane's width and height.
222 * This may be overridden on individual children by setting the child's
223 * alignment constraint.
224 * @return the alignment of children within this stackpane
225 */
226 public final ObjectProperty<Pos> alignmentProperty() {
227 if (alignment == null) {
228 alignment = new StyleableObjectProperty<Pos>(Pos.CENTER) {
229 @Override
230 public void invalidated() {
231 requestLayout();
232 }
233
234 @Override
235 public CssMetaData<StackPane, Pos> getCssMetaData() {
236 return StyleableProperties.ALIGNMENT;
237 }
238
239 @Override
240 public Object getBean() {
241 return StackPane.this;
242 }
243
244 @Override
245 public String getName() {
246 return "alignment";
247 }
248 };
249 }
250 return alignment;
251 }
252
253 private ObjectProperty<Pos> alignment;
254 public final void setAlignment(Pos value) { alignmentProperty().set(value); }
255 public final Pos getAlignment() { return alignment == null ? Pos.CENTER : alignment.get(); }
256 private Pos getAlignmentInternal() {
257 Pos localPos = getAlignment();
258 return localPos == null ? Pos.CENTER : localPos;
259 }
260
261 /**
262 *
263 * @return the first non-null contentBias of its managed children or null if no managed children
264 * have a content bias.
265 */
266 @Override public Orientation getContentBias() {
267 if (biasDirty) {
268 bias = null;
269 final List<Node> children = getManagedChildren();
270 for (Node child : children) {
271 Orientation contentBias = child.getContentBias();
272 if (contentBias != null) {
273 bias = contentBias;
274 if (contentBias == Orientation.HORIZONTAL) {
275 break;
276 }
277 }
278 }
279 biasDirty = false;
280 }
281 return bias;
282 }
283
284 @Override protected double computeMinWidth(double height) {
285 List<Node>managed = getManagedChildren();
286 return getInsets().getLeft() +
287 computeMaxMinAreaWidth(managed, marginAccessor, height, true) +
288 getInsets().getRight();
289 }
290
291 @Override protected double computeMinHeight(double width) {
292 List<Node>managed = getManagedChildren();
293 return getInsets().getTop() +
294 computeMaxMinAreaHeight(managed, marginAccessor, getAlignmentInternal().getVpos(), width) +
295 getInsets().getBottom();
296 }
297
298 @Override protected double computePrefWidth(double height) {
299 List<Node>managed = getManagedChildren();
300 Insets padding = getInsets();
301 return padding.getLeft() +
302 computeMaxPrefAreaWidth(managed, marginAccessor,
303 (height == -1) ? -1 : (height - padding.getTop() - padding.getBottom()), true) +
304 padding.getRight();
305 }
306
307 @Override protected double computePrefHeight(double width) {
308 List<Node>managed = getManagedChildren();
309 Insets padding = getInsets();
310 return padding.getTop() +
311 computeMaxPrefAreaHeight(managed, marginAccessor,
312 (width == -1) ? -1 : (width - padding.getLeft() - padding.getRight()),
313 getAlignmentInternal().getVpos()) +
314 padding.getBottom();
315 }
316
317
318 @Override public void requestLayout() {
319 biasDirty = true;
320 bias = null;
321 super.requestLayout();
322 }
323
324 @Override protected void layoutChildren() {
325 List<Node> managed = getManagedChildren();
326 Pos align = getAlignmentInternal();
327 HPos alignHpos = align.getHpos();
328 VPos alignVpos = align.getVpos();
329 final double width = getWidth();
330 double height = getHeight();
331 double top = getInsets().getTop();
332 double right = getInsets().getRight();
333 double left = getInsets().getLeft();
334 double bottom = getInsets().getBottom();
335 double contentWidth = width - left - right;
336 double contentHeight = height - top - bottom;
337 double baselineOffset = alignVpos == VPos.BASELINE ?
338 getAreaBaselineOffset(managed, marginAccessor, i -> width, contentHeight, true)
339 : 0;
340 for (int i = 0, size = managed.size(); i < size; i++) {
341 Node child = managed.get(i);
342 Pos childAlignment = StackPane.getAlignment(child);
343 layoutInArea(child, left, top,
344 contentWidth, contentHeight,
345 baselineOffset, getMargin(child),
346 childAlignment != null? childAlignment.getHpos() : alignHpos,
347 childAlignment != null? childAlignment.getVpos() : alignVpos);
348 }
349 }
350
351 /***************************************************************************
352 * *
353 * Stylesheet Handling *
354 * *
355 **************************************************************************/
356
357 /*
358 * Super-lazy instantiation pattern from Bill Pugh.
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 superclasses.
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 }