Dark Mode

VAqua supports the dark appearance introduced in macOS 10.14, also known as dark mode. Dark mode changes the rendering of all platform components; however, to effectively support dark mode in an application, additional changes to the application are likely to be required.

See screen shots.

Enabling Dark Mode

An application must opt-in to enable dark mode. An application that does not opt-in to dark mode will use the traditional macOS light appearance even when the system has been configured to use dark mode, thus preserving the appearance of existing applications.

When using JDK 14 or later, the following system property must be defined to enable dark mode: 

-Dapple.awt.application.appearance=system

In JDK 13 and earlier, enabling dark mode in a bundled application is easy. All that is needed is to add an entry to the application’s Info.plist: 

NSRequiresAquaSystemAppearance = NO

In JDK 13 and earlier, running an application from the command line in dark mode unfortunately requires more work. (You may think you will never need to run a desktop application from the command line, but be aware that IDEs such as IntelliJ IDEA routinely run applications from the command line under the covers.) The required change is to create a version of the Java launcher that itself opts into dark mode; see the instructions here.

Customizing your application

Once dark mode is enabled for an application, VAqua will automatically display in dark mode when dark mode is selected as the system appearance. In addition, VAqua will automatically update the display when the system appearance is changed, the accent color is changed, or the high contrast accessibility option is changed. (On older versions of macOS, similar changes are also obeyed immediately.)

For many apps, additional customization will be needed. Apple has a document that illustrates the kinds of changes that might be needed, such as selecting colors and creating icons to use in dark mode, but the technology it describes is not available to Java applications.

VAqua provides the basic information that an application needs using the Aqua.appearance client property. The value of this property is an object that provides information about the current appearance, as it applies to the component, such as whether the appearance is a dark appearance or a high contrast appearance. In addition, the current set of platform colors is available. A property change listener can be used to detect changes in the appearance.

See the sample code for accessing appearance data.

Specifying an appearance

Normally, each window inherits an appearance from its parent window or the application, and each component inherits its appearance from its parent component or its window. In certain cases, you may wish to force a given window or component to use a specific appearance. For example, when displaying user editable text content, you may prefer to use the light appearance (black text on a white background) even in dark mode. To specify an appearance, set the client property Aqua.appearanceName on the component or the root pane of the window.

The available appearance names are defined by macOS:

For best results, the component with the specified appearance may need to be contained in an opaque container that paints an appropriate background color. The reason this container may be needed is that the appearance based colors used by macOS are often translucent and assume a specific ancestor-supplied background, typically, the window background.