Running Swing and JavaFX applications

An existing desktop application written with Swing and AWT, with the SwingX component set, or with JavaFX can build and run as a Codename One application without changes to its Java code. The desktop sources go into a Codename One project, the build maps them onto Codename One’s implementation of the java.awt, javax.swing, org.jdesktop.swingx and javafx.* APIs, and the result runs on every Codename One target: iOS, Android, the web, the native desktop ports and the simulator.

No desktop Java runtime is involved. Buttons, text fields, check boxes, sliders and tabs are Codename One components that take the platform’s theme, layout managers and layout panes run the rules they run on the desktop, and code that paints with Graphics2D or a JavaFX Canvas draws through Codename One’s graphics.

A Swing or JavaFX application that already works has three reasons to move.

It reaches every platform from one code base. The same sources build for iPhone and iPad, Android phones and tablets, the browser, and native Linux, macOS and Windows. Nothing is rewritten per platform, and the desktop version keeps its windows, menus, and keyboard.

It ships as one native program. A native desktop build is a single executable with no Java runtime to bundle, install, or update. It starts faster, holds less memory and downloads smaller than the same application with a trimmed Java runtime beside it. Size, memory and start-up measures all three for eight applications, built both ways.

It gets the APIs desktop Java never had. The desktop sources compile next to the Codename One API and can call it directly, as Calling Codename One from desktop code shows. That fixes several of the oldest pain points of Swing and JavaFX development:

Push notifications, biometrics, maps, in-app purchase and the rest of the guide are available in the same way.

The layer implements the parts of each toolkit applications use, and the build tells you, file by file and line by line, about anything an application uses that it doesn’t implement (Unsupported API is a build error). New code can use either API: the two live in one project.

Create a Codename One application project (for example from the initializr), then import the desktop project into it:

The goal accepts a Maven or a Gradle project. It copies the project’s src/main/java, src/main/kotlin and src/main/resources into common/src/main/desktop, generates the Codename One main class that starts the application (The entry point), and lists what becomes of each of the project’s dependencies.

Two more parameters settle the cases the goal can’t decide for itself:

cn1.desktop.module names the module to import when the project’s root has no sources and more than one of its modules does. cn1.desktop.mainClass names the class the application starts through when the project leaves more than one candidate. In both cases the goal stops before it copies anything and lists the choices.

After that, run and build as you would any Codename One application. The sources are the same for every target:

The simulator is the quickest place to see the application, and its skins show it at the size and density of a phone or a tablet. Every target and its options are in the Maven project workflow chapter.

A Codename One project built with Gradle (see Gradle project workflow) takes the same sources in the same place, src/main/desktop. When that directory exists the Codename One Gradle plugin adds the toolkit layers and runs the same build steps, with no configuration:

The directory mirrors a desktop project’s src/main:

The common module’s desktop-compat profile activates when src/main/desktop exists and adds the Swing and JavaFX layers. Only the layer the compiled classes use ships, so a Swing application doesn’t carry the JavaFX runtime. A project created before the profile existed gets it from the import goal.

A ported application is an ordinary Codename One application with an ordinary main class: a Lifecycle subclass in common/src/main/java. The import goal generates it, and its start-up calls the Swing application’s main, or launches the JavaFX Application, on the Codename One event dispatch thread (EDT). That thread is also the Swing event dispatch thread and the JavaFX application thread.

The class is yours. Edit it to pass arguments, to set display properties before the first window opens (Display properties), to show a Codename One screen first, or to start the desktop code only for some devices.

Three ideas explain everything the build does:

The JDK API that ordinary application code uses is available on every target: java.io.File and java.nio.file, regular expressions, the stream API, java.time, the executors and concurrent collections, Optional, Properties, ResourceBundle, logging and preferences.

The build checks every reference in the compiled application, so a class, method, constructor or field that a layer doesn’t have stops the build. It never becomes a failure on a user’s device. The message names the API the way the source spells it, with the source file and line:

A project with more than a handful of such references gets a summary that groups them by kind and by library, and points at the port report.

Every build of a project that uses a desktop layer writes target/codenameone/desktop-port-report.md, whether the check passes or fails. It says how many of the application’s calls into Swing, AWT and JavaFX are supported, lists what to change source file by source file with a Codename One alternative where one exists, and says what became of each dependency. Set cn1.desktop.report to write it elsewhere:

To find out how well an application fits before changing a line of it, import it, build it and read the summary at the top of that report.

A small application usually builds after the import. A large one usually needs some work, and widgets are seldom the reason: the user interface calls of a two-hundred-file Swing application, with FlatLaf for its look and a syntax-highlighting editor, built as written. The work is in the libraries and services around the user interface, and it goes in the order below.

The import keeps every dependency of the project. One that the layer implements itself — the JavaFX modules, SwingX, FlatLaf and RSyntaxTextArea — gets the provided scope: the sources compile against the real jar and the layer ships in its place.

Every other dependency is built with the application like any dependency of a Codename One application. Its classes aren’t relocated onto a layer, so a library written against Swing, AWT or JavaFX — a layout manager such as MigLayout, an icon library, a component set — fails the check for unsupported API. Replace it with its Codename One equivalent, or bring its source into src/main/desktop beside the application’s own, where it’s relinked and checked like the rest. A library that isn’t about user interfaces only has to use API a device has.

Where Codename One has an equivalent, the port report names it next to the finding. The common ones:

What remains is functionality a phone can’t provide in the same form. Put it behind an interface the application owns, keep the desktop implementation in the desktop project, and give the Codename One build an implementation that uses the Codename One API, a server, or nothing:

This is where most of a large port’s time goes. An application whose screens call straight into its services needs that seam before the seam can get a second implementation. An application that already separates its screens from its services has it, and its port is mostly the first two steps.

Codename One styles an application with CSS. A theme.css file in the project is compiled into a .res theme when the application is built, so the device reads a compact binary theme and never parses a style sheet. In the simulator the theme is rebuilt each time the file is saved, and the running application restyles at once. There is no look-and-feel class to write and no skin to subclass: every component has a UIID, and a CSS rule for that UIID styles it on every platform, with native themes for iOS, Android and the desktops underneath. The CSS chapter covers the syntax and Native modern themes the themes it builds on.

This differs from both desktop toolkits. A Swing look and feel is Java code, UI delegates that paint each widget, chosen at run time. JavaFX reads its CSS at run time and applies it to skins. In Codename One the styling is data, settled at build time, and the same for every platform.

A ported application uses this model in three ways.

The standard widgets are Codename One components: a JButton is a Codename One button, a JTextField is the platform’s text field with its own keyboard, selection and autocorrection, and the same holds for labels, check boxes, combo boxes, sliders, progress bars and tabs. They take the theme of the platform they run on.

UIManager.setLookAndFeel accepts any look and feel, so the usual call at the top of main runs unchanged and selects a light or a dark palette: FlatDarkLaf and other dark themes select the dark one, null or the system look and feel follows the platform’s own setting. Switching while windows are open restyles them at once. UIManager colors and fonts the application puts are kept and used, and the ones it reads answer from the palette.

FlatLaf’s entry points are part of the layer, so an application written against FlatLaf runs without the FlatLaf jar: setup(), the dark and light themes, the accent color, style classes and common client properties such as JTextField.placeholderText.

On a desktop, the desktop.themeMode build hint chooses the theme the packaged application uses, and native selects the theme of the machine it runs on:

The native macOS build reads macos.themeMode instead. Both are described under Desktop themes.

JavaFX style sheets under src/main/desktop/resources are compiled when the application is built, like the application’s own CSS, into a compact table that the runtime applies. Type, class, id and pseudo-class selectors, the descendant and child relations, the cascade, inline setStyle, looked-up colors and @font-face work as in JavaFX:

A property or selector the layer doesn’t style is a build warning with the file and line, and the rule is left out, which is what JavaFX itself does with a property it doesn’t know. Redefining a theme color such as -fx-base or -fx-accent recolors the controls the layer draws itself.

The application’s theme.css styles the Codename One components that the Swing and JavaFX widgets are, so one rule changes a button, a text field or a dialog across the whole application on every platform. Use it for anything that should look the same across screens; use the desktop styling for what’s particular to one screen.

A Swing component that overrides paintComponent paints as it does on the desktop, through a Graphics2D with shapes, strokes, paints, clipping and an affine transform:

In JavaFX, shapes, Text, paths, gradients, transforms and the shadow effects are drawn by the layer, and a Canvas replays its drawing calls when it paints, so it stays sharp at any display density.

Desktop code sizes things in pixels and assumes about 96 of them to the inch. The layers treat every Swing and JavaFX coordinate as a logical pixel of 1/96 inch and scale it to the display, so a 24 pixel row is the same physical height on a phone as on a desktop monitor. A phone is about 400 logical pixels across, so a layout designed for a 1024 pixel window is much wider than the screen. Layout managers and panes that adapt to the available width keep working; fixed sizes and null layouts need the attention they would need in a small desktop window.

A window whose content can’t shrink to the display keeps its minimum size and the user pans across it with a drag. A FlowLayout row and a horizontal JToolBar wrap instead of being cut off. A JavaFX scene whose root is a layout pane reflows to the screen as it does when its window is resized.

The first JFrame or Stage fills the screen. On the desktop ports each further frame or stage is a real window with the size, position and title the application gave it. On a phone or tablet a further frame is a form shown over the one before it, with a back command, and a dialog floats over the current form.

A modal dialog blocks its caller as it does on the desktop. JOptionPane.showMessageDialog, a modal JDialog, and showAndWait() on a JavaFX Alert all return after the user answers, while painting and input continue, so code written as a sequence of questions needs no restructuring:

On the desktop a JMenuBar is drawn in the window. On a phone its items become commands in the form’s overflow menu, and their accelerators become shortcuts.

The same listeners run on every device:

CN.isDesktop() answers which kind of device the application is on, so a feature that lives behind a hover or a key binding can offer a second way in on a phone.

Three display properties adjust how a desktop application maps onto a device. Set them with CN.setProperty before the first window opens, for example in the generated main class or at the top of main:

The Swing event dispatch thread, the JavaFX application thread and the Codename One EDT are one thread. SwingUtilities.invokeLater, Platform.runLater, javax.swing.Timer and the JavaFX animation classes run there. Long work belongs on another thread, as on the desktop: SwingWorker and a JavaFX Task or Service run their work in the background and deliver results on the EDT:

getClass().getResource(…​), getResourceAsStream(…​) and ResourceBundle.getBundle work: the build packages the files under src/main/desktop/resources and records where each one came from. ImageIcon, ImageIO.read and the JavaFX Image decode PNG and JPEG through the platform.

A library written against Swing or JavaFX, such as MigLayout or a component set, isn’t relinked onto the layer from its jar; see Porting a large application. The layer itself supplies FlatLaf and RSyntaxTextArea; keep those two dependencies as they are.

FXML documents are compiled when the application is built, into classes that build the same node tree with plain constructors and setters. The application loads a document the way it does on the desktop:

The controller’s @FXML fields and handlers can stay private, and initialize() runs after they’re set. The build writes direct code for the assignments, so no reflection is involved:

Imports, fx:include, fx:define, fx:root, %key strings from a resource bundle, @path locations and ${…​} bindings to a property all work, and so does an application’s own control used as an element. Because every class and property a document names is checked when it compiles, the build reports a typo with the file, line, and column, where the desktop would only find it when loading the document. A JavaFX application that builds its scene in code needs none of this:

The tables list the main classes of each area. The exact answer for an application is in its port report (The port report), which counts the calls that are supported.

The desktop sources compile in the common module, next to the Codename One API, so they can call it directly. That’s how a ported application adapts to the device it runs on, and how it reaches the camera, the database, push notifications and the rest of Motivation:

Code that uses Codename One classes no longer compiles in the original desktop project. Keep such calls behind a small class of your own if the application must go on building for a desktop JVM too.

A Codename One application can use Swing and JavaFX screens without handing them the whole application. Put the desktop sources in common/src/main/desktop as usual, and have the main class show Codename One forms instead of calling the desktop application’s main.

SwingInterop.asComponent wraps a Swing component in a Codename One component that you add to a form like any other:

FxInterop.asComponent does the same for the root of a JavaFX scene graph, or for a Scene when the screen needs style sheets:

Both take an Object and throw an IllegalArgumentException for anything other than a Swing component, a JavaFX parent or a scene. Call them on the EDT.

Frames, stages and modal dialogs work from Codename One code too. A frame or a stage opens as a form over the current one, and closing it returns there:

On the desktop ports these windows are real windows. SwingInterop.setNativeWindows(false) and FxInterop.setNativeWindows(false) keep them inside the application’s own window instead, as on a phone.

The application’s logic is tested as any Codename One application’s is, with mvn cn1:test or ./gradlew cn1Test. Test classes aren’t relinked, so a unit test exercises the classes that don’t touch the toolkit: models, parsers and the services behind the interfaces of Porting a large application. The tests that came with the desktop project stay there and keep running on the JVM.

Then run the application in the simulator with a phone, a tablet and the desktop skin. Most of what a port gets wrong is visible there in a minute: a window that pans because it can’t shrink, a table whose columns no longer fit, a feature reachable only from a hover or a key binding.

To prove that the screens respond to a real pointer, the Codename One source tree carries a harness in maven/integration-tests/desktop-compat-realport. It starts a built application on the JavaSE port and plays a script of clicks, drags and keys with the display server’s own input, and it fails when anything throws or when a step changes nothing on the screen. A script has one step on a line, and a position is a fraction of the application’s area:

Run it against the common module of a built application, under xvfb-run on a machine you’re working on:

swing-gallery.txt and javafx-gallery.txt beside the harness are complete scripts to start from.

The same project builds a native executable for Linux, macOS, and Windows. The application, the part of the layers it uses and the part of Codename One it uses are translated to C and compiled into one program with no Java runtime beside it:

Each port has a chapter with its toolchain, build hints, signing and packaging: Building a native Linux app, Native macOS Build (AppKit) and Building a native Windows app. A ported application needs nothing beyond what those chapters ask of any application. On these ports a JMenuBar is drawn in its frame, the mouse, wheel and keyboard modifiers are reported, and every further JFrame and Stage is a real window (see Desktop Windows).

This section measures what the user downloads, how soon the window appears and how much memory the application holds, for the same sources built two ways:

The JVM runs in two configurations. Default is the image as built, with its class data sharing archive. Tuned is what a developer who cared about start-up and footprint would ship: the serial collector, a smaller thread stack, the first compiler tier only, an application class data sharing archive and the smallest heap the application runs in.

Eight applications were measured: the swing-gallery and javafx-gallery samples in the Codename One source tree, the JDK’s SwingSet2 and Notepad demos, and four small open-source applications. Every comparison is like for like. Both builds of an application ran on the same machine, and each size compares one architecture with the same architecture: on macOS the native application is measured with the arm64 slice of its executable only, the architecture of the jlink runtime it’s compared with. In each ratio the JVM’s figure is divided by the native build’s, so a figure above 1 favors the native build.

Size is bytes on disk, and bytes as one zip at the highest deflate level, which is close to what a download costs. Start-up is the time from the start of the process to the first painted frame, the median of seven launches. Memory is summed over the process tree, ten seconds after the first frame and again after a short script of input. CPU while idle is the processor time of an application waiting for input.

The jlink image is the application with the smallest Java runtime that runs it: the application’s jars and the modules jlink found it to need. The native build is one executable file with nothing beside it. Both rely on the desktop libraries of the system, X11 and, for the native build and for JavaFX, GTK; neither column counts them.

Against the jlink image as installed the native build is smaller in 8 applications, of the 8 measured. Its best result is 3.5x for Mandelbrot explorer (17.7 MB against 61.3 MB).

Against the zipped jlink image the native build is smaller in 8 applications, of the 8 measured. Its best result is 6.0x for Mandelbrot explorer (6.5 MB against 38.9 MB).

Both sides are built for arm64: the jlink image holds the arm64 runtime, and the native .app is the bundle with the arm64 slice of its executable only. The builder’s default output is universal, with an x86_64 slice beside it; its size is in the last size column.

Against the jlink image as installed the native build is smaller in 8 applications, of the 8 measured. Its best result is 2.5x for Mandelbrot explorer (23.2 MB against 56.8 MB).

Against the zipped jlink image the native build is smaller in 8 applications, of the 8 measured. Its best result is 4.7x for Mandelbrot explorer (7.9 MB against 36.9 MB).

Against the default JVM the native build is quicker in 8 applications, of the 8 measured. Its best result is 6.0x for javafx-gallery sample (100 ms against 603 ms).

Against the tuned JVM the native build is quicker in 7 applications and slower in 1 application, of the 8 measured. Its best result is 4.1x for javafx-gallery sample (100 ms against 408 ms). Its worst is 0.9x for Falling-blocks game (74 ms against 70 ms).

Against the default JVM the native build is quicker in 8 applications, of the 8 measured. Its best result is 5.5x for javafx-gallery sample (116 ms against 637 ms).

Against the tuned JVM the native build is quicker in 8 applications, of the 8 measured. Its best result is 3.6x for javafx-gallery sample (116 ms against 422 ms).

Against the default JVM the native build is smaller in 8 applications, of the 8 measured. Its best result is 4.2x for Address book (55.6 MB against 233.6 MB).

Against the tuned JVM the native build is smaller in 6 applications and within 5% of it in 2 applications, of the 8 measured. Its best result is 3.1x for Address book (55.6 MB against 171.5 MB).

Against the default JVM the native build is smaller in 8 applications, of the 8 measured. Its best result is 4.3x for Address book (57.2 MB against 245.8 MB).

Against the tuned JVM the native build is smaller in 5 applications, larger in 2 applications and within 5% of it in 1 application, of the 8 measured. Its best result is 3.0x for Address book (57.2 MB against 172.6 MB). Its worst is 0.9x for SwingSet2, the JDK demo (92.8 MB against 87.0 MB).

Of the 8 native builds, 5 idle at or under 1% of a core. Above it: SwingSet2, the JDK demo (1.6%), javafx-gallery sample (4.7%), Open-source 2048 game (4.8%).

The Linux display is a software framebuffer for both builds, and start-up and memory were measured on Linux only. Figures move with what an application does at start-up, so measure your own.

The harness that produced the tables is in the Codename One source tree, under scripts/desktop-compat-benchmarks, and takes any Swing or JavaFX project. It builds the application both ways, measures both and writes one result.json, which report.py turns into tables:

The README.md in that directory lists what it needs. The phone sizes come from a second script, run against the project the first one imported:

Each entry is a symptom and what to do about it.