HBox

The HBox layout’s job is to place JavaFX child nodes in a horizontal row. As child nodes are added consecutively, each is appended to the end (right side). By default, the HBox layout honors the child’s preferred width and height. When the parent node is not resizable (a Group node, for example), the row height of the HBox takes on the height of the child node with the greatest preferred height. Also, by default each child node aligns to the top-left (Pos.TOP_LEFT) position.

The HBox can be configured to have resizing ranges to allow the parent to manage and calculate space available upon layout requests. There are many ways you can programmatically alter the HBox’s layout constraints, such as border, padding, margin, spacing, and alignment. Although in this chapter you will learn how to set constraints using a programmatic approach, there are also alternative strategies. One well known and preferred strategy is to style or set constraints using JavaFX CSS attributes; you will catch a glimpse of that approach later in this chapter, and more details in Chapter 6, on custom UIs.

When dealing with nonresizable child nodes such as Shape nodes, the parent takes into account the Shape’s rectangular bounds (ParentInBounds), its width and height. In contrast, when using resizable nodes such as a TextField control, the parent has the ability to manage and compute the available space for the TextField to grow horizontally. To grow UI controls horizontally within an HBox, use the static HBox.setHgrow() method. The following code snippet sets a TextField control to grow horizontally when the parent HBox’s width is resized:

TextField myTextField = new TextField()
HBox.setHgrow(myTextField, Priority.ALWAYS);

As an example of an HBox layout in action, the code shown in Listing 4-1 uses four rectangles as child nodes with varying HBox constraints. Nonresizable nodes such as rectangle shapes are used in the example to demonstrate the many spacing attributes for the HBox layout control. For brevity, only the relevant code is listed here. To see the full listing, please visit the Source Code/Download tab of the book’s page at www.apress.com to download the source code.

Listing 4-1. The HBoxExample.java file demonstrates an HBox layout with shapes as child nodes

HBox hbox = new HBox(5);         // space between child nodes only
hbox.setPadding(new Insets(1));  // padding between hbox border and row.

Rectangle r1 = new Rectangle(10, 10); // Square
Rectangle r2 = new Rectangle(20, 20); // Big Square
Rectangle r3 = new Rectangle(5, 20);  // Vertical rectangle
Rectangle r4 = new Rectangle(20, 5);  // Horizontal rectangle

HBox.setMargin(r1, new Insets(2,2,2,2)); // space between border & child node
hbox.getChildren().addAll(r1, r2, r3, r4);

Figure 4-1 is the output of Listing 4-1.

In Listing 4-1 the code begins by instantiating an HBox using the single-argument constructor. This constructor takes a value of type double, which specifies the horizontal space (in pixels) between child nodes. This is also the equivalent of invoking the setSpacing() method. Because spacing, padding, margin, and border can often be confusing I’ve illustrated an HBox in Figure 4-2. The figure displays three gray rectangular areas, each five pixels wide, that represent the spacing between child nodes (r1 to r4). Setting the spacing uses an Insets object that allows you to create space between the HBox’s child nodes. Notice that the inner part of the HBox border has yellow padding one pixel wide surrounding the row.

After creating all four rectangles, the code sets the margin on rectangle r1. To set the margin you’ll notice the static method HBox.setMargin(Node, Insets). The code creates an Insets object with a margin of two pixels for the top, right, bottom, and left. As shown in Figure 4-2, this is the surrounding space around rectangle r1 (blue). To calculate the size of the HBox’s dimensions, you basically add up the spacing, margin, padding, and the child nodes’ bounds (ParentInBounds). When the parent of the HBox is a Group node (not resizable), the HBox width will total 76 pixels and the height 22 pixels.

VBox

The VBox layout is similar to an HBox, except that it places child nodes stacked in a vertical column. As children are added, each is placed beneath the previous child node. By default the VBox honors the children’s preferred width and height. When the parent node is not resizable (for example, a Group node), the maximum vertical column’s width is based on the node with the greatest preferred width. Also, by default each child node aligns to the top-left (Pos.TOP_LEFT) position. VBox layouts can also be configured to have resizing ranges to allow the parent node to manage and calculate space available upon layout requests. To demonstrate the use of a VBox, the example in Listing 4-2 contains the same four rectangles from the previous example, with the same layout constraints.

Listing 4-2. The VBoxExample.java file, demonstrating VBox layout

VBox vbox = new VBox(5);                 // spacing between child nodes
vbox.setPadding(new Insets(1));          // padding between border and child nodes
 
Rectangle r1 = new Rectangle(10, 10);    // little square
Rectangle r2 = new Rectangle(20, 20);    // big square
Rectangle r3 = new Rectangle(5, 20);     // vertical rectangle
Rectangle r4 = new Rectangle(20, 5);     // horizontal rectangle
VBox.setMargin(r1, new Insets(2,2,2,2)); // margin around r1
vbox.getChildren().addAll(r1, r2, r3, r4);

Figure 4-3 shows the output of the VBoxExample.java application in Listing 4-2, demonstrating the VBox layout with rectangle shapes as child nodes.

In Listing 4-2, the code begins by instantiating a VBox with a five-pixel space between child nodes. Figure 4-4 depicts horizontal gray bars that represent the spacing between child nodes (r1 to r4). After constructing the VBox, you set the padding via setPadding() method. Setting the padding by using an Insets object allows you to create padding between the border and the row. Notice in Figure 4-4 the VBox padding of one pixel surrounding the VBox shown surrounded by a yellow line.

Once the four rectangles are created, the code sets the margin on the rectangle r1. To set the margin we use the static method VBox.setMargin(Node, Insets). The code then creates an Insets object with a margin of two pixels for the top, right, bottom, and left. Surrounding rectangle r1 is a two-pixel margin shown in blue. To find the total size of a VBox instance, you simply add up the spacing, margin, padding, and child nodes’ dimensions (bounds). Having a Group as a parent, the VBox node’s calculated width would total 22 pixels, and the height would total 76 pixels.

FlowPane

The FlowPane layout node allows child nodes in a row to flow based on the available horizontal spacing and wraps nodes to the next line when horizontal space is less than the total of all the nodes’ widths. Depicted in Figure 4-5 are four child nodes flowing from left to right and then wrapping.

By default a FlowPane layout flows child nodes from left to right (Pos.TOP_LEFT). To change the flow alignment, you can simply invoke the setAlignment() method by passing in an enumerated value of type Pos. Listing 4-3 creates a FlowPane layout to flow child nodes from right to left (Pos.TOP_RIGHT).

Listing 4-3. The creation of a FlowPane layout to flow from right to left

FlowPane flowPane = new FlowPane();
flowPane.setAlignment(Pos.TOP_RIGHT);
flowPane.getChildren().addAll(...); // child nodes to add.

BorderPane

The BorderPane layout node allows child nodes to be placed in a top, bottom, left, right, or center region. Because each region can only have one node, developers typically nest layouts. An example would be to create an HBox with children to then be set as the top region via the setTop() method. Figure 4-6 shows the BorderPane’s regions.

This layout is similar to many websites we see every day, where navigational links are placed in either the top, bottom, left, or right regions of a page, while the main content is in the center area. A BorderPane’s region of top and bottom borders allows a resizable node to take up all of the available width. The left and right border regions take up the available vertical space between the top and bottom borders. All of the bordering regions honor the children’s sizes (preferred width and height) by default. According to the Javadocs, the default alignment of nodes when placed in the top, bottom, left, right, and center regions is as follows:

• Top: Pos.TOP_LEFT
• Bottom: Pos.BOTTOM_LEFT
• Left: Pos.TOP_LEFT
• Right: Pos.TOP_RIGHT
• Center: Pos.CENTER

GridPane

So far you have learned about simple layouts; now let’s take a look at a more advanced layout: the GridPane, commonly used in business applications. For instance, business applications typically have data entry form screens. Forms usually have read-only labels on the first column and input fields on the second column, resembling a grid pattern.

When using the GridPane you can specify constraints at the row, column, or cell level. For example, if the second column contains input text fields, you may want them to resize as the window is being resized. To lay out components in a grid-like manner, the example in Listing 4-4 uses JavaFX’s GridPane layout. The most interesting part of the example is the use of column constraints on the GridPane. Column constraints apply a minimum and maximum horizontal width for the child nodes to grow or shrink as the window is resized.

Listing 4-4. The GridPaneForm.java file demonstrates the GridPane layout

    @Override
    public void start(Stage primaryStage) {
        primaryStage.setTitle("GridPaneForm ");
        BorderPane root = new BorderPane();
        Scene scene = new Scene(root, 380, 150, Color.WHITE);
 
        GridPane gridpane = new GridPane();
        gridpane.setPadding(new Insets(5));
        gridpane.setHgap(5);
        gridpane.setVgap(5);
        ColumnConstraints column1 = new ColumnConstraints(100);
        ColumnConstraints column2 = new ColumnConstraints(50, 150, 300);
        column2.setHgrow(Priority.ALWAYS);
        gridpane.getColumnConstraints().addAll(column1, column2);
 
        Label fNameLbl = new Label("First Name");
        TextField fNameFld = new TextField();
        Label lNameLbl = new Label("Last Name");
        TextField lNameFld = new TextField();
         
        Button saveButton = new Button("Save");
         
        // First name label
        GridPane.setHalignment(fNameLbl, HPos.RIGHT);
        gridpane.add(fNameLbl, 0, 0);
         
        // Last name label
        GridPane.setHalignment(lNameLbl, HPos.RIGHT);
        gridpane.add(lNameLbl, 0, 1);
         
        // First name field
        GridPane.setHalignment(fNameFld, HPos.LEFT);
        gridpane.add(fNameFld, 1, 0);
         
        // Last name field
        GridPane.setHalignment(lNameFld, HPos.LEFT);
        gridpane.add(lNameFld, 1, 1);
 
        // Save button
        GridPane.setHalignment(saveButton, HPos.RIGHT);
        gridpane.add(saveButton, 1, 2);
         
        FlowPane topBanner = new FlowPane();
        topBanner.setPrefHeight(40);
        String backgroundStyle =
                "-fx-background-color: lightblue;"
              + "-fx-background-radius: 30%;"
              + "-fx-background-inset: 5px;";
        topBanner.setStyle(backgroundStyle);
        SVGPath svgIcon = new SVGPath();
        // icon from http://raphaeljs.com/icons/#people
        svgIcon.setContent(/* svg path code as a string */);
        svgIcon.setStroke(Color.LIGHTGRAY);
        svgIcon.setFill(Color.WHITE);
         
        Text contactText = new Text("Contacts");
        contactText.setFill(Color.WHITE);
         
        Font serif = Font.font("Dialog", 30);
        contactText.setFont(serif);
        topBanner.getChildren().addAll(svgIcon, contactText);
         
        root.setTop(topBanner);
        root.setCenter(gridpane);
         
        primaryStage.setScene(scene);
        primaryStage.show();
    }
}

After executing Listing 4-4 you will see the output in Figure 4-7, which displays a simple form application allowing the user to enter a first and last name as contact information. When resizing the window, notice that the input text field controls grow or shrink based on the column constraints. Also notice that the Save button is horizontally aligned to the right (HPos.RIGHT), just beneath the Last Name text field.

Listing 4-4 begins by creating an instance of a BorderPane object as the root node for our scene. By using a BorderPane as the root node and then placing the GridPane node object into the center region, we enable the parent (BorderPane) to resize the GridPane by giving it all the available horizontal and vertical space. After creating a BorderPane instance as our root node, the code instantiates a GridPane layout with padding along with horizontal and vertical gaps. The code in Listing 4-5 then creates a GridPane layout with padding, horizontal, and vertical gaps set to 5 (pixels).

Listing 4-5. Setting padding, horizontal, and vertical gap spacing between UI controls for each cell

GridPane gridpane = new GridPane();
gridpane.setPadding(new Insets(5));
gridpane.setHgap(5); gridpane.setVgap(5);

Back in Listing 4-4, the code implements column constraints for the first and second columns. To set a column’s constraint, use the ColumnConstraints constructor, which allows the developer to specify minimum, preferred, and maximum widths for a column on the GridPane node. This is very nice; it means that when the parent container node (BorderPane) is being resized, the GridPane will cause its child nodes to grow or shrink horizontally based on its row or column constraints. Listing 4-6 demonstrates the ability to constrain the first column to 100 pixels wide for the read-only labels and the second column with a minimum width of 50, a preferred width of 150 and a maximum width of 300.

Listing 4-6. Setting up column contraints for a JavaFX application

ColumnConstraints column1 = new ColumnConstraints(100);          // fixed for labels
ColumnConstraints column2 = new ColumnConstraints(50, 150, 300); // min,pref,max
column2.setHgrow(Priority.ALWAYS);
gridpane.getColumnConstraints().addAll(column1, column2);

After creating the column constraint for column 2, the code invokes the setHgrow() method by passing in the enum value Priority.ALWAYS, which lets the UI controls take up the available horizontal space within cells when the window is widened. I set the maximum width to 300 for the second column so you can see that the child TextField does not grow beyond the maximum width (300). In other words, when the window is resized wider than 300 pixels, the text fields within the grid pane column stop stretching.

The next step is simply putting each UI control into its respective cell location. All cells are relative to zero; to place a node in the cell in the first column and first row you would specify the cell as (0, 0). Thus, the following code snippet adds the Save button into the second column, third row of the GridPane layout at cell (1, 2):

gridpane.add(saveButton, 1, 2);

The layout also allows you to align controls horizontally or vertically within the cell. The following statement right-aligns the Save button:

GridPane.setHalignment(saveButton, HPos.RIGHT);

After completing the GridPane setup, the code implements the top banner area of the input form shown in Figure 4-7. To create a title banner, we use a flow layout with a background color of light blue, an SVG node icon (people) and a text node (contacts). The important code that relates to the FlowPane layout displaying the banner contains the settings for the preferred height and JavaFX CSS styles. Because the banner (FlowPane) is placed in the top region of the BorderPane layout, the preferred height of 40 pixels will be honored and the width will take up the available horizontal space.

With this knowledge that the FlowPane takes up the available horizontal space, notice the area being filled with the light blue background color. By using JavaFX CSS styling, the code sets a background color of light blue along with corner radii and insets specified using a string. Listing 4-7 is the code section that styles the banner (FlowPane) to be placed in the top region of the BorderPane layout. Don’t worry if JavaFX CSS styling doesn’t make sense yet; a more detailed discussion of it will follow in Chapter 6.

Listing 4-7. Styling a FlowPane layout for the top banner

FlowPane topBanner = new FlowPane();
topBanner.setPrefHeight(40);
String backgroundStyle = "-fx-background-color: lightblue;"
  + "-fx-background-radius: 30%;"
  + "-fx-background-inset: 5px;";
topBanner.setStyle(backgroundStyle);

We’ve only scratched the surface of the GridPane layout. There are other ways to provide constraints and alignment of child nodes, so I trust you will delve deeper into the GridPane layout. Please see the Javadocs documentation for more details. Now that you’ve learned how to use the most common layouts, you will be able to create well-behaved user interfaces. Next, you will explore common JavaFX UI controls.

Menus

Menus are a standard way for windowed desktop applications to allow users to select options. For example, applications typically have a File menu offering options (menu items) to save or open a file. In a windowed environment the user will use their mouse to navigate and select menu items. Menus and menu items typically also have the functionality of key combinations to select options, also known as keyboard shortcuts. In other words, key combinations allow quick menu selections without the need of a mouse.

Creating Menus and Menu Items

Before exploring how to invoke code triggered by selecting menu options, let’s look at how to create menus. For starters, you must create a menu bar (javafx.scene.control.MenuBar) object to hold many javafx.scene.control.Menu objects. Each Menu object is similar to a tree hierarchal structure where Menu objects can contain Menu and javafx.scene.control.MenuItem objects. Thus, a menu may contain other menus as submenus or menus within menus. MenuItems are child options within a Menu object. You can think of MenuItems as leaf nodes (containing no children) in a tree structure. Listing 4-8 shows the creation of a menu bar with a File menu that has a Save option as a menu item.

Listing 4-8. The creation of MenuBar, Menu, and MenuItem instances

MenuBar menuBar = new MenuBar();
Menu fileMenu = new Menu("File");
fileMenu.getItems().add(new MenuItem("Save"));
menuBar.getMenus().add(fileMenu);

Figure 4-8 shows the output of Listing 4-8, a simple File menu containing a Save menu item.

Although you can create simple menu items, you may want more advanced options such as checked options or radio buttons. Based on the inheritance hierarchy, the following are subclasses of the MenuItem class. The following listing shows the available MenuItem subclasses to use as menu options. A brief description of each subclass will follow.

• javafx.scene.control.CheckMenuItem
• javafx.scene.control.RadioMenuItem
• javafx.scene.control.CustomMenuItem
• javafx.scene.control.SeparatorMenuItem
• javafx.scene.control.Menu

A CheckMenuItem menu item is similar to a check box UI control, allowing the user to select items optionally. The RadioMenuItem menu item is similar to the radio button UI control, allowing the user to select only one item from an item group. When you want to create a custom menu item you can use the CustomMenuItem class. For instance, you may want to have a menu option that behaves like a toggle button. Next is a SeparatorMenuItem, which is really a derived class of type CustomMenuItem. A SeparatorMenuItem is a menu item that displays as a visual line to separate menu items. Last in the list is the Menu class. Because a Menu class is a subclass of MenuItem, it has a getItems().add() method that’s capable of adding children such as other Menu and MenuItem instances.

Invoking a Selected MenuItem

Now, that you know how to construct a menus and menu items, let’s see how to invoke code that is attached to a menu item. You’ll be happy to know that you wire-up handler code to a menu item in exactly the same way that you would wire-up JavaFX buttons, which means that menu items also have a setOnAction() method. The setOnAction() method receives a functional interface of type EventHandler<ActionEvent>, which is the handler code that is invoked when the menu item is selected. Listing 4-9 shows two equivalent implementations of action code to be invoked when the Exit menu item is triggered. The first implementation uses an anonymous inner class, and the second uses Java 8’s lambda expressions.

Listing 4-9. Adding handler code via the setOnAction() method

// Implementation that uses an anonymous inner class
exitMenuItem.setOnAction(new EventHandler<ActionEvent>() {
  @Override
  public void handle(ActionEvent t) {
       Platform.exit();
  }
});
// Implementation that uses lambda expressions
exitMenuItem.setOnAction(ae -> Platform.exit());

Example: Working with Menus

To demonstrate various menu selection scenarios, the next example mimics a security alarm application. Listing 4-10 is from the file MenuExample.java and shows the relevant code that demonstrates menu selections. Before executing the code you may want to know how to use this fictitious security alarm application. As illustrated in Figure 4-9, the menu bar displays three main menus: File, Cameras, and Alarm. When the File menu is selected, it displays three options—New, Save, and Exit—as child menu items. Selecting the Cameras menu displays two CheckMenuItem menu items, for the optional selection of Show Camera 1 or Show Camera 2. Lastly, the Alarm menu displays two RadioMenuItem options and a submenu Contingent Plans. The submenu displays three child CheckMenuItem options.

Listing 4-10. The MenuExample.java file is a fictional alarm system application

@Override
public void start(Stage primaryStage) {
    primaryStage.setTitle("Menus Example");
    BorderPane root = new BorderPane();
    Scene scene = new Scene(root, 300, 250, Color.WHITE);
 
    MenuBar menuBar = new MenuBar();
    root.setTop(menuBar);
 
    // File menu - new, save, exit
    Menu fileMenu = new Menu("File");
    MenuItem newMenuItem = new MenuItem("New");
    MenuItem saveMenuItem = new MenuItem("Save");
    MenuItem exitMenuItem = new MenuItem("Exit");
    exitMenuItem.setOnAction(actionEvent -> Platform.exit() );
 
    fileMenu.getItems().addAll(newMenuItem,
            saveMenuItem,
            new SeparatorMenuItem(),
            exitMenuItem
    );
    menuBar.getMenus().add(fileMenu);
 
    // Cameras menu - camera 1, camera 2
    Menu cameraMenu = new Menu("Cameras");
    CheckMenuItem cam1MenuItem = new CheckMenuItem("Show Camera 1");
    cam1MenuItem.setSelected(true);
    cameraMenu.getItems().add(cam1MenuItem);
 
    CheckMenuItem cam2MenuItem = new CheckMenuItem("Show Camera 2");
    cam2MenuItem.setSelected(true);
    cameraMenu.getItems().add(cam2MenuItem);
 
    // Alarm menu
    Menu alarmMenu = new Menu("Alarm");
 
    // sound or turn alarm off
    ToggleGroup tGroup = new ToggleGroup();
    RadioMenuItem soundAlarmItem = new RadioMenuItem("Sound Alarm");
    soundAlarmItem.setToggleGroup(tGroup);
 
    RadioMenuItem stopAlarmItem = new RadioMenuItem("Alarm Off");
    stopAlarmItem.setToggleGroup(tGroup);
    stopAlarmItem.setSelected(true);
 
    alarmMenu.getItems().addAll(soundAlarmItem,
            stopAlarmItem,
            new SeparatorMenuItem());
 
    Menu contingencyPlans = new Menu("Contingent Plans");
    contingencyPlans.getItems().addAll(
            new CheckMenuItem("Self Destruct in T minus 50"),
            new CheckMenuItem("Turn off the coffee machine "),
            new CheckMenuItem("Run for your lives! "));
 
    alarmMenu.getItems().add(contingencyPlans);
 
    menuBar.getMenus().addAll(fileMenu, cameraMenu, alarmMenu);
 
    primaryStage.setScene(scene);
    primaryStage.show();
}

The code begins by creating a MenuBar control, which may contain one to many menu (MenuItem) objects. After the MenuBar is created, it is set as the top region on the BorderPane layout. Since the top region allows a resizable node to take up the available horizontal space, the MenuBar control will stretch to the width of the BorderPane (the root scene). Listing 4-11 sets the top region of the BorderPane to a menu bar.

Listing 4-11. A menu bar is set as the top region node of the root BorderPane

MenuBar menuBar = new MenuBar();
root.setTop(menuBar);

Next, the code instantiates Menu objects that contain one or more menu item (MenuItem) objects and other Menu objects, making submenus.

After creating the File, menu the code creates the Cameras menu. This menu will contain CheckMenuItem objects. These menu items allow the user to optionally select or unselect Show Camera 1 and Show Camera 2 as menu items.

Last is the implementation of our Alarm menu, which contains two radio menu items (RadioMenuItem), a separator (SeparatorMenuItem), and a submenu (Menu). To create the radio menu items for the Alarm menu, the code creates an instance of a ToggleGroup class. The ToggleGroup class is also used on regular radio buttons (RadioButtons) to allow one selected option only. Listing 4-12 creates radio menu items (RadioMenuItems) to be added to the alarmMenu Menu object.

Listing 4-12. The creation of menu items that contain radio and separator menu items

// Alarm menu
Menu alarmMenu = new Menu("Alarm");
 
// sound or turn alarm off
ToggleGroup tGroup = new ToggleGroup();
RadioMenuItem soundAlarmItem = new RadioMenuItem("Sound Alarm");
soundAlarmItem.setToggleGroup(tGroup);
 
RadioMenuItem stopAlarmItem = new RadioMenuItem("Alarm Off");
stopAlarmItem.setToggleGroup(tGroup);
stopAlarmItem.setSelected(true);
 
alarmMenu.getItems().addAll(soundAlarmItem,
        stopAlarmItem,
        new SeparatorMenuItem());

The code also adds a visual separator, by instantiating a SeparatorMenuItem class that is added to a menu via the getItems().addAll() method. The method getItems() returns an observable list of MenuItem objects (ObservableList<MenuItem>). You’ll learn about ObservableList collections later, but briefly, they are collections that have the ability to notify and update UI controls as items are added or removed. For a full description please see the section “The ObservableList Collection Class” later in this chapter.

The last child menu item added to the Alarm menu is a submenu, Contingent Plans. To add some levity I’ve created some humorous menu options for contingency plans when an emergency occurs.

Additional Ways to Select Menus and Menu Items

In the previous example you learned how to create and invoke menu items using your mouse, but did you know that there are other ways to invoke menu items? In this section you will learn three additional ways to invoke menu items: by constructing key mnemonics, key combinations, and context menus.

Menu fileMenu = new Menu("_File");
fileMenu.setMnemonicParsing(true);

MenuItem saveItem = new MenuItem("_Save");
saveItem.setMnemonicParsing(true);
saveItem.setAccelerator(new KeyCodeCombination(KeyCode.S, KeyCombination.SHORTCUT_DOWN));

ContextMenu contextFileMenu = new ContextMenu(exitItem);

primaryStage.addEventHandler(MouseEvent.MOUSE_CLICKED, (MouseEvent me) -> {
   if (me.getButton() == MouseButton.SECONDARY || me.isControlDown()) {
      contextFileMenu.show(root, me.getScreenX(), me.getScreenY());
   } else {
      contextFileMenu.hide();
   }
});

Working with ListViews

The Hero Picker example application was created to demonstrate the ObservableList’s capabilities; it displays two JavaFX ListView UI controls and allows the user to transfer items between the two ListView controls. One list contains candidates for hero status and the other contains those who have already achieved it. As shown in Listing 4-16, this application allows you to choose a candidate to be transferred to the other ListView control, which contains the chosen heroes.

Listing 4-16. The Hero Picker application, which demonstrates the ObservableList and ListView classes

@Override
public void start(Stage primaryStage) {
   primaryStage.setTitle("Hero Picker: Chapter 4 Creating and Working with ObservableLists");
   BorderPane root = new BorderPane();
   Scene scene = new Scene(root, 400, 250, Color.WHITE);

   // create a grid pane
   GridPane gridpane = new GridPane();
   gridpane.setPadding(new Insets(5));
   gridpane.setHgap(10);
   gridpane.setVgap(10);
   ColumnConstraints column1 = new ColumnConstraints(150, 150, Double.MAX_VALUE);
   ColumnConstraints column2 = new ColumnConstraints(50);
   ColumnConstraints column3 = new ColumnConstraints(150, 150, Double.MAX_VALUE);
   column1.setHgrow(Priority.ALWAYS);
   column3.setHgrow(Priority.ALWAYS);
   gridpane.getColumnConstraints().addAll(column1, column2, column3);

   // Candidates label
   Label candidatesLbl = new Label("Candidates");
   GridPane.setHalignment(candidatesLbl, HPos.CENTER);
   gridpane.add(candidatesLbl, 0, 0);

   // Heroes label
   Label heroesLbl = new Label("Heroes");
   gridpane.add(heroesLbl, 2, 0);
   GridPane.setHalignment(heroesLbl, HPos.CENTER);

   // Candidates
   final ObservableList<String> candidates = FXCollections.observableArrayList("Superman",
           "Spiderman",
           "Wolverine",
           "Police",
           "Fire Rescue",
           "Soldiers",
           "Dad & Mom",
           "Doctor",
           "Politician",
           "Pastor",
           "Teacher");
   final ListView<String> candidatesListView = new ListView<>(candidates);
   gridpane.add(candidatesListView, 0, 1);

   // heroes
   final ObservableList<String> heroes = FXCollections.observableArrayList();
   final ListView<String> heroListView = new ListView<>(heroes);

   gridpane.add(heroListView, 2, 1);

   // select heroes
   Button sendRightButton = new Button(" > ");
   sendRightButton.setOnAction((ActionEvent event) -> {
       String potential = candidatesListView.getSelectionModel().getSelectedItem();
       if (potential != null) {
           candidatesListView.getSelectionModel().clearSelection();
           candidates.remove(potential);
           heroes.add(potential);
       }
   });

   // deselect heroes
   Button sendLeftButton = new Button(" < ");
   sendLeftButton.setOnAction((ActionEvent event) -> {
       String notHero = heroListView.getSelectionModel().getSelectedItem();
       if (notHero != null) {
           heroListView.getSelectionModel().clearSelection();
           heroes.remove(notHero);
           candidates.add(notHero);
       }
   });
   VBox vbox = new VBox(5);
   vbox.getChildren().addAll(sendRightButton,sendLeftButton);
   gridpane.add(vbox, 1, 1);
   root.setCenter(gridpane);

   GridPane.setVgrow(root, Priority.ALWAYS);
   primaryStage.setScene(scene);
   primaryStage.show();
}

Figure 4-10 shows the output from Listing 4-16, the Hero Picker application.

Created in this example is a GUI application that allows a user to choose their favorite heroes. This is quite similar to application screens that manage user roles by adding or removing items from list box components. In JavaFX the code example uses two ListView controls to hold String objects. For the sake of brevity we will not discuss the use of the layouts, but jump right into the code relating to the button actions and ListView controls.

Before creating an instance of a ListView, the code creates an ObservableList containing our candidates. Here you’ll notice the use of a factory class called FXCollections, into which you can pass common collection types to be wrapped and returned to the caller as an ObservableList. In the example an array of Strings is passed into the FXCollections.observableArrayList() method instead of an ArrayList. Using the ObservableList allows us to update the list of items in the array and in the display on the screen concurrently with a single method call.

Hopefully you get the idea about how to use the FXCollections class. I trust you will use it wisely; as Peter Parker’s Uncle Ben says,“With great power, there must also come great responsibility.” The following code line calls the FXCollections.observableArrayList() method class to return an observable list (ObservableList):

ObservableList<String> candidates = FXCollections.observableArrayList(...);

After the code creates an ObservableList, a ListView class is instantiated using a constructor that receives the observable list. The following code creates and populates a ListView object:

ListView<String> candidatesListView = new ListView<String>(candidates);

The last item of business is where the code manipulates ObservableLists as if they were java.util.ArrayLists. As they are manipulated, the ListView is notified and automatically updated to reflect the changes to the ObservableList. Listing 4-17 implements the action event code when the user presses the Send (>) button.

Listing 4-17. Action code to process selected items

// select heroes
Button sendRightButton = new Button(">");
sendRightButton.setOnAction( actionEvent -> {
        String potential = candidatesListView.getSelectionModel().getSelectedItem();
        if (potential != null) {
            candidatesListView.getSelectionModel().clearSelection();
            candidates.remove(potential);
            heroes.add(potential);
        }
});

To set action code for the button, the code uses a lambda expression with an actionEvent (ActionEvent) as a parameter, which is invoked when the button is clicked. When a button-press event arrives, the code determines which item in the ListView was selected via the getSelectionModel().getSelectedItem() on the ListView. Once the item is determined, the code clears the selection (clearSelection()), removes the item, and adds the item to the Heroes ObserverableList. What’s great is that there is no need to refresh the ListView UI control when the collection changes.