The appearance and functionality of your stage will depend on the platform on which it is deployed. For example, if deployed in a web browser, your stage will be a rectangular area, called an applet, within a web page. The stage for a JavaFX program deployed via Java Web Start will be a window.
Understanding the Stage Class
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 topic. 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 as 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 show you a program that demonstrates many of the properties and methods available in the Stage class.
Using the Stage Class: The StageCoach Example
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.
EXAMINING THE BEHAVIOR OF THE STAGECOACH PROGRAM
When the program starts, its appearance should be similar to the screenshot in Figure 2-2. To fully examine its behavior, perform the following steps. Note that for instructional purposes, the property and method names on the UI correspond to the properties and methods in the Stage instance.
1. Notice that the StageCoach program’s window is initially displayed near the top of the screen, with its horizontal position in the center of the screen. Drag the program’s window and observe that the x and y values near the top of the UI are dynamically updated to reflect its position on the screen.
2. Resize the program’s window and observe that the width and height values change to reflect the width and height of the Stage. Note that this size includes the decorations (title bar and borders) of the window.
3. Click the program (or cause it to be in focus some other way) and notice that the focused value is true. Cause the window to lose focus, perhaps by clicking somewhere else on the screen, and notice that the focused value becomes false.
4. Deselect the resizable check box and then notice that the resizable value becomes false. Then try to resize the window and note that it is not permitted. Select the resizable check box again to make the window resizable.
5. Select the fullScreen check box. Notice that the program occupies the full screen and that the window decorations are not visible. Deselect the fullScreen check box to restore the program to its former size.
6. Edit the text in the text field beside the title label, noticing that the text in the window’s title bar is changed to reflect the new value.
7. Drag the window to partially cover another window, and click the toBack() button. Notice that this places the program behind the other window, therefore causing the z-order to change.
8. With a portion of the program’s window behind another window, but with the toFront() button visible, click that button. Notice that the program’s window is placed in front of the other window.
9. Click the close() button, noticing that the program exits.
10. Invoke the program again, passing in the string "undecorated". If invoking from NetBeans, use the Project Properties dialog to pass this argument as shown in Figure 2-3.
Figure 2-3. Using NetBeans’ Project Properties dialog to pass an argument into the program
11. Notice that this time the program appears without any window decorations, but that the white background of the program includes the background of the window. The black outline in the screenshot shown in Figure 2-4 is part of the desktop background.
12. Exit the program again by clicking the close() button, and then run the program again, passing in the string "transparent" as the argument. Notice that the program appears in the shape of a rounded rectangle, as shown in Figure 2-5.
Figure 2-4. The StageCoach program after being invoked with the undecorated argument
■ Note You may have noticed that the screenshots in Figures 2-4 and 2-5 have y values that are negative. This is because the application was positioned on the secondary monitor, logically above the primary monitor, when the screenshots were taken.
Figure 2-5. The StageCoach program after being invoked with the transparent argument
13. Click the application’s UI, drag it around the screen, and click the close() button when finished. Congratulations on sticking with this 13-step exercise! Performing this exercise has prepared you to relate to the code behind it, which we now walk through together.
Understanding the StageCoach Program
Take a look at the code for the StageCoach program in Listing 2-1, and after that we point out new and relevant concepts.
Listing 2-1. StageCoachMain.java
