Quarkus Desktop

Quarkus Desktop brings AWT and Swing desktop (GUI) applications to Quarkus, in JVM mode and as GraalVM native executables.

The Quarkus core extension io.quarkus:quarkus-awt supports headless Java2D, ImageIO and fonts, which server side applications need. The Quarkus Desktop extensions build on it (they include it) and add what GUI applications need: windows, printing, data transfer, input methods, sound, accessibility, and Swing.

This documentation is a work in progress.

Installation

Add one of the extensions to your build file. quarkus-desktop-swing includes quarkus-desktop-awt.

AWT

Maven
<dependency>
    <groupId>io.quarkiverse.desktop</groupId>
    <artifactId>quarkus-desktop-awt</artifactId>
    <version>0</version>
</dependency>
Gradle
implementation("io.quarkiverse.desktop:quarkus-desktop-awt:0")

Swing

Maven
<dependency>
    <groupId>io.quarkiverse.desktop</groupId>
    <artifactId>quarkus-desktop-swing</artifactId>
    <version>0</version>
</dependency>
Gradle
implementation("io.quarkiverse.desktop:quarkus-desktop-swing:0")

Supported platforms

Platform JVM mode Native executable

Windows x64

Yes

Yes: a native build on Windows, with Visual Studio (the C++ build tools). The executable is DPI aware, has the visual styles of Windows, can be a GUI application without console, and comes with the JDK libraries and the Visual C++ runtime it needs (see Windows). Verified with the showcase (see Verification): every page renders the same pixels and gives the same checks as in JVM mode, with the Direct3D, GDI and OpenGL pipelines at 100 % scale, and at 150 % with GDI (with Direct3D at a fractional scale, a few edge pixels of the Metal gradients vary from one run to the next, in JVM mode too: see the showcase README).

Windows arm64

Yes

No: GraalVM has no native image builder for Windows on arm64. JVM mode is verified by the continuous integration of the showcase (two JVM runs compared).

Linux x64 and arm64

Yes

Yes: a native build on Linux or in a container. The executable uses the X11 libraries of the system (XWayland on Wayland), GTK 3 for the GTK look and feel and the native dialogs, CUPS and ALSA (see Linux). Verified on both architectures by the continuous integration of the showcase (native builds and runs).

macOS (Apple silicon)

Yes

Yes, with the quarkus-awt of the Quarkus pull request "Enable quarkus-awt on macOS" (not in a Quarkus release yet), and GraalVM 25.1 or later (see macOS). Verified on an Apple silicon Mac and by the continuous integration of the showcase.

Native executables need GraalVM for JDK 25 and Quarkus 3.40.0 or later (on macOS: GraalVM 25.1 or later, and a Quarkus built from the pull request above).

Guides

  • Desktop AWT: how the extensions work, writing a desktop application, and building native executables.

  • Desktop Swing: look and feels, text, Synth, and what Swing applications need in native executables.

  • Application model and CDI: windows as CDI beans, the startup and the exit of the user interface, the event dispatch thread (EdtExecutor, Edt, @RunOnEdt), the application menu, Finder and Dock events of macOS, dev mode and tests.

Verification

The Quarkus Desktop showcase is an application of 75 pages (about 3800 checks) that exercise the AWT, Java2D, text, image, Swing, look and feel, data transfer, desktop, printing, accessibility, JavaBeans and sound features of the JDK. Its tools run it in JVM mode and as a native executable, render every page to an image and compare the two runs pixel by pixel and check by check, also with exact reachability metadata (see Exact reachability metadata). On Windows (with the Direct3D, GDI and OpenGL pipelines, and with exact reachability metadata), Linux and macOS, every page gives the same result in both runs, except the page that shows where a native executable legitimately differs (its known limitations, see Limitations). It also has a Docker image for the Linux runs, and the steps to verify macOS on a Mac.

Configuration

The properties are fixed when the native executable is built and only apply to native executables (JVM mode uses the java launcher and the JDK as they are), except the run time properties of the application model (quarkus.desktop.awt.startup-event.*, quarkus.desktop.awt.exit-on-last-window-closed) and quarkus.desktop.swing.look-and-feel, which also apply in JVM mode.

Property Default Description

quarkus.desktop.awt.startup-event.enabled

true, false in tests

Whether DesktopStartupEvent is fired, see Testing.

quarkus.desktop.awt.startup-event.mode

auto

manual: the application fires DesktopStartupEvent with DesktopLifecycle.start(), see Manual mode.

quarkus.desktop.awt.exit-on-last-window-closed

true

The application stops when its last visible window closes, see Closing windows and exit.

quarkus.desktop.awt.java-beans.jdk-classes

true

The bean properties of the AWT classes for the JavaBeans API (about 0.3 MB), see JavaBeans.

quarkus.desktop.awt.exact-reachability-metadata

detected

The lookups for native executables built with --exact-reachability-metadata (about 0.3 MB), see Exact reachability metadata.

quarkus.desktop.awt.windows.dpi-aware

true

Windows: the executable scales its user interface to the display, as the java launcher does.

quarkus.desktop.awt.windows.manifest

true

Windows: the application manifest of the java launcher (visual styles, DPI awareness).

quarkus.desktop.awt.windows.subsystem

console

Windows: windows for a GUI application without console window (as javaw).

quarkus.desktop.awt.windows.copy-vc-runtime

true

Windows: copies the Visual C++ runtime next to the executable.

quarkus.desktop.awt.windows.font-configuration

jdk

Windows: the font configuration of the JDK (all the languages), or minimal (Latin only).

quarkus.desktop.awt.windows.access-bridge

true

Windows: the Java Access Bridge for screen readers.

quarkus.desktop.awt.macos.park-main-thread

true

macOS: the first thread runs the Cocoa event loop, the application runs on a new thread named main.

quarkus.desktop.awt.macos.main-thread-stack-size

8M

macOS: the stack size of that main thread.

quarkus.desktop.awt.macos.exit-halt-timeout

10S

macOS: how long System.exit may take before the process is halted.

quarkus.desktop.awt.macos.application-name

quarkus.application.name

macOS: the name of the application in the menu bar and the Dock.

quarkus.desktop.awt.macos.info-plist

false

macOS: embeds an information property list in the executable.

quarkus.desktop.awt.macos.jdk-build-version

true

macOS: the executable declares the minimum macOS version and SDK version of the java launcher of the JDK (the look of the windows depends on them), see macOS.

quarkus.desktop.swing.look-and-feel

The look and feel set at startup (system, cross-platform, nimbus…​ or a class name), see Look and feel.

quarkus.desktop.swing.included-look-and-feels

all

The look and feels of the JDK included in the executable (about 10 MB for all of them).

quarkus.desktop.swing.java-beans.jdk-classes

false

The bean properties of the Swing classes for the JavaBeans API (3 to 4 MB), see JavaBeans.

See the configuration reference for the details.