Substance look and feel

Getting started

If you are new to Swing, start with the general Swing tutorial. If you are new to look-and-feels, read the getting started first.

To use Substance in your applications, use one of the following options:

• Call UIManager.setLookAndFeel() with one of the skin-based look-and-feel classes (light or dark).
• Extend the SubstanceLookAndFeel class and pass a SubstanceSkin instance to the super constructor.
• Use the static setSkin(SubstanceSkin) or setSkin(String) APIs in SubstanceCortex.GlobalScope to set the specific skin.

In any case, add the latest substance-X.Y.ZZ.jar and the matching trident-L.M.NN.jar to your classpath.

The main demo application is in the substance-demo uses the FormLayout and components from SwingLabs. In addition, substance-samples has a collection of self-contained samples that show more advanced usage of Substance APIs for custom application skinning.

Have a question? See the FAQ and the list of known issues, and if you don't see an answer there, file a bug or get in touch.

Adding Substance to your application

If you've skipped getting started page, to add Substance to your app follow these steps:

• Go to the main project page.
• Navigate to the drop folder. This should take you to the sub-folder that contains the downloads for the latest / earlier releases.
• Click on the specific X.Y.ZZ row. It's highly recommended to always use the latest stable release which is 8.0.0 at the present.
• Download substance-X.Y.ZZ.jar file from there.
• Also download trident-L.M.NN.jar file from the same folder - this is the Trident animation library that is a required runtime dependency.

Configure and customize

It is easy to customize and extend Substance to fit your visual needs.

Substance comes with an extensive set of APIs to add custom functionality to your components. The overall visuals are controlled by skins, with each skin defined by color scheme bundles and painters.

The skinning primer has a few tips on how to use the different Substance painters in applications that wish to paint custom components in a way that is consistent with other Substance visuals. The substance-samples project provides additional self-contained mini-applications that show more advanced usage of Substance APIs for pixel-perfect skinning.

Plugins

While the core Swing components cover the base UI functionality that most applications require, modern UIs need modern UI components. To address this need, Substance comes with a built-in support to define and load plugins that provide consistent appearance and interaction patterns for third-party components.

During the initialization of your application in the main() method - before creating your first window - use these SubstanceCortex.GlobalScope APIs to register plugins:

• registerComponentPlugin() for registering component plugins
• registerSkinPlugin() for registering skin plugins

Substance plugin for Flamingo components is the only actively developed and fully supported first-party component plugin.

Substance plugin for SwingX components is being kept in sync with the latest core Substance library. However, since the core SwingX project is effectively dead (last official 1.6.4 release is from July 2013), there is no more active new development in that plugin.

Substance Extras pack provides additional watermarks, color schemes and skins and is another example of a Substance plugin.