Positioning Graphic and Text

The contentDisplay property of labeled controls specifies the positioning of the graphic relative to the text. Its value is one of the constants of the ContentDisplay enum: TOP, RIGHT, BOTTOM, LEFT, CENTER, TEXT_ONLY, and GRAPHIC_ONLY. If you do not want to display the text or the graphic, you can use the GRAPHIC_ONLY and TEXT_ONLY values instead of setting the text to an empty string and the graphic to null. Figure 12-3 shows the effects of using different values for the contentDisplay property of a Label. The Label uses Name: as the text and a blue rectangle as the graphic. The value for the contentDisplay property is displayed at the bottom of each instance.

Understanding Mnemonics and Accelerators

Labeled controls support keyboard mnemonics , which is also known as a keyboard shortcut or keyboard indicator. A mnemonic is a key that sends an ActionEvent to the control. The mnemonic key is often pressed in combination with a modifier key such as an Alt key. The modifier key is platform dependent; however, it is usually an Alt key. For example, suppose you set the C key as a mnemonic for a Close button. When you press Alt + C, the Close button is activated.

Finding the documentation about mnemonics in JavaFX is not easy. It is buried in the documentation for the Labeled and Scene classes. Setting a mnemonic key for a labeled control is easy. You need to precede the mnemonic character with an underscore in the text content and make sure that the mnemonicParsing property for the control is set to true. The first underscore is removed, and the character following it is set as the mnemonic for the control. For some labeled controls, the mnemonic parsing is set to true by default, and for others, you will need to set it.

When you press the Alt key, the mnemonic characters for all controls are underlined, and pressing the mnemonic character for any controls will set focus to the control and send it an ActionEvent.

An object of the Mnemonic class represents a mnemonic. An object of the KeyCombination class, which is declared abstract, represents the key combination for a mnemonic. The KeyCharacterCombination and KeyCodeCombination classes are subclasses of the KeyCombination class. Use the former to construct a key combination using a character; use the latter to construct a key combination using a key code. Note that not all keys on the keyboard represent characters. The KeyCodeCombination class lets you create a key combination for any key on the keyboard.

The Mnemonic object is created for a node and is added to a Scene. When the Scene receives an unconsumed key event for the key combination, it sends an ActionEvent to the target node.

The Scene class supports accelerator keys. An accelerator key, when pressed, executes a Runnable task. Notice the difference between mnemonics and accelerator keys. A mnemonic is associated with a control, and pressing its key combination sends an ActionEvent to the control. An accelerator key is not associated with a control, but rather to a task. The Scene class maintains an ObservableMap<KeyCombination, Runnable>, whose reference can be obtained using the getAccelerators() method .

Understanding the Button Control

An instance of the Button class represents a command button. Typically, a Button has text as its label, and an ActionEvent handler is registered to it. The mnemonicParsing property for the Button class is set to true by default.

For a normal button, its ActionEvent is fired when the button is activated. For a default button, the ActionEvent is fired when the Enter key is pressed and no other node in the scene consumes the key press. For a cancel button, the ActionEvent is fired when the Esc key is pressed and no other node in the scene consumes the key press.

By default, a Button is a normal button. The default and cancel modes are represented by the defaultButton and cancelButton properties. You would set one of these properties to true to make a button a default or cancel button. By default, both properties are set to false.

Understanding the Hyperlink Control

An instance of the Hyperlink class represents a hyperlink control, which looks like a hyperlink in a web page. In a web page, a hyperlink is used to navigate to another web page. However, in JavaFX, an ActionEvent is triggered when a Hyperlink control is activated, for example, by clicking it, and you are free to perform any action in the ActionEvent handler.

A Hyperlink control is simply a button styled to look like a hyperlink. By default, mnemonic parsing is off. A Hyperlink control can have focus, and by default, it draws a dashed rectangular border when it has focus. When the mouse cursor hovers over a Hyperlink control, the cursor changes to a hand, and its text is underlined.

The Hyperlink class contains a visited property of BooleanProperty type. When a Hyperlink control is activated for the first time, it is considered “visited,” and the visited property is set to true automatically. All visited hyperlinks are shown in a different color than the not visited ones. You can also set the visited property manually using the setVisited() method of the Hyperlink class.

Understanding the MenuButton Control

A MenuButton control looks like a button and behaves like a menu. When it is activated (by clicking or other means), it shows a list of options in the form of a pop-up menu. The list of options in the menu is maintained in an ObservableList<MenuItem> whose reference is returned by the getItems() method. To execute a command when a menu option is selected, you need to add the ActionEvent handler to the MenuItems.

The following snippet of code creates a MenuButton with two MenuItems. Each menu item has an ActionEvent handler attached to it. Figure 12-5 shows the MenuButton in two states: not showing and showing.

// Create two menu items with an ActionEvent handler.

// Assume that the loadPage() method exists

MenuItem jdojo = new MenuItem("JDojo");

jdojo.setOnAction(e -> loadPage("http://www.jdojo.com"));

MenuItem yahoo = new MenuItem("Yahoo");

yahoo.setOnAction(e -> loadPage("http://www.yahoo.com"));

// Create a MenuButton and the two menu items

MenuButton links = new MenuButton("Visit");

links.getItems().addAll(jdojo, yahoo);

The popupSide property is of the ObjectProperty<Side> type, and the showing property is of the ReadOnlyBooleanProperty type.

The popupSide property determines which side of the menu should be displayed. Its value is one of the constants in the Side enum: TOP, LEFT, BOTTOM, and RIGHT. The default value is Side.BOTTOM. An arrow in the MenuItem shows the direction set by the popupSide property. The arrow in Figure 12-5 is pointing downward, indicating that the popupSide property is set to Side.BOTTOM. The menu is opened in the direction set in the popupSide property only if space is available to display the menu in that side. If space is not available, the JavaFX runtime will make a smart decision as to which side the menu should be displayed. The value of the showing property is true when the pop-up menu is showing. Otherwise, it is false.

Understanding the ToggleButton Control

ToggleButton is a two-state button control. The two states are selected and unselected. Its selected property indicates whether it is selected. The selected property is true when it is in the selected state. Otherwise, it is false. When it is in the selected state, it stays depressed. You can toggle between the selected and unselected states by pressing it, and hence it got the name ToggleButton. For ToggleButtons, mnemonic parsing is enabled by default.

Figure 12-6 shows four toggle buttons with Spring, Summer, Fall, and Winter as their labels. Two of the toggle buttons, Spring and Fall, are selected, and the other two are unselected.

A ToggleButton is used to select a choice, not to execute a command. Typically, you do not add ActionEvent handlers to a ToggleButton. Sometimes, you can use a ToggleButton to start or stop an action. For that, you will need to add a ChangeListener for its selected property.

The ToggleGroup class contains a selectedToggle property that keeps track of the selected Toggle in the group. The getSelectedToggle() method returns the reference of the Toggle that is selected. If no Toggle is selected in the group, it returns null. Add a ChangeListener to this property if you are interested in tracking the change in selection inside a ToggleGroup.

The program in Listing 12-6 adds four toggle buttons to a ToggleGroup. You can select none or at the most one ToggleButton from the group. Figure 12-7 shows two screenshots: one when there is no selection and one when the ToggleButton with the label Summer is selected. The program adds a ChangeListener to the group to track the change in selection and displays the label of the selected ToggleButton in a Label control.

Understanding the RadioButton Control

An instance of the RadioButton class represents a radio button. It inherits from the ToggleButton class. Therefore, it has all of the features of a toggle button. A radio button is rendered differently compared to a toggle button. Like a toggle button, a radio button can be in one of the two states: selected and unselected. Its selected property indicates its current state. Like a toggle button, its mnemonic parsing is enabled by default. Like a toggle button, it also sends an ActionEvent when it is selected and unselected. Figure 12-8 shows a RadioButton with Summer as its text in selected and unselected states.

There is a significant difference in the use of radio buttons compared to the use of toggle buttons. Recall that when toggle buttons are used in a group, there may not be any selected toggle button in the group. When radio buttons are used in a group, there must be one selected radio button in the group. Unlike a toggle button, clicking a selected radio button in a group does not unselect it. To enforce the rule that one radio button must be selected in a group of radio buttons, one radio button from the group is selected programmatically by default.

You set the default season in the radio button after you have added the change listener to the group, so the message to display the selected season is updated correctly.

// RadioButtonTest.java

// ... find in the book's download area.

Listing 12-7

Using Radio Buttons in a ToggleGroup and Tracking the Selection

Understanding the CheckBox Control

CheckBox is a three-state selection control: checked, unchecked, and undefined. The undefined state is also known as an indeterminate state. A CheckBox supports a selection of three choices: true/false/unknown or yes/no/unknown. Usually, a CheckBox has text as a label, but not a graphic (even though it can). Clicking a CheckBox transitions it from one state to another cycling through three states.

A box is drawn for a CheckBox. In the unchecked state, the box is empty. A tick mark (or a check mark) is present in the box when it is in the checked state. In the undefined state, a horizontal line is present in the box. Figure 12-10 shows a CheckBox labeled Hungry in its three states.

The program in Listing 12-8 shows how to use CheckBox controls. Figure 12-11 shows the window that results from running this code. The program creates two CheckBox controls. The Hungry CheckBox supports only two states. The I agree CheckBox is configured to support three states. When you change the state for the I agree CheckBox by clicking it, the Label at the top displays the description of the state.

// CheckBoxTest.java

// ... find in the book's download area.

Listing 12-8

Using the CheckBox Control

The default CSS style class name for a CheckBox is check-box. The CheckBox class supports three CSS pseudo-classes: selected, determinate, and indeterminate. The selected pseudo-class applies when the selected property is true. The determinate pseudo-class applies when the indeterminate property is false. The indeterminate pseudo-class applies when the indeterminate property is true.

Using Domain Objects in ChoiceBox

In the previous example, you used String objects as items in the choice box. You can use any object type as items. ChoiceBox calls the toString() method of every item and displays the returned value in the pop-up list. The following snippet of code creates a choice box and adds four Person objects as its items. Figure 12-15 shows the choice box in the showing state. Notice the items are displayed using the String object returned from the toString() method of the Person class.

import com.jdojo.mvc.model.Person;

import javafx.scene.control.ChoiceBox;

...

ChoiceBox<Person> persons = new ChoiceBox<>();

persons.getItems().addAll(new Person("John", "Jacobs", null),

                          new Person("Donna", "Duncan", null),

                          new Person("Layne", "Estes", null),

                          new Person("Mason", "Boyd", null));

The toString(T object) method converts the object of type T to a string. The fromString(String string) method converts a string to a T object.

The following snippet of code uses a converter in a ChoiceBox to convert Person objects in its list of items to strings. Figure 12-16 shows the choice box in the showing state.

import com.jdojo.mvc.model.Person;

import javafx.scene.control.ChoiceBox;

...

ChoiceBox<Person> persons = new ChoiceBox<>();

// Set a converter to convert a Person object to a String object

persons.setConverter(new PersonStringConverter());

// Add five person objects to the ChoiceBox

persons.getItems().addAll(new Person("John", "Jacobs", null),

                          new Person("Donna", "Duncan", null),

                          new Person("Layne", "Estes", null),

                          new Person("Mason", "Boyd", null));

Allowing Nulls in ChoiceBox

The preceding snippet of code produces a choice box as shown in Figure 12-17. Notice that the null item is shown as an empty space.

It is often required that the null choice be shown as a custom string, for example, "[None]". This can be accomplished using a converter. In the previous section, you used a converter to customize the choices for Person objects. Here, you will use the converter to customize the choice item for null. You can do both in one converter as well. The following snippet of code uses a converter with a ChoiceBox to convert a null choice as "[None]". Figure 12-18 shows the resulting choice box.

ChoiceBox<String> seasons = new ChoiceBox<>();

seasons.getItems().addAll(null, "Spring", "Summer", "Fall", "Winter");

// Use a converter to convert null to "[None]"

seasons.setConverter(new StringConverter<String>() {

        @Override

        public String toString(String string) {

                return (string == null) ? "[None]" : string;

        }

        @Override

        public String fromString(String string) {

                return string;

        }

});

Using Separators in ChoiceBox

Sometimes , you may want to separate choices into separate groups. Suppose you want to show fruits and cooked items in a breakfast menu, and you want to separate one from the other. You would use an instance of the Separator class to achieve this. It appears as a horizontal line in the list of choices. A Separator is not selectable. The following snippet of code creates a choice box with one of its items as a Separator. Figure 12-19 shows the choice box in the showing state.

ChoiceBox breakfasts = new ChoiceBox();

breakfasts.getItems().addAll("Apple", "Banana", "Strawberry",

                      new Separator(),

                      "Apple Pie", "Donut", "Hash Brown");

Styling a ChoiceBox with CSS

The default CSS style class name for a ChoiceBox is choice-box. The ChoiceBox class supports a showing CSS pseudo-class, which applies when the showing property is true.

Detecting Value Change in ComboBox

Detecting an item change in a noneditable combo box is easily performed by adding a ChangeListener to the selectedIndex or selectedItem property of its selection model. Please refer to the “Understanding the ChoiceBox Control” section for more details.

You can still use a ChangeListener for the selectedItem property to detect when the value in an editable combo box changes by selecting from the items list or entering a new value. When you enter a new value, the selectedIndex property does not change because the entered value does not exist in the items list.

Using Domain Objects in Editable ComboBox

In an editable ComboBox<T> where T is something other than String, you must set the converter property to a valid StringConverter<T>. Its toString(T object) method is used to convert the item object to a string to show it in the pop-up list. Its fromString(String s) method is called to convert the entered string to an item object. The value property is updated with the item object converted from the entered string. If the entered string cannot be converted to an item object, the value property is not updated.

Customizing the Height of a Pop-Up List

Using Nodes As Items in ComboBox

Both areas use ListCells to display items. A ListCell is a Cell. A Cell is a Labeled control to display some form of content that may have text, a graphic, or both. The pop-up area is a ListView that contains an instance of ListCell for each item in the list. I will discuss ListView in the next section.

Elements in the items list of a combo box can be of any type, including Node type. It is not recommended to add instances of the Node class directly to the items list. When nodes are used as items, they are added as the graphic to the cells. Scene graphics need to follow the rule that a node cannot be displayed in two places at the same time. That is, a node must be inside one container at a time. When a node from the items list is selected, the node is removed from the pop-up ListView cell and added to the button area. When the pop-up is displayed again, the selected node is not shown in the list as it is already showing in the button area. To avoid this inconsistency in display, avoid using nodes directly as items in a combo box.

Figure 12-21 shows three views of a combo box created using the following snippet of code. Notice that the code adds three instances of HBox, which is a node to the items list. The figure labeled #1 shows the pop-up list when it is opened for the first time, and you see all three items correctly. The figure labeled #2 shows up after the second item is selected, and you see the correct item in the button area. At this time, the second item in the list, an HBox with a rectangle, was removed from the cell in the ListView and added to the cell in the button area. The figure labeled #3 shows the pop-up list when it is open for the second time. At this time, the second item is missing from the list because it is already selected. This problem was discussed in the previous paragraph.

Label shapeLbl = new Label("Shape:");

ComboBox<HBox> shapes = new ComboBox<>();

shapes.getItems().addAll(new HBox(new Line(0, 10, 20, 10), new Label("Line")),

                new HBox(new Rectangle(0, 0, 20, 20), new Label("Rectangle")),

                new HBox(new Circle(20, 20, 10), new Label("Circle")));

You can fix the display issue that occurs when you use nodes as items. The solution is to add nonnode items in the list and supply a cell factory to create the desired node inside the cell factory. You need to make sure that the nonnode items will provide enough pieces of information to create the node you wanted to insert. The next section explains how to use a cell factory.

Using a Cell Factory in ComboBox

The declaration of the cellFactory property states that it stores a Callback object whose call() method receives a ListView<T> and returns a ListCell<T>. Inside the call() method, you create an instance of the ListCell<T> class and override the updateItem(T item, boolean empty) method of the Cell class to populate the cell.

Notice the use of the StringShapeCell class in the buttonCell property and ShapeCellFactory class.

Run the program in Listing 12-16. You should be able to select a shape from the list, and the shape should be displayed in the combo box correctly. Figure 12-22 shows three views of the combo box.

// ComboBoxCellFactory.java

package com.jdojo.control;

import javafx.application.Application;

import javafx.scene.Scene;

import javafx.scene.control.ComboBox;

import javafx.scene.control.Label;

import javafx.scene.layout.HBox;

import javafx.stage.Stage;

public class ComboBoxCellFactory extends Application {

        public static void main(String[] args) {

                Application.launch(args);

        }

        @Override

        public void start(Stage stage) {

                Label shapeLbl = new Label("Shape:");

                ComboBox<String> shapes = new ComboBox<>();

                shapes.getItems().addAll("Line", "Rectangle", "Circle");

                // Set the cellFactory property

                shapes.setCellFactory(new ShapeCellFactory());

                // Set the buttonCell property

                shapes.setButtonCell(new StringShapeCell());

                HBox root = new HBox(shapeLbl, shapes);

                root.setStyle("-fx-padding: 10;" +

                              "-fx-border-style: solid inside;" +

                              "-fx-border-width: 2;" +

                              "-fx-border-insets: 5;" +

                              "-fx-border-radius: 5;" +

                              "-fx-border-color: blue;");

                Scene scene = new Scene(root);

                stage.setScene(scene);

                stage.setTitle("Using CellFactory in ComboBox");

                stage.show();

        }

}

Listing 12-16

Using a Cell Factory in a Combo Box

Using a custom cell factory and button cell in a combo box gives you immense power to customize the look of the pop-up list and the selected item. If using a cell factory looks hard or confusing to you, keep in mind that a cell is a Labeled control, and you are setting the text and graphic in that Labeled control inside the updateItem() method . The Callback interface comes into play because the ComboBox control needs to give you a chance to create a cell when it needs it. Otherwise, you would have to know how many cells to create and when to create them. There is nothing more to it.

These properties are of the type ObjectProperty<EventHandler<Event>>. You can set an event handler to these properties, which will be called before the pop-up list is shown, after it is shown, before it is hidden, and after it is hidden. For example, the onShowing event handlers are handy when you want to customize the pop-up list just before it is shown.

Styling ComboBox with CSS

The default CSS style class name for a ComboBox is combo-box. A combo box contains several CSS substructures, as shown in Figure 12-23.

Orientation of a ListView

Figure 12-25 shows two instances of ListView: one uses vertical orientation and one horizontal orientation. Notice that the odd and even rows or columns have different background colors. This is the default look of the ListView. You can change the appearance using a CSS. Please refer to the “Styling ListView with CSS” section for details.

Selection Model in ListView

In single selection mode, only one item can be selected at a time. If an item is selected, the previously selected item is deselected. By default, a ListView supports single selection mode. An item can be selected using a mouse or a keyboard. You can select an item using a mouse click. Using a keyboard to select an item requires that the ListView have focus. You can use the up/down arrow in a vertical ListView and the left/right arrow in a horizontal ListView to select items.

The MultipleSelectionModel class inherits from the SelectionModel class, which contains selectedIndex and selectedItem properties.

The selectedIndex property is –1 if there is no selection. In single selection mode, it is the index of the currently selected item. In multiple selection mode, it is the index of the last selected item. In multiple selection mode, use the getSelectedIndices() method that returns a read-only ObservableList<Integer> containing the indexes of all selected items. If you are interested in listening for selection change in a ListView, you can add a ChangeListener to the selectedIndex property or a ListChangeListener to the ObservableList returned by the getSelectedIndices() method.

The selectedItem property is null if there is no selection. In single selection mode, it is the currently selected item. In multiple selection mode, it is the last selected item. In multiple selection mode, use the getSelectedItems() method that returns a read-only ObservableList<T> containing all selected items. If you are interested in listening for selection change in a ListView, you can add a ChangeListener to the selectedItem property or a ListChangeListener to the ObservableList<T> returned by the getSelectedItems() method.

The program in Listing 12-17 demonstrates how to use the selection model of a ListView for making selections and listening for selection change events. Figure 12-26 shows the window that results from running this code. Run the application and use a mouse or buttons on the window to select items in the ListView. The selection details are displayed at the bottom.

// ListViewSelectionModel.java

// ... find in the book's download area.

Listing 12-17

Using a ListView Selection Model

Using Cell Factory in ListView

Each item in a ListView is displayed in an instance of ListCell, which is a Labeled control. Recall that a Labeled control contains text and a graphic. The ListView class contains a cellFactory property that lets you use custom cells for its items. The property type is ObjectProperty<Callback<ListView<T>,ListCell<T>>>. The reference of the ListView is passed to the call() method of the Callback object, and it returns an instance of the ListCell class. In a large ListView, say 1000 items, the ListCell returned from the cell factory may be reused. The control needs to create only the number of cells that are visible. Upon scrolling, it may reuse the cells that went out of the view to display newly visible items. The updateItem() method of the ListCell receives the reference of the new item.

By default, a ListView calls the toString() method of its items, and it displays the string in its cell. In the updateItem() method of your custom ListCell, you can populate the text and graphic for the cell to display anything you want in the cell based on the item in that cell.

The program in Listing 12-18 shows how to use a custom cell factory to display the formatted names of Person items. Figure 12-27 shows the resulting window after running the code. The snippet of code in the program creates and sets a custom cell factory. The updateItem() method of the ListCell formats the name of the Person object and adds a serial number that is the index of the cell plus one.

// ListViewDomainObjects.java

// ... find in the book's download area.

Listing 12-18

Using a Custom Cell Factory for ListView

Using Editable ListView

Select a cell and click to start editing. Alternatively, press the spacebar when a cell has focus to start editing. If a ListView is editable and has an editable cell, you can also use the edit(int index) method of the ListView to edit the item in the cell at the specified index.

JavaFX provides cell factories that let you edit a ListCell using TextField, ChoiceBox, ComboBox, and CheckBox. You can create a custom cell factory to edit cells in some other way. Instances of the TextFieldListCell, ChoiceBoxListCell, ComboBoxListCell, and CheckBoxListCell classes, as list cells in a ListView, provide editing support. These classes are included in the javafx.scene.control.cell package.

Using a Check Box to Edit ListView Items

The CheckBoxListCell class provides the ability to edit a ListCell using a check box. It draws a check box in the cell, which can be selected or deselected. Note that the third state, the indeterminate state, of the check box is not available for selection while using a check box to edit ListView items.

Using a check box to edit ListView items is a little different. You need to provide the CheckBoxListCell class with an ObservableValue<Boolean> object for each item in the ListView. Internally, the observable value is bound bidirectionally to the selected state of the check box. When the user selects or deselects an item in the ListView using the check box, the corresponding ObservableValue object is updated with a true or false value. If you want to know which item is selected, you will need to keep the reference of the ObservableValue object.

Let’s redo our earlier breakfast example using a check box. The following snippet of code creates a map and adds all items as a key and a corresponding ObservableValue item with false value. Using a false value, you want to indicate that the items will be initially deselected:

Map<String, ObservableValue<Boolean>> map = new HashMap<>();

map.put("Apple", new SimpleBooleanProperty(false));

map.put("Banana", new SimpleBooleanProperty(false));

map.put("Donut", new SimpleBooleanProperty(false));

map.put("Hash Brown", new SimpleBooleanProperty(false));

Now, you create an editable ListView with all keys in the map as its items:

ListView<String> breakfasts = new ListView<>();

breakfasts.setEditable(true);

// Add all keys from the map as items to the ListView

breakfasts.getItems().addAll(map.keySet());

The following snippet of code creates a Callback object. Its call() method returns the ObservableValue object for the specified item passed to the call() method. The CheckBoxListCell class will call the call() method of this object automatically:

Callback<String, ObservableValue<Boolean>> itemToBoolean =

    (String item) -> map.get(item);

Now it is time to create and set a cell factory for the ListView. The forListView() static method of the CheckBoxListCell class takes a Callback object as an argument. If your ListView contains domain objects, you can also provide a StringConverter to this method, using the following code:

// Set the cell factory

breakfasts.setCellFactory(CheckBoxListCell.forListView(itemToBoolean));

When the user selects or deselects an item using the check box, the corresponding ObservableValue in the map will be updated. To know whether an item in the ListView is selected, you need to look at the value in the ObservableValue object for that item.

The program in Listing 12-21 shows how to use a check box to edit items in a ListView. Figure 12-28 shows the resulting window after running the code. Select items using a mouse. Pressing the Print Selection button prints the selected items on the standard output.

// ListViewCheckBoxEditing.java

// ... find in the book's download area.

Listing 12-21

Using a Check Box to Edit ListView Items

Handling Events While Editing a ListView

The ListView class defines a ListView.EditEvent<T> static inner class to represent edit-related event objects. Its getIndex() method returns the index of the item that is edited. The getNewValue() method returns the new input value. The getSource() method returns the reference of the ListView firing the event. The ListView class provides onEditStart, onEditCommit, and onEditCancel properties to set the event handlers for these methods.

Styling ListView with CSS

The default CSS style class name for a ListView is list-view, and for ListCell it is list-cell. The ListView class has two CSS pseudo-classes: horizontal and vertical. The -fx-orientation CSS property controls the orientation of the ListView, which can be set to horizontal or vertical.

The empty pseudo-class applies when the cell is empty. The filled pseudo-class applies when the cell is not empty. The selected pseudo-class applies when the cell is selected. The odd and even pseudo-classes apply to cells with an odd and even index, respectively. The cell representing the first item is index 0, and it is considered an even cell.

This only solves half of the problem; it only takes care of the background colors of the list cells in a normal state inside a ListView. A list cell can be in several states, for example, focused, selected, empty, or filled. To completely address this, you will need to set the appropriate background colors for list cells for all states. Please refer to the modena.css file for a complete list of states that you will need to modify the background colors for list cells.

The ListCell class supports an -fx-cell-size CSS property that is the height of the cells in a vertical ListView and the width of cells in a horizontal ListView.

Using the ColorPicker Control

The ColorPicker control supports three looks: combo-box look, button look, and split-button look. The combo-box look is the default look. Figure 12-32 shows a ColorPicker in these three looks, respectively.

Styling ColorPicker with CSS

The default CSS style class name for a ColorPicker is color-picker. You can style almost every part of a ColorPicker, for example, color indicator, color label, color palette dialog, and custom color dialog. Please refer to the modena.css file for complete reference.

Using the DatePicker Control

The DatePicker has a converter property that uses a StringConverter to convert a LocalDate to a string and vice versa. Its value property stores the date as LocalDate, and its editor displays it as a string, which is the formatted date. When you enter a date as text, the converter converts it to a LocalDate and stores it in the value property. When you pick a date from the calendar pop-up, the converter creates a LocalDate to store in the value property, and it converts it to a string to display in the editor. The default converter uses the default Locale and chronology to format the date. When you enter a date as text, the default converter expects the text in the default Locale and chronology format.

Listing 12-25 has a complete program showing how to use a DatePicker control. It uses most of the features of the DatePicker. It displays a window as shown in Figure 12-34. The control is noneditable, forcing the user to select a nonfuture date from the pop-up.

// DatePickerTest.java

// ... find in the book's download area.

Listing 12-25

Using the DatePicker Control

Styling DatePicker with CSS

The default CSS style class name for a DatePicker is date-picker, and for its pop-up, the class name is date-picker-popup. You can style almost every part of a DatePicker, for example, the month-year pane in the top area of the pop-up, day cells, week number cells, and current day cell. Please refer to the modena.css file for complete reference.

Positioning and Moving Caret

All text input controls provide a caret. By default, a caret is a blinking vertical line when the control has focus. The current caret position is the target for the next input character from the keyboard. The caret position starts at zero, which is before the first character. Position 1 is after the first character and before the second character and so on. Figure 12-35 shows the caret positions in a text input control that has four characters. The number of characters in the text determines the valid range for the caret position, which is zero to the length of the text. Zero is the only valid caret position if the control does not contain text.

Several methods take a caret position as an argument. Those methods clamp the argument value to the valid caret position range. Passing a caret position outside the valid range will not throw an exception. For example, if the control has four characters and you want to move the caret to position 10, the caret will be positioned at position 4.

The read-only caretPosition property contains the current caret position. Use the positionCaret(int pos) method to position the caret at the specified pos. The backward() and forward() methods move the caret one character backward and forward, respectively, if there is no selection. If there is a selection, they move the caret position to the beginning and end and clear the selection. The home() and end() methods move the caret before the first character and after the last character, respectively, and clear the selection. The nextWord() method moves the caret to the beginning of the next word and clears the selection. The endOfNextWord() method moves the caret to the end of the next word and clears the selection. The previousWord() method moves the caret to the beginning of the previous word and clears the selection.

Making Text Selection

The TextInputControl class provides a rich API through its properties and methods to deal with text selection. Using the selection API, you can select the entire or partial text and get the selection information.

The selectedText property contains the value of the selected text. Its value is an empty string if there is no selection. The selection property contains an IndexRange that holds the index range of the selection. The getStart() and getEnd() methods of the IndexRange class return the start index and end index of the selection, respectively, and its getLength() method returns the length of the selection. If there is no selection, the lower and upper limits of the range are the same, and they are equal to the caretPosition value.

The anchor and caretPosition properties play a vital role in text selection. The value of these properties defines the selection range. The same value for both properties indicates no selection. Either property may indicate the start or end of the selection range. The anchor value is the caret position when the selection started. You can select characters by moving the caret backward or forward. For example, you can use the left or right arrow key with the Shift key pressed to select a range of characters. If you move the caret forward during the selection process, the anchor value will be less than the caretPosition value. If you move the caret backward during the selection process, the anchor value will be greater than the caretPosition value. Figure 12-36 shows the relation between the anchor and caretPosition values.

In Figure 12-36, the part labeled #1 shows a text input control with the text BLESSINGS. The caretPosition value is 1. The user selects four characters by moving the caret four positions forward, for example, by pressing the Shift key and right arrow key or by dragging the mouse. The selectedText property, as shown in the part labeled #2, is LESS. The anchor value is 1, and the caretPosition value is 5. The selection property has an IndexRange of 1 to 5.

In the part labeled #3, the caretPosition value is 5. The user selects four characters by moving the caret backward as shown in the part labeled #4. The selectedText property, as shown in part labeled #4, is LESS. The anchor value is 5, and the caretPosition value is 1. The selection property has an IndexRange of 1 to 5. Notice that in the parts labeled #2 and #4, the anchor and caretPosition values are different, and the selectedText and selection properties are the same.

Notice that you have a positionCaret(int pos) method and a selectPositionCaret(int pos) method. The former positions the caret at the specified position and clears the selection. The latter moves the caret to the specified pos and extends the selection if one exists. If no selection exists, it forms a selection by the current caret position as the anchor and moving the caret to the specified pos.

The replaceSelection(String replacement) method replaces the selected text by the specified replacement. If there is no selection, it clears the selection and inserts the specified replacement at the current caret position.

Modifying the Content

The text property of the TextInputControl class represents the textual content of text input controls. You can change the content using the setText(String text) method and get it using the getText() method. The clear() method sets the content to an empty string.

The insertText(int index, String text) method inserts the specified text at the specified index. It throws an IndexOutOfBoundsException if the specified index is outside the valid range (zero to the length of the content). The appendText(String text) method appends the specified text to the content. The deleteText() method lets you delete a range of characters from the content. You can specify the range as an IndexRange object or start and end index. The deleteNextChar() and deletePreviousChar() methods delete the next and previous character, respectively, from the current caret position if there is no selection. If there is a selection, they delete the selection. They return true if the deletion was successful. Otherwise, they return false.

The read-only length property represents the length of the content. It changes as you modify the content. Practically, the length value can be very big. There is no direct way to restrict the number of characters in a text input control. I will cover an example of restricting the length of text shortly.

Cutting, Copying, and Pasting Text

The text input controls support cut, copy, and paste features programmatically, using the mouse and keyboard. To use these features using the mouse and keyboard, use the standard steps supported on your platform. Use the cut(), copy(), and paste() methods to use these features programmatically. The cut() method transfers the currently selected text to the clipboard and removes the current selection. The copy() method transfers the currently selected text to the clipboard without removing the current selection. The paste() method replaces the current selection with the content in the clipboard. If there is no selection, it inserts the clipboard content at the current caret position.

An Example

The program in Listing 12-26 demonstrates how the different properties of text input control change. It displays a window as shown in Figure 12-37. The program uses a TextField, which is a text input control, to display one line of text. Each property is displayed in a Label by binding the text properties to the properties of the TextField. After running the program, change the text in the name field, move the caret, and change the selection to see how the properties of the TextField change.

// TextControlProperties.java

// ... find in the book's download area.

Listing 12-26

Using the Properties of Text Input Controls

Styling TextInputControl with CSS

The -fx-font property is inherited from the parent by default. The value for the -fx-display-caret property could be true or false. When it is true, the caret is displayed when the control has focus. Otherwise, the caret is not displayed. Its default value is true. Most of the other properties affect background and text colors.

Styling TextField with CSS

The default CSS style class name for a TextField is text-field. It adds an -fx-alignment property that is the alignment of its text within its content area. There is nothing special that needs to be said about styling TextField.

Styling TextArea with CSS

The default CSS style class name for a TextArea is text-area. It does not add any CSS properties to the ones present in its ancestor TextInputControl. It contains scroll-pane and content substructures, which are a ScrollPane and a Region, respectively. The scroll-pane is the scroll pane that appears when its text exceeds its width or height. The content is the region that displays the text.

Styling ProgressIndicator with CSS

The default CSS style class name for a ProgressIndicator is progress-indicator. ProgressIndicator supports determinate and indeterminate CSS pseudo-classes. The determinate pseudo-class applies when the indeterminate property is false. The indeterminate pseudo-class applies when the indeterminate property is true.

You can style all substructures of a ProgressIndicator. Please refer to the modena.css file for sample code.

Styling ProgressIndicator and ProgressBar with CSS

All properties apply to the bar that shows the indeterminate progress. The default bar length is 60px. Use the -fx-indeterminate-bar-length property to specify a different bar length.

When the -fx-indeterminate-bar-escape property is true, the bar starting edge starts at the starting edge of the track, and the bar trailing edge ends at the ending edge of the track. That is, the bar is displayed beyond the track length. When this property is false, the bar moves within the track length. The default value is true.

The -fx-indeterminate-bar-flip property indicates whether the bar moves only in one direction or both. The default value is true, which means the bar moves in both directions by flipping its direction at the end of each edge.

The -fx-indeterminate-bar-animation-time property is the time in seconds that the bar should take to go from one edge to the other. The default value is 2.

The following styles modify the background color and radius of the bar and track of the ProgressBar control to give it a look as shown in Figure 12-44:

.progress-bar .track  {

        -fx-background-color: lightgray;

        -fx-background-radius: 5;

}

.progress-bar .bar  {

        -fx-background-color: blue;

        -fx-background-radius: 5;

}

Styling TitledPane with CSS

The default values for both properties are true. The -fx-animated property indicates whether the expanding and collapsing actions are animated. The -fx-collapsible property indicates whether the control can be collapsed.

The collapsed pseudo-class applies when the control is collapsed, and the expanded pseudo-class applies when it is expanded.

The title substructure is a StackPane that contains the content of the title bar. The title substructure contains text and arrow-button substructures. The text substructure is a Label, and it holds the title text and the graphic. The arrow-button substructure is a StackPane that contains an arrow substructure, which is also a StackPane. The arrow substructure is an indicator that shows whether the control is in an expanded or collapsed state. The content substructure is a StackPane that contains the content of the control.

Style #1 sets the background color of the title to light gray and places the graphic and title at the center right in the title bar. Style #2 changes the font size of the title text to 14px and underlines it. Setting the text color of the title using the -fx-text-fill property does not work at the time of this writing, and setting the -fx-text-fill property on the TitledPane itself affects the text color of the content as well. Style #3 sets the background color of the arrow to blue. Style #4 sets the background color and padding of the content region. Figure 12-46 shows the same window as shown in Figure 12-45 after applying the preceding styles.

Styling Accordion with CSS

Styling Pagination with CSS

The -fx-max-page-indicator-count property specifies the maximum number of page indicators to display. The default value is ten. The -fx-arrows-visible property specifies whether the previous and next page buttons are visible. The default value is true. The -fx-tooltip-visible property specifies whether a tool tip is displayed when the mouse hovers over a page indicator. The default value is true. The -fx-page-information-visible specifies whether the selected page label is visible. The default value is true. The -fx-page-information-alignment specifies the location of the selected page label relative to the page indicators. The possible values are top, right, bottom, and left. The default value is bottom, which displays the selected page indicator below the page indicators.

The left-arrow-button and right-arrow-button substructures are of the Button type. They represent the previous and next page buttons, respectively. The left-arrow-button substructure has a left-arrow substructure, which is a StackPane, and it represents the arrow in the previous page button. The right-arrow-button substructure has a right-arrow substructure, which is a StackPane, and it represents the arrow in the next page button. The bullet-button and number-button are of the ToggleButton type, and they represent the page indicators. The page-information substructure is a Label that holds the selected page information. The pagination-control substructure holds the previous and next page buttons and the page indicators in a substructure called control-box, which is an HBox.

Styling Tooltip with CSS

Understanding the ScrollBar Control

ScrollBar is a basic control that does not provide the scrolling feature by itself. It is represented as a horizontal or vertical bar that lets users choose a value from a range of values. Figure 12-53 shows a horizontal and a vertical scrollbar.

The increment and decrement buttons in a vertical ScrollBar are on the bottom and top, respectively.

The blockIncrement and unitIncrement properties specify the amount to adjust the current value when the user clicks the track and the increment or decrement buttons, respectively. Typically, the block increment is set to a larger value than the unit increment.

The default CSS style class name for a ScrollBar control is scroll-bar. ScrollBar supports two CSS pseudo-classes: horizontal and vertical. Some of its properties can be set using CSS.

ScrollBar is rarely used directly by developers. It is used to build complete controls that support scrolling, for example, the ScrollPane control. If you need to provide scrolling capability to a control, use the ScrollPane, which I will discuss in the next section.

Understanding the ScrollPane Control

A ScrollPane provides a scrollable view of a node. A ScrollPane consists of a horizontal ScrollBar, a vertical ScrollBar, and a content node. The node for which the ScrollPane provides scrolling is the content node. If you want to provide a scrollable view of multiple nodes, add them to a layout pane, for example, a GridPane, and then add the layout pane to the ScrollPane as the content node. ScrollPane uses a scroll policy to specify when to show a specific scrollbar. The area through which the content is visible is known as viewport. Figure 12-54 shows a ScrollPane with a Label as its content node.

The content property is an object property of the Node type, and it specifies the content node. You can scroll the content using the scrollbars or by panning. If you use panning, you need to drag the mouse while left, right, or both buttons are pressed to scroll the content. By default, a ScrollPane is not pannable, and you need to use the scrollbars to scroll through the content. The pannable property is a boolean property that specifies whether the ScrollPane is pannable. Use the setPannable(true) method to make a ScrollPane pannable.

The fitToHeight and fitToWidth properties specify whether the content node is resized to match the height and width of the viewport, respectively. By default, they are false. These properties are ignored if the content node is not resizable. Figure 12-55 shows the same ScrollPane as shown in Figure 12-54 with its fitToHeight and fitToWidth properties set to true. Notice that the Label content node has been resized to fit into the viewport.

The hbarPolicy and vbarPolicy properties are object properties of the ScrollPane.ScrollBarPolicy enum type. They specify when to show the horizontal and vertical scrollbars. The possible values are ALWAYS, AS_NEEDED, and NEVER. When the policy is set to ALWAYS, the scrollbar is shown all the time. When the policy is set to AS_NEEDED, the scrollbar is shown when required based on the size of the content. When the policy is set to NEVER, the scrollbar is never shown.

The hmin, hmax, and hvalue properties specify the min, max, and value properties of the horizontal scrollbar, respectively. The vmin, vmax, and vvalue properties specify the min, max, and value properties of the vertical scrollbar, respectively. Typically, you do not set these properties. They change based on the content and as the user scrolls through the content.

The prefViewportHeight and prefViewportWidth are the preferred height and width, respectively, of the viewport that is available to the content node.

The default CSS style class name for a ScrollPane control is scroll-pane. Please refer to the modena.css file for sample styles and the online JavaFX CSS Reference Guide for the complete list of CSS properties and pseudo-classes supported by the ScrollPane.

Understanding the Separator Control

A Separator is a horizontal or vertical line that separates two groups of controls. Typically, they are used in menus or combo boxes. Figure 12-56 shows menu items of a restaurant separated by horizontal and vertical separators.

A separator resizes itself to fill the space allocated to it. A horizontal Separator resizes horizontally, and a vertical Separator resizes vertically. Internally, a Separator is a Region. You can change its color and thickness using a CSS.

The orientation property specifies the orientation of the control. The possible values are one of the two constants of the Orientation enum: HORIZONTAL and VERTICAL. The halignment property specifies the horizontal alignment of the separator line within the width of a vertical separator. This property is ignored for a horizontal separator. The possible values are one of the constants of the HPos enum: LEFT, CENTER, and RIGHT. The default value is CENTER. The valignment property specifies the vertical alignment of the separator line within the height of a horizontal separator. This property is ignored for a vertical separator. The possible values are one of the constants of the VPos enum: BASELINE, TOP, CENTER, and BOTTOM. The default value is CENTER.

Styling Separator with CSS

Understanding the SplitPane Control

SplitPane arranges multiple nodes by placing them horizontally or vertically separated by a divider. The divider can be dragged by the user, so the node on one side of the divider expands, and the node on the other side shrinks by the same amount. Typically, each node in a SplitPane is a layout pane containing some controls. However, you can use any node, for example, a Button. If you have used Windows Explorer, you are already familiar with using a SplitPane. In a Windows Explorer, the divider separates the tree view and the list view. Using the divider, you can resize the width of the tree view, and the width of the list view resizes with the equal amount in the opposite direction. A resizable HTML frameset works similar to a SplitPane. Figure 12-57 shows a window with a horizontal SplitPane. The SplitPane contains two VBox layout panes; each of them contains a Label and a TextArea. Figure 12-57 shows the divider dragged to the right, so the left VBox gets more width than the right one.

The setDividerPositions() method takes the positions of multiple dividers. You must provide positions for all dividers from starting up to the one you want to set the positions.

If you want to set the position for a specific divider, use the setDividerPosition() method. The first divider has the index 0. Positions passed in for an index outside the range are ignored.

The getDividerPositions() method returns the positions of all dividers. It returns a double array. The index of dividers matches the index of the array elements.

Styling SplitPane with CSS

The default CSS style class name for a SplitPane control is split-pane. SplitPane contains -fx-orientation CSS properties, which determine its orientation. The possible values are horizontal and vertical.

The split-pane-divider substructure contains a grabber substructure, which is a StackPane. Its CSS style class name is horizontal-grabber for a horizontal SplitPane and vertical-grabber for a vertical SplitPane. The grabber is shown in the middle of the divider.

Styling Slider with CSS

You can give the thumb any shape using the -fx-shape CSS property. The following code gives the thumb a triangular shape. The triangle is inverted for a horizontal slider and is pointed to the right for a vertical slider. Figure 12-60 shows a horizontal slider with the thumb.

/* An inverted triangle */

.slider > .thumb {

        -fx-shape: "M0, 0L10, 0L5, 10 Z";

}

/* A triangle pointing to the right, only if orientation is vertical */

.slider:vertical > .thumb {

        -fx-shape: "M0, 0L10, 5L0, 10 Z";

}

The following code gives the thumb a shape of a triangle placed beside a rectangle. The triangle is inverted for a horizontal slider and is pointed to the right for a vertical slider. Figure 12-61 shows a horizontal slider with the thumb.

/* An inverted triangle below a rectangle*/

.slider > .thumb {

        -fx-shape: "M0, 0L10, 0L10, 5L5, 10L0, 5 Z";

}

/* A triangle pointing to the right by the right side of a rectangle */

.slider:vertical > .thumb {

        -fx-shape: "M0, 0L5, 0L10, 5L5, 10L0, 10 Z";

}

Using Menu Bars

Using Menus

A menu contains a list of actionable items, which are displayed on demand, for example, by clicking it. The list of menu items is hidden when the user selects an item or moves the mouse pointer outside the list. A menu is typically added to a menu bar or another menu as a submenu.

The onShowing event handler is called just before the menu items for the menu is shown. The onShown event handler is called after the menu items are displayed. The onHiding and onHidden event handlers are the counterparts of the onShowing and onShown event handlers, respectively.

The showing property is a read-only boolean property. It is set to true when the items in the menu are showing. It is set to false when they are hidden.

The program in Listing 12-37 puts this all together. It creates four menus, a menu bar, adds menus to the menu bar, and adds the menu bar to the top region of a BorderPane. Figure 12-63 shows the menu bar in the window. But you have not seen anything exciting about menus yet! You will need to add menu items to the menus to experience some excitement.

// MenuTest.java

package com.jdojo.control;

import javafx.application.Application;

import javafx.scene.Scene;

import javafx.scene.control.Menu;

import javafx.scene.control.MenuBar;

import javafx.scene.layout.BorderPane;

import javafx.stage.Stage;

public class MenuTest extends Application {

        public static void main(String[] args) {

                Application.launch(args);

        }

        @Override

        public void start(Stage stage) {

                // Create some menus

                Menu fileMenu = new Menu("File");

                Menu editMenu = new Menu("Edit");

                Menu optionsMenu = new Menu("Options");

                Menu helpMenu = new Menu("Help");

                // Add menus to a menu bar

                MenuBar menuBar = new MenuBar();

                menuBar.getMenus().addAll(

                         fileMenu, editMenu, optionsMenu, helpMenu);

                BorderPane root = new BorderPane();

                root.setTop(menuBar);

                root.setStyle("""

                         -fx-padding: 10;

                   -fx-border-style: solid inside;

                   -fx-border-width: 2;

                   -fx-border-insets: 5;

                   -fx-border-radius: 5;

                   -fx-border-color: blue;""");

                Scene scene = new Scene(root);

                stage.setScene(scene);

                stage.setTitle("Using Menus");

                stage.show();

        }

}

Listing 12-37

Creating a Menu Bar and Adding Menus to It

Using Menu Items

A menu item is an actionable item in a menu. The action associated with a menu item is performed by the mouse or keys. Menu items can be styled using a CSS.

An instance of the MenuItem class represents a menu item. The MenuItem class is not a node. It is inherited from the Object class and, therefore, cannot be added directly to a scene graph. You need to add it to a menu.

You can add several types of menu items to a menu. Figure 12-64 shows the class diagram for the MenuItem class and its subclasses that represent a specific type of menu item.

I will discuss all menu item types in detail in the sections to follow.

Using a MenuItem

A MenuItem represents an actionable option. When it is clicked, the registered ActionEvent handlers are called. The following snippet of code creates an Exit MenuItem and adds an ActionEvent handler that exits the application:

MenuItem exitItem = new MenuItem("Exit");

exitItem.setOnAction(e -> Platform.exit());

A MenuItem is added to a menu. A menu stores the reference of its MenuItems in an ObservableList<MenuItem> whose reference can be obtained using the getItems() method:

Menu fileMenu = new Menu("File");

fileMenu.getItems().add(exitItem);

The MenuItem class contains the following properties that apply to all types of menu items:

• text

• graphic

• disable

• visible

• accelerator

• mnemonicParsing

• onAction

• onMenuValidation

• parentMenu

• parentPopup

• style

• id

The text and graphic properties are the text and graphics for the menu item, respectively, which are of String and Node types. The disable and visible properties are boolean properties. They specify whether the menu item is disabled and visible. The accelerator property is an object property of the KeyCombination type that specifies a key combination that can be used to execute the action associated with the menu item in one keystroke. The following snippet of code creates a Rectangle menu item and sets its accelerator to Alt + R. The accelerator for a menu item is shown next to it, as shown in Figure 12-65, so the user can learn about it by looking at the menu item. The user can activate the Rectangle menu item directly by pressing Alt + R.

MenuItem rectItem = new MenuItem("Rectangle");

KeyCombination kr = new KeyCodeCombination(KeyCode.R, KeyCombination.ALT_DOWN);

rectItem.setAccelerator(kr);

The mnemonicParsing property is a boolean property. It enables or disables text parsing to detect a mnemonic character. By default, it is set to true for menu items. If it is set to true, the text for the menu item is parsed for an underscore character. The character following the first underscore is added as the mnemonic for the menu item. Pressing the Alt key on Windows highlights mnemonics for all menu items. Typically, mnemonic characters are shown in an underlined font style. Pressing the key for the mnemonic character activates the menu item.

// Create a menu item with x as its mnemonic character

MenuItem exitItem = new MenuItem("E_xit");

The onAction property is an ActionEvent handler that is called when the menu item is activated, for example, by clicking it with a mouse or pressing its accelerator key:

// Close the application when the Exit menu item is activated

exitItem.setOnAction(e -> Platform.exit());

The onMenuValidation property is an event handler that is called when a MenuItem is accessed using its accelerator or when the onShowing event handler for its menu (the parent) is called. For a menu, this handler is called when its menu items are shown.

The parentMenu property is a read-only object property of the Menu type. It is the reference of the Menu, which contains the menu item. Using this property and the items list returned by the getItems() method of the Menu class, you can navigate the menu tree from top to bottom and vice versa.

The parentPopup property is a read-only object property of the ContextMenu type. It is the reference of the ContextMenu in which the menu item appears. It is null for a menu item appearing in a normal menu.

The style and ID properties are included to support styling using a CSS. They represent the CSS style and ID.

Using a RadioMenuItem

A RadioMenuItem represents a mutually exclusive option. Typically, you add RadioMenuItem in multiples to a ToggleGroup, so only one item is selected. RadioMenuItem displays a check mark when selected. The following snippet of code creates three instances of RadioMenuItem and adds them to a ToggleGroup. Finally, they are all added to a File Menu. Typically, a RadioMenuItem in a group is selected by default. Figure 12-66 shows the group of RadioMenuItems: once when Rectangle is selected and once when Circle is selected.

// Create three RadioMenuItems

RadioMenuItem rectItem = new RadioMenuItem("Rectangle");

RadioMenuItem circleItem = new RadioMenuItem("Circle");

RadioMenuItem ellipseItem = new RadioMenuItem("Ellipse");

// Select the Rantangle option by default

rectItem.setSelected(true);

// Add them to a ToggleGroup to make them mutually exclusive

ToggleGroup shapeGroup = new ToggleGroup();

shapeGroup.getToggles().addAll(rectItem, circleItem, ellipseItem);

// Add RadioMenuItems to a File Menu

Menu fileMenu = new Menu("File");

fileMenu.getItems().addAll(rectItem, circleItem, ellipseItem);

Add an ActionEvent handler to the RadioMenuItem if you want to perform an action when it is selected. The following snippet of code adds an ActionEvent handler to each RadioMenuItem, which calls a draw() method:

rectItem.setOnAction(e -> draw());

circleItem.setOnAction(e -> draw());

ellipseItem.setOnAction(e -> draw());

Using a Submenu Item

Notice that the Menu class is inherited from the MenuItem class. This makes it possible to use a Menu in place of a MenuItem. Use a Menu as a menu item to create a submenu. When the mouse hovers over a submenu, its list of options is displayed.

The following snippet of code creates a MenuBar, adds a File menu, adds New and Open MenuItems and a Save As submenu to the File menu, and adds Text and PDF menu items to the Save As submenu. It produces a menu as shown in Figure 12-67.

MenuBar menuBar = new MenuBar();

Menu fileMenu = new Menu("File");

menuBar.getMenus().addAll(fileMenu);

MenuItem newItem = new MenuItem("New");

MenuItem openItem = new MenuItem("Open");

Menu saveAsSubMenu = new Menu("Save As");

// Add menu items to the File menu

fileMenu.getItems().addAll(newItem, openItem, saveAsSubMenu);

MenuItem textItem = new MenuItem("Text");

MenuItem pdfItem = new MenuItem("PDF");

saveAsSubMenu.getItems().addAll(textItem, pdfItem);

Typically, you do not add an ActionEvent handler for a submenu. Rather, you set an event handler to the onShowing property that is called before the list of items for the submenu is displayed. The event handler is used to enable or disable menu items.

Using a CustomMenuItem

CustomMenuItem is a simple yet powerful menu item type. It opens the door for all kinds of creativity for designing menu items. It lets you use any node. For example, you can use a Slider, a TextField, or an HBox as a menu item. The CustomMenuItem class contains two properties:

• content

• hideOnClick

The content property is an object property of the Node type. Its value is the node that you want to use as the menu item.

When you click a menu item, all visible menus are hidden, and only top-level menus in the menu bar stay visible. When you use a custom menu item that has controls, you do not want to hide menus when the user clicks it because the user needs to interact with the menu item, for example, to enter or select some data. The hideOnClick property is a boolean property that lets you control this behavior. By default, it is set to true, which means clicking a custom menu hides all showing menus.

The CustomMenuItem class provides several constructors. The default constructor creates a custom menu item setting the content property to null and the hideOnClick property to true, as shown in the following code:

// Create a Slider control

Slider slider = new Slider(1, 10, 1);

// Create a custom menu item and set its content and hideOnClick properties

CustomMenuItem cmi1 = new CustomMenuItem();

cmi1.setContent(slider);

cmi1.setHideOnClick(false);

// Create a custom menu item with a Slider content and

// set the hideOnClick property to false

CustomMenuItem cmi2 = new CustomMenuItem(slider);

cmi1.setHideOnClick(false);

// Create a custom menu item with a Slider content and false hideOnClick

CustomMenuItem cmi2 = new CustomMenuItem(slider, false);

The following snippet of code produces a menu as shown in Figure 12-68. One of the menu items is a CustomMenuItem, which uses a slider as its content:

CheckMenuItem strokeItem = new CheckMenuItem("Draw Stroke");

strokeItem.setSelected(true);

Slider strokeWidthSlider = new Slider(1, 10, 1);

strokeWidthSlider.setShowTickLabels(true);

strokeWidthSlider.setShowTickMarks(true);

strokeWidthSlider.setMajorTickUnit(2);

CustomMenuItem strokeWidthItem = new CustomMenuItem(strokeWidthSlider, false);

Menu optionsMenu = new Menu("Options");

optionsMenu.getItems().addAll(strokeItem, strokeWidthItem);

MenuBar menuBar = new MenuBar();

menuBar.getMenus().add(optionsMenu);

Putting All Parts of Menus Together

Understanding the parts of menus is easy. However, using them in code is tricky because you have to create all parts separately, add listeners to them, and then assemble them.

The program in Listing 12-38 creates a shape drawing application using menus. It uses all types of menu items. The program displays a window with a BorderPane as the root of its scene. The top region contains a menu, and the center region contains a canvas on which shapes are drawn.

Run the application and use the File menu to draw different types of shapes; clicking the Clear menu item clears the canvas. Clicking the Exit menu item closes the application.

Styling Menus Using CSS

MenuBar supports an -fx-use-system-menu-bar property, which is set to false by default. It indicates whether to use a system menu for the menu bar. It contains a menu substructure that holds the menus for the menu bar. Menu supports a showing CSS pseudo-class, which applies when the menu is showing. RadioMenuItem and CheckMenuItem support a selected CSS pseudo-class, which applies when the menu items are selected.

You can style several components of menus. Please refer to the modena.css file for the sample styles.

Styling ContextMenu with CSS

Styling a Toolbar with CSS

The default CSS style class name for a ToolBar is tool-bar. It contains an -fx-orientation CSS property that specifies its orientation with the possible values of horizontal and vertical. It supports horizontal and vertical CSS pseudo-classes that apply when its orientation is horizontal and vertical, respectively.

A toolbar contains a tool-bar-overflow-button substructure to represent the overflow button. It is a StackPane. The tool-bar-overflow-button contains an arrow substructure to represent the arrow in the overflow button. It is also a StackPane.

Creating Tabs

Setting the Title and Content of Tabs

The closable property is a boolean property that specifies whether the tab can be closed. If it is set to false, the tab cannot be closed. Closing of tabs is also controlled by the tab-closing policy of the TabPane. If the closable property is set to false, the tab cannot be closed by the user, irrespective of the tab-closing policy of the TabPane. You will learn about tab-closing policy when I discuss the TabPane later.

Creating TabPanes

Adding Tabs to a TabPane

The read-only tabPane property of the Tab class stores the reference of the TabPane that contains the tab. If a tab has not yet been added to a TabPane, its tabPane property is null. Use the getTabPane() method of the Tab class to get the reference of the TabPane.

Putting TabPanes and Tabs Together

Understanding Tab Selection

TabPane supports a single selection model, which allows selecting only one tab at a time. If a tab is selected by the user or programmatically, the previously selected tab is unselected. The Tab class provides the API to allow working with the selection state of an individual tab. The TabPane class provides the API that allows working with the selection of all of its tabs.

The Tab class contains a read-only selected property of the boolean type. It is true when the tab is selected. Otherwise, it is false. Note that it is a property of the Tab, not the TabPane.

Use the selectNext() method of the selection model to select the next tab from the list. Calling this method when the last tab is already selected has no effect.

Use the selectPrevious() and selectLast() methods to select the previous and the last tabs in the list. The select(int index) and select(T item) methods select a tab using the index and reference of the tab.

Closing Tabs in a TabPane

Sometimes, the user needs to add tabs to a TabPane on demand, and they should be able to close tabs as well. For example, all modern web browsers use tabs for browsing and let you open and close tabs. Adding tabs on demand requires some coding in JavaFX. However, closing tabs by the user is built in the Tab and TabPane classes.

ALL_TABS means the close button is available for all tabs. That is, any tab can be closed at any time provided the closable property of the tab is true. SELECTED_TAB means the close button appears only for the selected tab. That is, only the selected tab can be closed at any time. This is the default tab-closing policy of a TabPane. UNAVAILABLE means the close button is not available for any tabs. That is, no tabs can be closed by the user, irrespective of their closable properties.

Both have the same effect, that Tabs are removed from the TabPane. The discussion in this section applies to closing tabs by the user.

Positioning Tabs in a TabPane

Figure 12-73 shows the title bar of a tab in a TabPane with the side property set to TOP and LEFT. Notice the effect on the graphics when the side property is LEFT and the rotateGraphic property is false and true. The rotateGraphic property has no effect when tabs are positioned at the top or bottom.

Sizing Tabs in a TabPane

The default values are zero for minimum width and height, and Double.MAX_VALUE for maximum width and height. The default size is computed based on the context of the tab titles. If you want all tab titles to be of a fixed size, set the minimum and maximum width and height to the same value. Note that for the fixed size tabs, the longer text in the title bar will be truncated.

Using Recessed and Floating TabPanes

Figure 12-74 shows two windows with the same TabPane: one in the recessed mode and one in the floating mode.

Styling Tab and TabPane with CSS

The default CSS style class name for a tab and for a TabPane is tab-pane. You can style Tabs directly using the tab style class or using the substructure of TabPane. The latter approach is commonly used.

The control-buttons-tab substructure contains a tab-down-button substructure, which contains an arrow substructure. The tab substructure contains tab-label and tab-close-button substructures. The tab-content-area substructure represents the content area of the TabPane. Substructures let you style different parts of TabPane.

Please refer to the modena.css file for the complete list of styles used for TabPane.

Creating an HTMLEditor

Using an HTMLEditor

The getHTMLText() method returns the HTML content as a string. The setHTMLText() method sets the content of the control to the specified HTML string. The print() method prints the content of the control.