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();
    }
}