The Stage class is the top-level container for any JavaFX program that has a graphical UI. It has several properties and methods that allow it, for example, to be positioned, sized, given a title, made invisible, or given some degree of opacity. The two best ways that we know of to learn the capabilities of a class are to study the JavaFX API documentation and to examine (and write) programs that use it. In this section, we ask you to do both, beginning with looking at the API docs.

The JavaFX API docs may be found in the docs/api directory subordinate to where you installed the JavaFX SDK. Also, they are available online at the URL given in the Resources section at the end of this chapter. Open the index.html file in your browser, navigate to the javafx.stage package, and select the Stage class. That page should contain tables of Properties, Constructors, and Methods, including select ones shown in the excerpt in Figure 2-1.

Figure 2-1. A portion of the Stage class documentation in the JavaFX API

Go ahead and explore the documentation for each of the properties and methods in the Stage class, remembering to click the links to reveal more detailed information. When you’re finished, come back and we’ll show you a program that demonstrates many of the properties and methods available in the Stage class.

A screenshot of the unassuming, purposely ill-fitting StageCoach example program is shown in Figure 2-2.

Figure 2-2. A screenshot of the StageCoach example

The StageCoach program was created to coach you through the finer points of using the Stage class and related classes such as StageStyle and Screen. Also, we use this program to show you how to get arguments passed into the program.

Before walking through the behavior of the program, go ahead and open the project and execute it by following the instructions for building and executing the Audio-Config project in Chapter 1. The project file is located in the Chapter02 directory subordinate to where you extracted the book’s code download bundle.

Take a look at the code for the StageCoach program in Listing 2-1 before we point out new and relevant concepts.

Listing 2-1. StageCoachMain.java

The first new concept introduced by this program is the ability to read the arguments passed into a JavaFX program. The javafx.application package includes a class named Application that has application life cycle-related methods such as launch(), init(), start(), and stop(). Another method in the Application class is getParameters(), which gives the application access to the arguments passed on the command line, as well as unnamed parameters and <name,value> pairs specified in a JNLP file. Here’s the relevant code snippet from Listing 2-1 for your convenience:

We’re using the getParameters() method described previously to get an argument that tells us whether the stage style of the Stage instance should be its default (StageStyle.DECORATED), StageStyle.UNDECORATED, or StageStyle.TRANSPARENT. You saw the effects of each in the preceding exercise, specifically in Figures 2-2, 2-4, and 2-5.

As shown in the following excerpt from Listing 2-1, to make this application’s window initially resizable we’re calling the setResizable() method of the Stage instance. To keep the resizable property of the Stage and the state of the resizable check box synchronized, the check box is bidirectionally bound to the resizable property of the

Tip: A property that is bound cannot be explicitly set. In the code preceding the snippet, the resizable property is set with the setResizable() method before the property is bound in the next line.

Making the Stage show in full-screen mode is done by setting the fullScreen property of the Stage instance to true. As shown in the following snippet from Listing 2-1, to keep the fullScreen property of the Stage and the state of the fullScreen check box synchronized, the fullScreen property of the Stage instance is updated whenever the selected property of the checkBox changes.

The bounds of the Stage are represented by its x, y, width, and height properties, the values of which can be changed at will. This is demonstrated in the following snippet from Listing 2-1 where the Stage is placed near the top and centered horizontally on the primary screen after the Stage has been initialized.

We’re using the Screen class of the javafx.stage package to get the dimensions of the primary screen so that the desired position may be calculated.

Note: We intentionally made the Stage in Figure 2-2 larger than the Scene contained within to make the following point. The width and height of a Stage include its decorations (title bar and border), which vary on different platforms. It is therefore usually better to control the width and height of the Scene (we show you how in a bit) and let the Stage conform to that size.

As pointed out in Chapter 1, you can put rounded corners on a Rectangle by specifying the arcWidth and arcHeight for the corners. The following snippet from Listing 2-1 draws the sky-blue rounded rectangle that becomes the background for the transparent window example in Figure 2-5.

In this snippet, we use the three-argument constructor of Rectangle, in which the first two parameters specify the width and the height of the Rectangle. The third parameter defines the fill color of the Rectangle.

As you can detect from this code snippet, rounded rectangles are easily created using the arcWidth(double v) and arcHeight(double v) methods, where the parameter v defines the diameter of the arc.

The Stage may be dragged on the desktop using its title bar, but in the case where its StageStyle is UNDECORATED or TRANSPARENT, the title bar isn’t available. To allow dragging in this circumstance, we added the code shown in the following code snippet from Listing 2-1.

Event handlers are covered a little later in the chapter, but as a preview, the lambda expression that is supplied to the onMouseDragged() method is called when the mouse is dragged. As a result, the values of the x and y properties are altered by the number of pixels that the mouse was dragged, which moves the Stage as the mouse is dragged.

When developing applications that will be deployed in a cross-platform environment or are internationalized, it is good to use layout containers. One advantage of using layout containers is that when the node sizes change, their visual relationships with each other are predictable. Another advantage is that you don’t have to calculate the location of each node that you place in the UI.

The following snippet from Listing 2-1 shows how the VBox layout class, located in the javafx.scene.layout package, is used to arrange the Text, CheckBox, HBox, and Button nodes in a column. This snippet also shows that layout containers may be nested, as demonstrated by the HBox with the name titleBox that arranges the Label and TextField nodes horizontally. Note that several lines of code are omitted from this snippet to show the layout nesting clearly:

The VBox layout class is similar to the Group class discussed in the Hello Earthrise example in Chapter 1, in that it contains a collection of nodes within it. Unlike the Group class, the VBox class arranges its contained nodes vertically, spacing them apart from each other by the number of pixels specified in the spacing property.

To know whether your JavaFX application is the one that currently is in focus (e.g., keys pressed are delivered to the application), simply consult the focused property of the Stage instance. The following snippet from Listing 2-1 demonstrates this.

In the event that you want your JavaFX application to appear on top of other windows or behind other windows onscreen, you can use the toFront() and toBack() methods, respectively. The following snippet from Listing 2-1 shows how this is accomplished.

Once again, note how using lambda expressions enhances the readability of the code. It is clear from the first line of the snippet that a Button named toBackButton is created with a text toBack() being displayed on the button. The second line defines that when an action is performed on the button (i.e., the button is clicked), the stage is sent to the back.

Without using a lambda expression, the second line would be replaced by a call to an anonymous inner class as follows:

This approach not only requires more code, it doesn’t allow the Java runtime to optimize calls and it is much less readable.

As shown in the following code snippet from Listing 2-1, you can programmatically close the Stage with its close() method. This is important when the stageStyle is undecorated or transparent, because the close button supplied by the windowing system is not present.

By the way, you can detect when there is an external request to close the Stage by using the onCloseRequest event handler as shown in the following code snippet from Listing 2-1.

To see this in action, run the application without any arguments so that it has the appearance of Figure 2-2 shown previously, and then click the close button on the decoration of the window.

Tip: The onCloseRequest event handler is only called when there is an external request to close the window. This is why the “Stage is closing” message doesn’t appear in this example when you click the button labeled close( ).