12.6. Layout Panes

The HBox object at the root of ExampleApp's scene graph is an example of a layout pane. A layout pane is a container node that automatically positions (and sometimes resizes) its children. The JavaFX layout panes are in the javafx.scene.layout package, and you can find links to commonly used ones in the "RE: Layout Panes" section of the JavaFX Bookmarks and Notes page. Let's change how root lays out the Text and Button objects that you added to ExampleApp in the previous section.

After the previous section, the scene graph for ExampleApp looks like this:

@startmindmap
top to bottom direction
skinparam defaultFontName monospaced
<style>
  node {
    HorizontalAlignment center
  }
</style>

*:[[https://javadoc.io/doc/org.openjfx/javafx-base/25.0.2/javafx.graphics/javafx/scene/layout/HBox.html{javafx.scene.layout.HBox} HBox]]
root;
**:[[https://javadoc.io/doc/org.openjfx/javafx-base/25.0.2/javafx.graphics/javafx/scene/text/Text.html{javafx.scene.text.Text} Text]]
hello;
**:[[https://javadoc.io/doc/org.openjfx/javafx-base/25.0.2/javafx.controls/javafx/scene/control/Button.html{javafx.scene.control.Button} Button]]
button;
@endmindmap

@startmindmap
top to bottom direction
skinparam defaultFontName monospaced
<style>
  node {
    HorizontalAlignment center
  }
</style>

*:[[https://javadoc.io/doc/org.openjfx/javafx-base/25.0.2/javafx.graphics/javafx/scene/layout/HBox.html{javafx.scene.layout.HBox} HBox]]
root;
**:[[https://javadoc.io/doc/org.openjfx/javafx-base/25.0.2/javafx.graphics/javafx/scene/text/Text.html{javafx.scene.text.Text} Text]]
hello;
**:[[https://javadoc.io/doc/org.openjfx/javafx-base/25.0.2/javafx.controls/javafx/scene/control/Button.html{javafx.scene.control.Button} Button]]
button;
@endmindmap

Fig. 12.5 Scene Graph: ExampleApp with a Button [svg] [png]

The mockups below show the app after a fresh launch, before the button is clicked. The macOS frames are illustrative; fonts and window decorations may vary by system. The last two mockups use an enlarged window to make the alignment easier to see.

  1. Compile ExampleApp.java, then rerun ExampleDriver. Look closely at the app. The text and the button are right next to each other, and they touch the edges of the window. Also notice that the top of the text lines up with the top of the button.

    An "ExampleApp!" window with "Hello, World!!!" directly beside a "Click me!" button, aligned at the top with no spacing or padding.

    Fig. 12.6 Notice the lack of space between the text and the button or around the row.

  2. An HBox places its children in a single horizontal row. By default, it does not put any space between its children. Add the following line immediately after the line that creates the HBox object in the constructor:

    this.root.setSpacing(10);
    

    This sets the amount of horizontal space (in pixels) that root leaves between each of its children. Compile ExampleApp.java, then rerun ExampleDriver. You should see a gap between the text and the button.

    An "ExampleApp!" window with "Hello, World!!!" to the left of a "Click me!" button, with a gap between them and no padding around the row.

    Fig. 12.7 A gap of 10 pixels separates the text and the button.

  3. The spacing does not add any space between the children and the edges of the HBox. That space is called padding. Import the javafx.graphics/javafx.geometry.Insets class, then add the following line immediately after the line you added in the previous step:

    this.root.setPadding(new Insets(10));
    

    An Insets object describes a set of inside offsets for the 4 sides of a rectangular area. The constructor that we used gives all 4 sides the same offset. There is also a constructor that lets you specify the top, right, bottom, and left offsets separately. Compile ExampleApp.java, then rerun ExampleDriver. You should now see space between the edges of the window and the nodes inside of it.

    An "ExampleApp!" window with "Hello, World!!!" to the left of a "Click me!" button, with a gap between them and padding around the row.

    Fig. 12.8 Padding adds 10 pixels of space around the row while keeping the gap between the children.

  4. The alignment of an HBox determines where its children are placed inside of it. The default alignment is Pos.TOP_LEFT, which is why the top of the text lines up with the top of the button. Import the javafx.graphics/javafx.geometry.Pos enum, then add the following line immediately after the line you added in the previous step:

    this.root.setAlignment(Pos.CENTER);
    

    Compile ExampleApp.java, then rerun ExampleDriver. The text should now be vertically centered next to the button. Make the window larger by dragging one of its corners. The text and the button should stay together in the center of the window.

    An enlarged "ExampleApp!" window with "Hello, World!!!" to the left of a "Click me!" button, vertically aligned and centered together in the window.

    Fig. 12.9 After enlarging the window, notice how the row stays centered.

  5. Let's see what happens if we use a different layout pane. Import the javafx.graphics/javafx.scene.layout.VBox class, then change the declared type of the root instance variable:

    private VBox root;
    

    In the constructor, change the assignment to root so that it creates a VBox object instead:

    this.root = new VBox();
    

    A VBox places its children in a single vertical column. It also has setSpacing, setPadding, and setAlignment methods, so the lines you added in the previous steps still compile. Compile ExampleApp.java, then rerun ExampleDriver. You should see the button below the text. The spacing is now vertical instead of horizontal. Make the window larger if needed to compare the centered column with the centered row in the previous step.

    An enlarged "ExampleApp!" window with "Hello, World!!!" above a "Click me!" button, horizontally aligned and centered together in the window.

    Fig. 12.10 The children now form a centered column. The spacing and padding are still 10 pixels.

  6. Change the declared type of root back to HBox and change the constructor assignment back to this.root = new HBox(); before you continue. Remember to compile ExampleApp.java and rerun ExampleDriver to make sure that your app looks the way it did at the end of the step where you set the alignment.

Example: Letting a Child Grow with HBox.setHgrow

If you make the ExampleApp window wider, neither the text nor the button gets wider. A Text object is not resizable, and by default, the maximum width of a Button object is its preferred width. Some nodes, like a javafx.controls/javafx.scene.control.TextField, can grow. If an HBox is wider than its children need, then you can tell it to give the extra horizontal space to a particular child by calling the static HBox.setHgrow method:

TextField urlField = new TextField("https://");
Button loadButton = new Button("Load");
HBox urlBar = new HBox(10, urlField, loadButton);
HBox.setHgrow(urlField, Priority.ALWAYS);

Here, the HBox constructor sets the spacing to 10 and adds both children. When urlBar is wider than its children need, the TextField grows to fill the extra space, and the Button stays the same width. The VBox class has a similar static setVgrow method.

Imports

  • javafx.scene.control.Button

  • javafx.scene.control.TextField

  • javafx.scene.layout.HBox

  • javafx.scene.layout.Priority