Supporting decoration areas and per-window skins in the next release of Substance look-and-feel required rewriting the skinning layer from the scratch. The current APIs represent my best understanding of skinning functionality at the present moment, and the internal implementation was heavily influenced by performance considerations. Applications that just used the bundled core Substance skins will not have to change their code. However, those applications that created custom Substance themes and skins will have to adjust the code to the new APIs.

As the old theming implementation continued evolving and getting new features, it quickly outgrew the original design and made adding new features progressively more difficult. Those of you who either looked at the code or used the old SubstanceTheme and SubstanceComplexTheme know what i’m talking about. I know that every time i had to add a new feature to an existing skin or create a new skin, i witnessed the “ugliness” of the theming API. As already mentioned, this has been completely rewritten in version 5 to address the following:

• Better modeling of logical structure of a UI skin
• Cleaner, more generic and more extensible implementation
• Performance, performance, performance

The main concepts in the new skinning layer of Substance 5 are:

• Color scheme – information to paint a single control in a specific visual state. For example, you can have one color scheme for rollover button, and another color scheme for pressed button.
• Color scheme bundle – information to paint all controls in a specific decoration area. Allows registering color schemes and alpha values for different component states, as well as registering highlight and border color schemes for different component states.
• Skin – information to paint a top-level window (with all its decoration areas). Allows specifying supported decoration areas, registering color scheme bundles for different decoration areas, registering a watermark and watermark color scheme, setting painters (border, gradient, decoration and highlight) and a few miscellaneous settings.

The following documentation has been updated to reflect the latest stable drop of 5.0dev:

• Skin overview document, along with sample screenshots and code snippets from existing core Substance skins.
• Skinner primer that describes how applications can use Substance skin APIs and painters to provide custom application painting that is consistent with core Substance visuals.
• Documentation of gradient painters, decoration painters, highlight painters and border painters.
• Documentation of watermarks.
• API of the main SubstanceLookAndFeel class, including the new getCurrentSkin(Component) method.
• Client properties from the main SubstanceLookAndFeel class, including the new SKIN_PROPERTY.
• Supported VM flags.

Here are some sample screenshots from the documentation of 5.0dev:

If you have been waiting to try the 5.0dev branch, now is the time. The main functionality that i wanted to see is in, and the APIs should be stable enough with only minor changes projected based on user feedback. If you wrote a custom pre-5.0 skin, i will gladly assist in porting it to the new API. If you have any questions on the new APIs, or have any suggestions on the existing documentation, let me know. The official release is planned for early September. The earlier you try, the more chances i will have to address your feedback.

Note that documentation for the latest stable release 4.3 is available with the full distribution archive (and in CVS tagged with release_4_3_06_nairobi). Version 4.3 is in long term support stage. Please consult the updated release info notes to see the list of backported bug fixes.