Stage – a JavaFX term for the window

Every UI app needs a window. In JavaFX, the javafx.stage.Stage class is responsible for that. The very first stage/windows are prepared for you by Application and your usual entry point for the app is method start, which has Stage as a parameter.

If you want to have more windows, just create a new Stage:

Stage anotherStage = new Stage();
stage2.show();

Working with Stage modality options

Modality determines whether events (for example, mouse clicks) will pass to an other application's windows. This is important as you would then need to show the user a modal dialog style window or a warning, which should be interacted with before any other action with the program.

Stage supports three options for modality:

• Modality.NONE: The new Stage won't block any events. This is the default.
• Modality.APPLICATION_MODAL: The new Stage will block events to all other application's windows.
• Modality.WINDOW_MODAL: The new Stage will block only events to hierarchy set by initOwner() methods.

These options can be set by calling the Stage.initModality() method.

The following sample shows how it works. Try to run it and close each window to check events handling, and see the comments inline:

// chapter1/FXModality.java
public class FXModality extends Application {
 
    @Override
    public void start(Stage stage1) {
        // here we create a regular window
        Scene scene = new Scene(new Group(), 300, 250);
        stage1.setTitle("Main Window");
        stage1.setScene(scene);
        stage1.show();
 
        // this window doesn't block mouse and keyboard events
        Stage stage2 = new Stage();
        stage2.setTitle("I don't block anything");
        stage2.initModality(Modality.NONE);
        stage2.show();

        // this window blocks everything - you can't interact 
        // with other windows while it's open
        Stage stage3 = new Stage();
        stage3.setTitle("I block everything");
        stage3.initModality(Modality.APPLICATION_MODAL);
        stage3.show();
 
        // this window blocks only interaction with it's owner window (stage1)
        Stage stage4 = new Stage();
        stage4.setTitle("I block only clicks to main window");
        stage4.initOwner(stage1);
        stage4.initModality(Modality.WINDOW_MODAL);
        stage4.show();
    }
}

Using Stage styles

Stage style is the way your window is decorated outside of the Scene.

You can control how Stage will look using StageStyle enum values. It can be passed to the constructor or through the initStyle() method:

// chapter1/StageStylesDemo
Stage stage = new Stage(StageStyle.UNDECORATED)
// or
stage.initStyle(StageStyle.TRANSPARENT)

See the existing options in the following figure. Note that a Windows screenshot was used here, but decorations will look different on other operating systems because they are a part of the OS user interface and not drawn by Java or JavaFX.

Setting fullscreen and other window options

There are several other options to manipulate Stage that are self-explanatory, like in the following examples:

// chapter1.StageFullScreen.java
stage.setFullScreen(true);
stage.setIconified(true);
stage.setMaxWidth(100); 
//...

The only unusual thing about this API is the extra fullscreen options—you can set up a warning message and key combination to exit fullscreen using the following methods:

 primaryStage.setFullScreenExitHint("Exit code is Ctrl+B");
 primaryStage.setFullScreenExitKeyCombination(KeyCombination.valueOf("Ctrl+B"));

Note the convenient KeyCombination class, which can parse names of shortcuts. If you prefer more strict methods, you can use KeyCodeCombination instead:

KeyCodeCombination kc = new KeyCodeCombination(KeyCode.B, KeyCombination.CONTROL_DOWN);