1 <!doctype html> 2 3 <!-- 4 /* 5 * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved. 6 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 7 * 8 * This code is free software; you can redistribute it and/or modify it 9 * under the terms of the GNU General Public License version 2 only, as 10 * published by the Free Software Foundation. Oracle designates this 11 * particular file as subject to the "Classpath" exception as provided 12 * by Oracle in the LICENSE file that accompanied this code. 13 * 14 * This code is distributed in the hope that it will be useful, but WITHOUT 15 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 16 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 17 * version 2 for more details (a copy is included in the LICENSE file that 18 * accompanied this code). 19 * 20 * You should have received a copy of the GNU General Public License version 21 * 2 along with this work; if not, write to the Free Software Foundation, 22 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 23 * 24 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 25 * or visit www.oracle.com if you need additional information or have any 26 * questions. 27 */ 28 --> 29 30 <html> 31 <head> 32 <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"> 33 <title>javafx.scene.layout</title> 34 </head> 35 <body> 36 <p> 37 Provides classes to support user interface layout. 38 Each layout pane class supports a different layout strategy for its children 39 and applications may nest these layout panes to achieve the needed layout structure 40 in the user interface. Once a node is added to one of the layout panes, 41 the pane will automatically manage the layout for the node, so the application 42 should not position or resize the node directly; see "Node Resizability" 43 for more details. 44 </p> 45 46 <h3>Scene Graph Layout Mechanism</h3> 47 <p> 48 The scene graph layout mechanism is driven automatically by the system once 49 the application creates and displays a {@link javafx.scene.Scene Scene}. 50 The scene graph detects dynamic node changes which affect layout (such as a 51 change in size or content) and calls {@code requestLayout()}, which marks that 52 branch as needing layout so that on the next pulse, a top-down layout pass is 53 executed on that branch by invoking {@code layout()} on that branch's root. 54 During that layout pass, the {@code layoutChildren()} callback method will 55 be called on each parent to layout its children. This mechanism is designed 56 to maximize layout efficiency by ensuring multiple layout requests are coalesced 57 and processed in a single pass rather than executing re-layout on on each minute 58 change. Therefore, applications should not invoke layout directly on nodes. 59 </p> 60 61 62 <h3>Node Resizability</h3> 63 <p> 64 The scene graph supports both resizable and non-resizable node classes. The 65 {@code isResizable()} method on {@link javafx.scene.Node Node} returns whether a 66 given node is resizable or not. {@literal A resizable node class is one which supports a range 67 of acceptable sizes (minimum <= preferred <= maximum), allowing its parent to resize 68 it within that range during layout, given the parent's own layout policy and the 69 layout needs of sibling nodes.} Node supports the following methods for layout code 70 to determine a node's resizable range: 71 <pre><code> 72 public Orientation getContentBias() 73 public double minWidth(double height) 74 public double minHeight(double width) 75 public double prefWidth(double height) 76 public double prefHeight(double width) 77 public double maxWidth(double height) 78 public double maxHeight(double width) 79 </code></pre> 80 <p> 81 Non-resizable node classes, on the other hand, do <em>not</em> have a consistent 82 resizing API and so are <em>not</em> resized by their parents during layout. 83 Applications must establish the size of non-resizable nodes by setting 84 appropriate properties on each instance. These classes return their current layout bounds for 85 min, pref, and max, and the {@code resize()} method becomes a no-op.</p> 86 <p> 87 <br>Resizable classes: {@link javafx.scene.layout.Region Region}, {@link javafx.scene.control.Control Control}, {@link javafx.scene.web.WebView WebView} 88 <br>Non-Resizable classes: {@link javafx.scene.Group Group}, {@link javafx.scene.shape.Shape Shape}, {@link javafx.scene.text.Text Text} 89 </p> 90 <p> 91 For example, a Button control (resizable) computes its min, pref, and max sizes 92 which its parent will use to resize it during layout, so the application only needs 93 to configure its content and properties: 94 95 <pre><code> Button button = new Button("Apply"); 96 </code></pre> 97 However, a Circle (non-resizable) cannot be resized by its parent, so the application 98 needs to set appropriate geometric properties which determine its size: 99 100 <pre><code> Circle circle = new Circle(); 101 circle.setRadius(50); 102 </code></pre> 103 104 <h3>Resizable Range</h3> 105 106 Each resizable node class computes an appropriate min, pref, and max size based 107 on its own content and property settings (it's 'intrinsic' size range). 108 Some resizable classes have an unbounded max size (all layout panes) while 109 others have a max size that is clamped by default to their preferred size (buttons) 110 (See individual class documentation for the default range of each class). 111 While these defaults are geared towards common usage, applications often need 112 to explicitly alter or set a node's resizable range to achieve certain layouts. 113 The resizable classes provide properties for overriding the min, pref and max 114 sizes for this purpose. 115 <p>For example, to override the preferred size of a ListView:</p> 116 <pre><code> listview.setPrefSize(200,300); 117 </code></pre> 118 <p>Or, to change the max width of a button so it will resize wider to fill a space: 119 <pre><code> button.setMaxWidth(Double.MAX_VALUE); 120 </code></pre> 121 <p>For the inverse case, where the application needs to clamp the node's min 122 or max size to its preferred: 123 <pre><code> listview.setMaxSize(Region.USE_PREF_SIZE, Region.USE_PREF_SIZE); 124 </code></pre> 125 And finally, if the application needs to restore the intrinsically computed values: 126 <pre><code> listview.setPrefSize(Region.USE_COMPUTED_SIZE, Region.USE_COMPUTED_SIZE); 127 </code></pre> 128 129 <h3>CSS Styling and Node Sizing</h3> 130 131 Applications cannot reliably query the bounds of a resizable node until it has been 132 added to a scene because the size of that node may be dependent on CSS. This is 133 because CSS is used to style many aspects of a node which affect it's preferred size 134 (font, padding, borders, etc) and so the node cannot be laied out (resized) until 135 CSS has been applied and the parent can access valid size range metrics. 136 This is always true for Controls (and any panes that contain them), because they 137 rely on CSS for their default style, even if no user-level style sheets have been set. 138 Stylesheets are set at the Scene level, which means that styles cannot even 139 be determined until a node's enclosing scene has been initialized. Once a Scene 140 is initialized, CSS is applied to nodes on each pulse (when needed) just before 141 the layout pass. 142 143 144 145 <h3>Visual Bounds vs. Layout Bounds</h3> 146 147 A graphically rich user interface often has the need to make a distinction between 148 a node's visual bounds and the bounds used for layout. For example, the tight visual 149 bounds of a Text node's character glyphs would not work for layout, as the text 150 would not be aligned and leading/trailing whitespace would be discounted. Also, 151 sometimes applications wish to apply affects and transforms to nodes without 152 disturbing the surrounding layout (bouncing, jiggling, drop shadows, glows, etc). 153 To support this distinction in the scene graph, {@link javafx.scene.Node Node} 154 provides the {@code layoutBounds} property to define the 'logical' bounds 155 of the node for layout and {@code boundsInParent} to define the visual bounds 156 once all effects, clipping, and transforms have been applied. 157 158 <p>These two bounds properties will often differ for a given node and 159 {@code layoutBounds} is computed differently depending on the node class: 160 161 <table border="1"> 162 <caption>Bounds Computation Table</caption> 163 <thead> 164 <tr> 165 <th scope="col">Node Type</th> 166 <th scope="col">Layout Bounds</th> 167 </tr> 168 </thead> 169 <tbody> 170 <tr> 171 <th scope="row">{@link javafx.scene.shape.Shape Shape},{@link javafx.scene.image.ImageView ImageView}</th> 172 <td>Includes geometric bounds (geometry plus stroke). 173 Does NOT include effect, clip, or any transforms. 174 </td> 175 </tr> 176 <tr> 177 <th scope="row">{@link javafx.scene.text.Text Text}</th> 178 <td>logical bounds based on the font height and content width, including white space. 179 can be configured to be tight bounds around chars glyphs by setting {@code boundsType}. 180 Does NOT include effect, clip, or any transforms. 181 </td> 182 </tr> 183 <tr> 184 <th scope="row">{@link javafx.scene.layout.Region Region}, {@link javafx.scene.control.Control Control}, {@link javafx.scene.web.WebView WebView}</th> 185 <td>always {@code [0,0 width x height]} regardless of visual bounds, 186 which might be larger or smaller than layout bounds. 187 </td> 188 </tr> 189 <tr> 190 <th scope="row">{@link javafx.scene.Group Group}</th> 191 <td>Union of all visible children's visual bounds ({@code boundsInParent}) 192 Does NOT include effect, clip, or transforms set directly on group, 193 however DOES include effect, clip, transforms set on individual children since 194 those are included in the child's {@code boundsInParent}. 195 </td> 196 </tr> 197 </tbody> 198 </table> 199 <p> 200 So for example, if a {@link javafx.scene.effect.DropShadow DropShadow} is added to a shape, 201 that shadow will <em>not</em> be factored into layout by default. Or, if a 202 {@link javafx.animation.ScaleTransition ScaleTransition} is used to 203 pulse the size of a button, that pulse animation will not disturb layout around 204 that button. If an application wishes to have the effect, clip, or transform 205 factored into the layout of a node, it should wrap that node in a Group. 206 </p> 207 208 </body> 209 </html>