Properties Files

This page is work in progress.

File Format

A .properties file is a text file where each line stores a single property in the format key = value. Leading and trailing white space characters are ignored.

Comment lines start with a # character.

# button colors
Button.background = #ffffff
Button.focusedBackground = #e3f1fa

Keys

A key has the format component.property, where

  • component is the type of the component (usually without leading J)
  • property is the property name

Values

Following value types are supported:

Primitive Types

Formats of supported primitive types:

  • Boolean - either false and true
  • Integer - one or more decimal digits 0-9; first character may be minus sign '-' or a plus sign '+'
  • Float - zero or more decimal digits 0-9 followed by a dot character '.' followed by one or more decimal digits; first character may be minus sign '-' or a plus sign '+'
  • String - start with a '"' character followed by any character and end with a '"' character
  • null - must be null
# boolean
Menu.opaque = false
MenuItem.borderPainted = true

# integer
Button.borderWidth = 1

# float
Popup.dropShadowOpacity = 0.15

# null
Menu.checkIcon = null

Color

Colors (java.awt.Color) are specified in hexadecimal formats #RRGGBB, #RRGGBBAA, #RGB or #RGBA. R (red), G (green), B (blue) and A (alpha) are hexadecimal characters (0-9, a-f, A-F). The characters of the two short formats are doubled. E.g. #f26 is the same as #ff2266. Likewise #0f38 is the same as #00ff3388.

Button.background = #fff
Button.focusedBackground = #e3f1fa
PasswordField.capsLockIconColor = #00000064

Use color functions to derive colors from already defined colors to reduce the number of individual colors. E.g.:

TableHeader.separatorColor = darken($TableHeader.background,10%)

Insets

Insets (java.awt.Insets) are in format top,left,bottom,right, where each of the four parameters must be of type integer.

Button.margin = 2,14,2,14
TabbedPane.tabInsets = 0,12,0,12

Dimension

Dimensions (java.awt.Dimension) are in format width,height, where each of the two parameters must be of type integer.

DesktopIcon.iconSize = 64,64
ProgressBar.horizontalSize = 146,4

Border

Borders (javax.swing.border.Border) are either in format top,left,bottom,right[,lineColor[,lineThickness]] or fullQualifiedClassName.

The first format creates a border with the given insets top,left,bottom,right. An empty border is created if no lineColor is specified. A line border is created if (optional) lineColor is specified. Line thickness is either (optional) lineThickness or 1.

OptionPane.border = 12,12,12,12
ToolTip.border = 4,6,4,6,#000

The second format creates a border with the given full qualified class name fullQualifiedClassName. The class must be public and must have a zero-argument public constructor. A single instance of the border is created lazy (when first used) and its constructor can query values from the UI defaults with UIManager.get(String key).

Button.border = com.formdev.flatlaf.ui.FlatButtonBorder

Icon

Icons (javax.swing.Icon) are in format fullQualifiedClassName. The class must be public and must have a zero-argument public constructor. A single instance of the icon is created lazy (when first used) and its constructor can query values from the UI defaults with UIManager.get(String key).

CheckBox.icon = com.formdev.flatlaf.icons.FlatCheckBoxIcon

Gray Filter

Gray filter (com.formdev.flatlaf.util.GrayFilter) is in format brightness,contrast,alpha.

Parameters:

  • brightness - an integer in range -100 - 100 where 0 has no effect
  • contrast - an integer in range -100 - 100 where 0 has no effect
  • alpha - an integer in range 0-100 where 0 is transparent, 100 has no effect
Component.grayFilter = 25,-25,100

Variables

Variables are defined in properties files and can only be used within other values in properties files. They are not added to the UI defaults and therefore you can not query them with UIManager.get(String key).

Variables are defined in the same way as properties, but the key starts with a '@' character:

@background = #f2f2f2
@foreground = #000
@menuHoverBackground = darken(@menuBackground,10%,derived)

Usage of variables:

Table.background = @background
Table.foreground = @foreground
MenuBar.hoverBackground = @menuHoverBackground
MenuItem.acceleratorForeground = lighten(@foreground,30%)

Color Functions

Color functions create new colors either by modifying existing colors or by defining new colors in RGB or HSL color space.

Using color modification functions makes it easy to define colors that are e.g. lighter or darker than already used colors. This reduces the number of individual colors and makes it easy to change themes by modifying base colors.

Available color functions:

  • lighten() - Increase the lightness of a color in HSL color space.
  • darken() - Decrease the lightness of a color in HSL color space.
  • saturate() - Increase the saturation of a color in HSL color space.
  • desaturate() - Decrease the saturation of a color in HSL color space.
  • fadein() - Increase the opacity (alpha) of a color.
  • fadeout() - Decrease the opacity (alpha) of a color.
  • fade() - Set the opacity (alpha) of a color.
  • rgb() - Creates an opaque color from red, green and blue (RGB) values.
  • rgba() - Creates transparent a color from red, green, blue (RGB) and alpha values.
  • hsl() - Creates an opaque color from hue, saturation and lightness (HSL) values.
  • hsla() - Creates transparent a color from hue, saturation, lightness (HSL) and alpha values.

lighten / darken

Increase or decrease the lightness of a color in HSL color space.

Syntax: lighten(color,amount[,options]) or darken(color,amount[,options])

Parameters:

  • color - base color (e.g. #f00), a color function or a reference to another color value
  • amount - percentage 0-100% that is added to (lighten) or removed from (darken) the lightness (absolute)
  • options - optional options (separate multiple options with space characters):
    • relative - specifies that the amount is relative to the lightness of the base color, so adding 10% to a 20% lightness results in 22%
    • autoInverse - specifies that the amount should be inverted if the lightness of the base color is greater than 65% (lighten) or less than 35% (darken); this option is automatically enabled if option derived is enabled, except if option noAutoInverse is enabled
    • lazy- specifies that the color is computed lazy (when first used); in this case, the color parameter must be a UI key that is used to get the base color
    • derived - specifies that the real color is computed at runtime based on a variable base color (usually the current background color of a component); this works only for a limited set of UI keys
Button.background = darken(#ffffe1,80%)
Button.foreground = lighten(#ff0,50%,relative)
Button.hoverBackground = lighten($Button.background,3%,derived)
InternalFrame.closePressedBackground = darken(Actions.Red,10%,lazy)
Component.warning.borderColor = lighten(saturate($Component.warning.focusedBorderColor,25%),20%)

saturate / desaturate

Increase or decrease the saturation of a color in HSL color space.

Syntax: saturate(color,amount[,options]) or desaturate(color,amount[,options])

The parameters are the same as in lighten / darken functions.

Component.error.borderColor = desaturate($Component.error.focusedBorderColor,25%)
Component.custom.borderColor = desaturate(#f00,50%,relative derived noAutoInverse)

fadein / fadeout

Increase or decrease the opacity (alpha) of a color.

Syntax: fadein(color,amount[,options]) or fadeout(color,amount[,options])

The parameters are the same as in lighten / darken functions.

fade

Set the opacity (alpha) of a color.

Syntax: fade(color,amount[,options])

Parameters:

  • color - base color (e.g. #f00), a color function or a reference to another color value
  • amount - percentage 0-100%
  • options - optional options:
    • derived - specifies that the real color is computed at runtime based on a variable base color (usually the current background color of a component); this works only for a limited set of UI keys
Slider.focusedColor = fade($Component.focusColor,50%,derived)

rgb / rgba

Creates a color from red, green, blue (RGB) and alpha (optional) values.

Syntax: rgb(red,green,blue) or rgba(red,green,blue,alpha)

Parameters:

  • red - an integer 0-255 or a percentage 0-100%
  • green - an integer 0-255 or a percentage 0-100%
  • blue - an integer 0-255 or a percentage 0-100%
  • alpha - an integer 0-255 or a percentage 0-100%
Button.focusedBackground = rgb(227,241,250)
PasswordField.capsLockIconColor = rgba(0,0,0,120)

hsl / hsla

Creates a color from hue, saturation, lightness (HSL) and alpha (optional) values.

Syntax: hsl(hue,saturation,lightness) or hsla(hue,saturation,lightness,alpha)

Parameters:

  • hue - an integer 0-360 representing degrees
  • saturation - a percentage 0-100%
  • lightness - a percentage 0-100%
  • alpha - a percentage 0-100%
List.selectionBackground = hsl(209,66%,44%)
List.selectionForeground = hsla(0,0%,100%,50%)

Wildcard replacements

Keys starting with *. are wildcard replacements. They replace all matching keys defined in javax.swing.plaf.basic.BasicLookAndFeel.getDefaults() and FlatLaf.getDefaults(). This is used to initialize basic component colors.

*.background = #f2f2f2
*.foreground = #000

Platform specific values

If a key is preceded by [win], [mac] or [linux], then its value is only used on the given platform.

[win]Button.defaultButtonFollowsFocus = true
[mac]OptionPane.isYesLast = true
[linux]ScrollBar.minimumThumbSize = 18,18

Light/dark theme specific values

If a key is preceded by [light] or [dark], then its value is only used if the current FlatLaf theme is light or dark. Method com.formdev.flatlaf.FlatLaf.isDark() is used to detect whether a theme is light or dark.

[light]Button.background = #fff
[dark]Button.background = #000

Scaled values

FlatLaf has built-in scaling for HiDPI screens. This is disabled if Java does the scaling itself (Java 9 and later). On Java 8 (and Linux), FlatLaf scales in Java code where necessary by invoking method UIScale.scale(). Sometimes this is not possible because a UI value is used in Java core classes. In this case it is necessary to specify in the properties file that a value should be scaled when used.

Following value types can be scaled in properties files:

  • integer - prefix value with {scaledInteger}
  • float - prefix value with {scaledFloat}
  • Insets - prefix value with {scaledInsets}
  • Dimension - prefix value with {scaledDimension}
Caret.width = {scaledInteger}1
Component.innerFocusWidth = {scaledFloat}0.5
TabbedPane.tabInsets = {scaledInsets}0,12,0,12
ColorChooser.swatchesSwatchSize = {scaledDimension}16,16

Type prefix

In case that the value type can not be detected correctly, it is necessary to explicitly specify it by prefixing the value with one of the following strings:

{integer}, {float}, {string}, {character}, {color}, {insets}, {dimension}, {border}, {icon} or {grayFilter}

Component.innerOutlineWidth = {float}1
Table.intercellSpacing = {dimension}0,0

Value type detection

Because properties files are text files, but UI default values must be binary, it is necessary to convert them. Following strategy is used to convert value strings:

  1. strings false and true are converted to Boolean
  2. string null becomes Java null
  3. strings starting with '#' become Colors
  4. strings starting and ending with '"' character become Java Strings
  5. strings starting with a type prefix use the specified type
  6. if key ends with
  7. if string is parsable as Color, Integer or Float, use it
  8. use string as Java String