• Creating a Stage
• Showing a Stage
  • show() vs. showAndWait()
• Set a Scene on a Stage
• Stage Title
• Stage Position
• Stage Width and Height
• Stage Modality
• Stage Owner
• Stage Style
• Stage Full Screen Mode
• Stage Life Cycle Events
  • Close Stage Event Listener
  • Hiding Stage Event Listener
  • Hidden Stage Event Listener
  • Showing Stage Event Listener
  • Shown Stage Event Listener
• Stage Keyboard Events

 

A JavaFX Stage, javafx.stage.Stage, represents a window in a JavaFX desktop application. Inside a JavaFX Stage you can insert a JavaFX Scene which represents the content displayed inside a window - inside a Stage.

When a JavaFX application starts up, it creates a root Stage object which is passed to the start(Stage primaryStage) method of the root class of your JavaFX application. This Stage object represents the primary window of your JavaFX application. You can create new Stage objects later in your application's life time, in case your application needs to open more windows.

Creating a Stage

You create a JavaFX Stage object just like any other Java object: Using the new command and the Stage constructor. Here is an example of creating a JavaFX Stage object.

Stage stage = new Stage();

Showing a Stage

Simple creating a JavaFX Stage object will not show it. In order to make the Stage visible you must call either its show() or showAndWait() method. Here is an example of showing a JavaFX Stage:

Stage stage = new Stage();
stage.show();

show() vs. showAndWait()

The difference between the JavaFX Stage methods show() and showAndWait() is, that show() makes the Stage visible and the exits the show() method immediately, whereas the showAndWait() shows the Stage object and then blocks (stays inside the showAndWait() method) until the Stage is closed.

Set a Scene on a Stage

In order to display anything inside a JavaFX Stage, you must set a JavaFX Scene object on the Stage. The content of the Scene will then be displayed inside the Stage when the Stage is shown. Here is an example of setting a Scene on a JavaFX Stage:

VBox vBox = new VBox(new Label("A JavaFX Label"));
Scene scene = new Scene(vBox);

Stage stage = new Stage();
stage.setScene(scene);

Stage Title

You can set the JavaFX Stage title via the Stage setTitle() method. The Stage title is displayed in the title bar of the Stage window. Here is an example of setting the title of a JavaFX Stage:

stage.setTitle("JavaFX Stage Window Title");

Stage Position

You can set the position (X,Y) of a JavaFX Stage via its setX() and setY() methods. The setX() and setY() methods set the position of the upper left corner of the window represented by the Stage. Here is an example of setting the X and Y position of a JavaFX Stage object:

Stage stage = new Stage();

stage.setX(50);
stage.setY(50);

Please note, that it might be necessary to also set the width and height of the Stage if you set the X and Y position, or the stage window might become very small. See the next section for more information about setting the width and height of a Stage.

Stage Width and Height

You can set the width and of a JavaFX Stage via its setWidth() and setHeight() methods. Here is an example of setting the width and height of a JavaFX Stage:

Stage stage = new Stage();

stage.setWidth(600);
stage.setHeight(300);

Stage Modality

You can set window modality of a JavaFX Stage. The Stage modality determines if the window representing the Stage will block other windows opened by the same JavaFX application. You set the window modality of a JavaFX Stage via its initModality() method. Here is an example of setting the JavaFX Stage modality:

public class StageExamples extends Application {
    public static void main(String[] args) {
        launch(args);
    }

    @Override
    public void start(Stage primaryStage) {
        primaryStage.setTitle("JavaFX App");

        Stage stage = new Stage();
        stage.initModality(Modality.APPLICATION_MODAL);
        //stage.initModality(Modality.WINDOW_MODAL);
        //stage.initModality(Modality.NONE);

        primaryStage.show();

        stage.showAndWait();

    }
}

Notice how this example is a full JavaFX application. The start() method is executed when the JavaFX application is launched (first main() is called which calls launch() which later calls start()).

Notice also, how a new JavaFX Stage object is created, its modality mode set, and then both the primary and the new Stage objects are made visible (shown). The second Stage has its modality set to Modality.APPLICATION_MODAL meaning it will block all other windows (stages) opened by this JavaFX application. You cannot access any other windows until this Stage window has been closed.

The Modality.WINDOW_MODAL modality option means that the newly created Stage will block the Stage window that "owns" the newly created Stage, but only that. Not all windows in the application. See the next section below to see how to set the "owner" of a Stage.

The Modality.NONE modality option means that this Stage will not block any other windows opened in this application.

The Modality.APPLICATION_MODAL and Modality.WINDOW_MODAL modality modes are useful for Stage objects representing windows that function as "wizards" or "dialogs" which should block the application or window until the wizard or dialog process is completed by the user. The Modality.NONE modality is useful for Stage objects representing windows that can co-exist, like different browser windows in a browser application.

Stage Owner

A JavaFX Stage can be owned by another Stage. You set the owner of a Stage via its initOwner() method. Here is an example of initializing the owner of a JavaFX Stage, plus set the modality of the Stage to Modality.WINDOW_MODAL:

public class StageExamples extends Application {
    public static void main(String[] args) {
        launch(args);
    }

    @Override
    public void start(Stage primaryStage) {
        primaryStage.setTitle("JavaFX App");

        Stage stage = new Stage();
        stage.initModality(Modality.WINDOW_MODAL);

        stage.initOwner(primaryStage);

        primaryStage.show();

        stage.showAndWait();
    }
}

This example will open a new Stage which will block the Stage owning the newly created Stage (which is set to the primary stage).

Stage Style

You can set the style of a JavaFX Stage via its initStyle() method. There are a set of different styles you can choose from:

• DECORATED
• UNDECORATED
• TRANSPARENT
• UNIFIED
• UTILITY

A decorated Stage is a standard window with OS decorations (title bar and minimize / maximize / close buttons), and a white background.

An undecorated Stage is a standard window without OS decorations, but still with a white background.

A transparent Stage is an undecorated window with transparent background.

A unified Stage is like a decorated stage, except it has no border between the decoration area and the main content area.

A utility Stage is a decorated window, but with minimal decorations.

Here is an example of setting the style of a JavaFX Stage:

stage.initStyle(StageStyle.DECORATED);

//stage.initStyle(StageStyle.UNDECORATED);
//stage.initStyle(StageStyle.TRANSPARENT);
//stage.initStyle(StageStyle.UNIFIED);
//stage.initStyle(StageStyle.UTILITY);

Only the first line is actually executed. The rest are commented out. They are just there to show how to configure the other options.

Stage Full Screen Mode

You can switch a JavaFX Stage into full screen mode via the Stage setFullScreen() method. Please note, that you may not get the expected result (a window in full screen mode) unless you set a Scene on the Stage. Here is an example of setting a JavaFX Stage to full screen mode:

VBox vbox = new VBox();
Scene scene = new Scene(vbox);

primaryStage.setScene(scene);
primaryStage.setFullScreen(true);

primaryStage.show();

Stage Life Cycle Events

The JavaFX Stage can emit a few events you can listen for. These Stage events are:

• Close Request
• Hiding
• Hidden
• Showing
• Shown

Close Stage Event Listener

You can listen for close events on a JavaFX Stage, meaning you can be notified when the user clicks the button with the X on, in the upper right corner of the Stage window. Listening for the Stage close event can be useful if you need to clean up some resources after the main Stage window is closed, or e.g. need to stop some threads etc. Here is an example of listening for Stage close events:

primaryStage.setOnCloseRequest((event) -> {
    System.out.println("Closing Stage");
});

Hiding Stage Event Listener

You can attach a Stage hiding event listener to a JavaFX stage. The Stage hiding event listener is called before the Stage is being hidden, but after it has been requested hidden. Here is an example of attaching a Stage hiding event listener to a JavaFX Stage:

primaryStage.setOnHiding((event) -> {
    System.out.println("Hiding Stage");
});

Hidden Stage Event Listener

You can attach a Stage hidden event listener to a JavaFX stage. The Stage hidden event listener is called after the Stage is hidden. Here is an example of attaching a Stage hidden event listener to a JavaFX Stage:

primaryStage.setOnHidden((event) -> {
    System.out.println("Stage hidden");
});

Showing Stage Event Listener

You can attach a Stage showing event listener to a JavaFX stage. The Stage showing event listener is called after the Stage is requested shown, but before the Stage is shown. Here is an example of attaching a Stage showing event listener to a JavaFX Stage:

primaryStage.setOnShowing((event) -> {
    System.out.println("Showing Stage");
});

Shown Stage Event Listener

You can attach a Stage shown event listener to a JavaFX stage. The Stage shown event listener is called after the Stage is shown. Here is an example of attaching a Stage shown event listener to a JavaFX Stage:

primaryStage.setOnShown((event) -> {
    System.out.println("Stage Shown");
});

Stage Keyboard Events

It is possible to listen for keyboard events on a JavaFX Stage. That way you can catch all keyboard events that occur while the Stage has focus. Here is an example that listens for the ESC and Return keys on the keyboard - when a JavaFX Stage has focus:

primaryStage.addEventHandler(KeyEvent.KEY_PRESSED,  (event) -> {
    System.out.println("Key pressed: " + event.toString());

    switch(event.getCode().getCode()) {
        case 27 : { // 27 = ESC key
            primaryStage.close();
            break;
        }
        case 10 : { // 10 = Return
            primaryStage.setWidth( primaryStage.getWidth() * 2);
        }
        default:  {
            System.out.println("Unrecognized key");
        }
    }
});

Next: JavaFX Scene