Secondary Windows

How SwingBridge renders secondary Swing windows, and how to control whether a JFrame is modal.

How Modality Is Decided
Controlling JFrame Modality
Next Steps

When your Swing application opens a second top-level window on top of its main frame, SwingBridge surfaces that window in the browser as a Vaadin overlay. This applies to JDialog, JFrame, and JWindow. Popups, menus, and tooltips are handled separately and are always non-modal.

This page explains how the modality of a secondary window is decided, and how to control it for a JFrame.

How Modality Is Decided

Whether a secondary window is rendered modal (it blocks interaction with everything behind it) or modeless (the rest of the UI stays interactive) depends on the window type:

Window type Modality

Window type	Modality
`JDialog`	Follows the dialog’s own modality — the value of its `isModal()` method. This mirrors what the Swing application already declared, so no extra configuration is needed.
`JFrame` / `JWindow`	Modeless by default. A `JFrame` is never modal in Swing — it never blocks other windows — so SwingBridge renders it modeless to match. Opt a specific frame into modal rendering with the hint described below.

JDialog

Follows the dialog’s own modality — the value of its isModal() method. This mirrors what the Swing application already declared, so no extra configuration is needed.

JFrame / JWindow

Modeless by default. A JFrame is never modal in Swing — it never blocks other windows — so SwingBridge renders it modeless to match. Opt a specific frame into modal rendering with the hint described below.

Controlling JFrame Modality

Some applications implement a secondary dialog as a JFrame rather than a JDialog, and still expect it to block the main frame. Because a JFrame has no modality property of its own, SwingBridge cannot infer this. Declare it explicitly by attaching a client-property hint to the frame’s root pane before the frame becomes visible.

The hint requires SwingBridge 1.2.1 or later. WindowHints lives in the swing-bridge-annotations JAR, the same compile-only JAR that holds the interoperability annotations. Add it to the Swing application’s build as described in Adding the Annotations JAR to the Swing Application. For Maven, that is:

Source code

XML<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>swing-bridge-annotations</artifactId>
    <version>1.3.0</version>
    <scope>provided</scope>
</dependency>

Keep its version in lockstep with SwingBridge on the Vaadin side. When the application runs embedded, SwingBridge supplies the WindowHints classes. Unlike the interoperability annotations, though, the code that sets the hint references WindowHints.Modality at runtime. If you still launch the Swing application as a standalone desktop application during the migration, put the JAR on the runtime classpath of that launch too, or the application fails with a NoClassDefFoundError when it sets the hint.

Then set the WindowHints.MODALITY client property to MODAL:

Source code

Javaimport com.vaadin.swingbridge.window.WindowHints;

JFrame frame = new JFrame("Edit Customer");
// ... build the frame's content ...

// Render this frame as a modal overlay in SwingBridge.
frame.getRootPane().putClientProperty(WindowHints.MODALITY,
        WindowHints.Modality.MODAL);

frame.setVisible(true);

The hint travels with the window itself, so it takes effect no matter which Vaadin route or SwingBridge instance renders the frame — you set it once, in your Swing code, at the point where the frame is shown.

Note	Set the hint before the frame becomes visible. SwingBridge reads it when it first surfaces the window, so changing it after the frame is shown has no effect.

To be explicit about a frame that should stay modeless, use WindowHints.Modality.MODELESS. Any JFrame or JWindow without the hint is already modeless, so this is only needed for readability.

Tip	This hint has no effect on a `JDialog`. A dialog’s real modality (`isModal()`) always wins, so continue to use `setModal(…)` on the `JDialog` itself.

Next Steps

Public API surface and lifecycle hooks: Reference.
Call into Swing code and listen to Swing events from Vaadin: Interoperability.

Docs