How to Customize

This page is work in progress.

UIManager

This is the simplest way to customize FlatLaf and is suitable for small modifications.

UIManager.put( "someKey", someValue );

Invoke Java method UIManager.put() to change FlatLaf UI defaults. Note that this method adds the values into a "global" UI defaults table, which is used for all themes (and also for other look and feels). If your application supports multiple themes or other look and feels, it is better to use application properties files.

Note: Invoke UIManager.put() always after setting the look and feel with e.g. FlatLightLaf.setup() or UIManager.setLookAndFeel() (but before creating the components). Otherwise, the system look and feel is temporary installed before FlatLaf is installed, which may make application startup slower.

Here is an example for doing basic FlatLaf customizing using UIManager:

FlatLightLaf.setup();

UIManager.put( "Component.arc", 0 );
UIManager.put( "ProgressBar.arc", 0 );
UIManager.put( "TabbedPane.selectedBackground", Color.white );

Application properties files

This is the recommended way for applications that use multiple themes or like to do more customization or define own UI defaults (e.g. colors) for own components.

FlatLaf.registerCustomDefaultsSource( "com.myapp.themes" );

Note: Invoke this method before setting the look and feel.

This method registers a package where FlatLaf searches for properties files with custom UI defaults.

This can be used to specify application specific UI defaults that override UI values of existing themes or to define own UI values used in custom components.

There may be multiple properties files in that package for multiple themes. The properties file name must match the used theme class name. E.g. FlatLightLaf.properties for class FlatLightLaf or FlatDarkLaf.properties for class FlatDarkLaf. FlatLaf.properties is loaded first for all themes.

These properties files are loaded after theme (and addon properties) files and therefore can override all UI defaults.

Example

Here is an example for an application that uses light and dark themes, the appearance of some components is changed and application specific colors for light and dark themes are defined.

Create a file com/myapp/themes/FlatLaf.properties used for all themes:

Component.arc = 0
ProgressBar.arc = 0

Create a file com/myapp/themes/FlatLightLaf.properties used for light themes:

TabbedPane.selectedBackground = #fff

# define application specific UI values
MyApp.SideBar.background = darken(@background,10%)
MyApp.someColor = #f00
MyApp.anotherColor = #645554

Create a file com/myapp/themes/FlatDarkLaf.properties used for dark themes:

TabbedPane.selectedBackground = darken($TabbedPane.background,5%)

# define application specific UI values
MyApp.SideBar.background = lighten(@background,10%)
MyApp.someColor = #00f
MyApp.anotherColor = #278354

In your main() method use:

FlatLaf.registerCustomDefaultsSource( "com.myapp.themes" );
FlatLightLaf.setup();

To get application specific UI values in your components use:

Color sideBarBackground = UIManager.getColor( "MyApp.SideBar.background" );

Properties files load order

Properties files are loaded in a well-defined order into a single hash table. Keys defined in later loaded files can therefore override keys defined in earlier loaded files.

The class name of the used look and feel class and its superclasses define the used basenames of the properties files. E.g if you use class FlatDarculaLaf, which extends class FlatDarkLaf that in turn extends class FlatLaf, then FlatDarculaLaf.properties, FlatDarkLaf.properties and FlatLaf.properties are loaded in reverse order. All files are optional.

The properties files are loaded from several places (in this order):

  1. from flatlaf.jar
  2. from JARs that provide the service com.formdev.flatlaf.swingx.FlatSwingXDefaultsAddon
    (e.g. SwingX and JIDE addons).
  3. from packages or folders registered with FlatLaf.registerCustomDefaultsSource()
    (see Application Properties)

For example if you use FlatDarculaLaf, the SwingX addon and also have own properties files in package com.myapp.themes registered with FlatLaf.registerCustomDefaultsSource(), then following properties files are loaded (in this order; all files are optional):

From flatlaf.jar:

  1. com/formdev/flatlaf/FlatLaf.properties
  2. com/formdev/flatlaf/FlatDarkLaf.properties
  3. com/formdev/flatlaf/FlatDarculaLaf.properties

From flatlaf-swingx.jar:

  1. com/formdev/flatlaf/swingx/FlatLaf.properties
  2. com/formdev/flatlaf/swingx/FlatDarkLaf.properties
  3. com/formdev/flatlaf/swingx/FlatDarculaLaf.properties

From myapp.jar:

  1. com/myapp/themes/FlatLaf.properties
  2. com/myapp/themes/FlatDarkLaf.properties
  3. com/myapp/themes/FlatDarculaLaf.properties