As Substance look-and-feel nears the official release 4.1 (scheduled for November 12th), i’m working on the missing documentation. This entry talks about the using the painter layer to skin custom components.
As mentioned in the painter overview, most of the Substance painting logic is abstracted into a set of painters. This not only allows preventing duplicate painting sequence in the Substance UI delegates. This also provides a painting layer for the applications that wish to paint custom components in a way that is consistent with other Substance visuals.
This applies in two major cases:
- Providing consistent painting for a standalone component suite, such as SwingX.
- Providing consistent painting for custom components and visual areas of a specific application.
Instead of trying to match the colors, gradients and animation sequences from the current Substance skin (which might change between various releases), applications can use the Substance painting APIs. This will result in code which is shorter, more maintainable and also produces consistent results.
Skinning primer
The following Substance APIs are most suited for painting custom components:
Most of the Substance UI delegates use a combination of the above APIs. While the exact combination in the existing UI delegates is subject to change in between releases, you can study the core Substance code to see the main combination patterns.
The first pattern is watermark overlaying. The watermarks are painted on most Swing containers, and on some components as well. In simpler cases (such as <font color="darkblue">JPanel</font>), the watermark is painted on top of the gradient fill. In more complex scenarios, after the watermark has been painted, the fill sequence is repeated with lower alpha value. Here is an example of such a scenario:
In this scenario, while the regular controls and containers on the content pane are painted with the regular watermark, the frame header (title pane and tool bar) has less “intrusive” watermark painting. This is achieved by the following sequence:
- Using the header painter to paint the background gradient.
- Using the watermark to paint the current watermark.
- Using the header painter once again, this time with the
<font color="darkblue">AlphaComposite.SRC_OVER</font> with alpha value of 0.5.
The second pattern is decorating. The header painters can be used to provide distinct painting to some containers, this setting them “apart” from the rest of the application. As the pattern name implies, this works best on specialized containers and visual areas that are situated along the window edges. Here is an example of SwingX <font color="darkblue">JXLoginDialog</font> component painted by the Substance SwingX plugin:
In this scenario, the
<font color="darkblue">JXLoginDialog</font> has a “decoration” strip located along the top side of the window. To paint the background of this component, the custom UI delegate is using the current
header painter, which results in a consistent appearance of the top portion of this dialog.Here is another example of this pattern, this time on the
<font color="darkblue">JXStatusBar</font> component from
SwingX component suite. Assuming that this component will be placed along the bottom side of the frame, the matching UI delegate in the
Substance SwingX plugin uses the current
header painter to provide a distinct appearance of status bar which is consistent with the title pane and menu bar:
The third pattern is
border tracing. Those components that require consistent painting of borders or contours can use the
border painter with the matching contour. Here is an example of border tracing in the
<font color="darkblue">JRibbon</font> component from
Flamingo component suite under the
Substance Flamingo plugin:
This UI delegate uses the
border painter extensively to create the required visuals. Note the outer contour of the ribbon that also includes the selected tab button, and the inner contours of the ribbon tasks.Here is another example of this pattern, this time on the
<font color="darkblue">JCommandButton</font> component from
Flamingo component suite. The custom UI delegate uses the border painter to paint the button border (a simpler contour in this case):
The last pattern is
gradient filling. It is used to paint the inner fill of custom components (along with the border tracing pattern to paint the component contour). This pattern uses the
gradient painter with the matching contour. Here is an example of the
<font color="darkblue">JRibbon</font> component from
Flamingo component suite:
In this example, the first toggle tab button (Write) is filled by the current
gradient painter, providing a consistent appearance with the rest of the application controls. Another example is the previous screenshot (of the
<font color="darkblue">JCommandButton</font>), where the button fill is painted by the current gradient painter as well.
Here are some Swing links that you might have missed during this week:
- Jan Erik Paulsen is working on a new RIA tool named Amanda. Some nice screenshots that use the Titanium look-and-feel that is based on Substance.
- The release notes for Java 5 on Leopard include a few new client properties that can be used to provide functionality missing from the core Swing components. Examples include indeterminate progress circular indicator, smaller controls and search text fields.
- Jan Haderka writes about detecting Caps Lock state on the JXLoginPanel SwingX component. This thread on java.net forums has additional comments. The current solution does not sound too robust, and since the correct approach requires using native code (which is currently missing from the JDK), use with care.
- Eclipse 3.4M3 release notes mention the new API on the Shell component. It allows setting an alpha channel value on supported platforms (see screenshot). While the matching functionality is available in the JNA project for Swing, it’s really time for the core Swing team to provide it in JDK. It’s missing in Tiger, it’s missing in Mustang, and it most probably won’t be in Dolphin (due to major work by the client team on the “Update N” which leaves them with only a few months for Dolphin).
- Hrish writes about problems with file access in signed applets under IE 7 on Windows Vista. There are some links to MSDN articles, but i think that a more important link would be to Chet’s blog on this subject where he says that “There is an issue worth noting here than cannot be fixed: IE7 on Vista will not let us access the file system outside the IE7 sandbox for applets. This means that even “signed” applets have no permission to write to arbitrary locations on disk. This behavior differs from the old behavior of applets on Windows, but given the restrictions of IE7, there is really no way around the problem.” I’m not sure how this sits along with the user comments on bug 6504236 that say that “there is a well documented design to allow IE add-ins access the file system from the user’s normal (Medium) Integrity level, rather the IE’s Low Integrity level: implement an Internet Explorer Broker Process“.
This week has also seen a few announcements:
- Mikael Grev has announced release 3.0 of MigLayout project. The main emphasis of this release is on automatic support for resolution independence, which is a very important topic that doesn’t get the attention it deserves (neither in Java world nor elsewhere).
- David Qiao has announced release 2.2.1 of JIDE component suite. The new components are group list, dual list and aggregate table – all of these are not available in the open-source common layer.
- Instantiations has announced release 6.5.0 of the WindowBuilder family of products with a few enhancements to the Swing designer.
- Hans Muller has announced release 1.03 of Swing Application Framework, the reference implementation of JSR 296, while Shannon Hickey has announced release 1.2 and release 1.2.1 of Beans Binding, the reference implementation of JSR 295. There are some breaking changes in the Beans Binding 1.2 (see release notes). While on one hand it is expected from an evolving project which has not been finalized, it brings some interesting questions nonetheless. The first one (this is also relevant for Swing Application Framework) – what exactly do the version numbers signify? Was the release 1.0 just something to “tag” and release so that people will consider it as a production-ready implementation? Or perhaps these are the versions used in NetBeans 6.0 betas – which makes it even worse considering that NetBeans is an IDE and these two projects are JSR reference implementations. And what happens when NetBeans 6.0 is frozen (somewhere this week) and there are still breaking API changes in these two projects?
The release candidate for version 4.1 of Substance look-and-feel (code-named Lima) is available. The list of new features includes:
Some applications may need to follow the instructions in the migration guide. Target date for release is November 12. Only defects will be fixed until this date.
In addition to the core release candidate, the following Substance plugins and modules have been updated as well:
Special thanks for bug reporting and testing go to Mikael Grev, Vincent Trussart, Kamil Paral, Klaus Rheinwald and Jean-Francois Poilpret.
Here are some Swing links that you might have missed during this week:
- Geoffrey Wiseman shares an interesting tip on hiding a UI during the test running. In order to get the UI tests running on the continuous integration server, they needed to find a way to run in headless environment. While it appears that the solution works only on X server, it opens an intriguing array of possibilities which hopefully can be implemented in a cross-platform way in a general purpose UI test library such as Fest (by Alex Ruiz and Yvonne Wang Price). This would be useful in areas beyond testing. For example, most of the documentation screenshots for Substance (that show various themes, watermarks and skins applied to the same UI) are taken by a Robot-controled process. During this process (which takes a few minutes) i have to make sure that i don’t accidentally interact with the frames and dialogs that get captured so as not to interfere with the correct visuals. Can this process can be done in a headless mode with an approach similar to what Geoffrey is describing?
- Davide Raccagni announced release 2.0 of his A03 look-and-feel (link a little slow to open because of embedded videos). A major change is that A03 now can run under JDK 5.0 (unlike the previous releases). In addition, it features a theming layer and has a few interesting visuals (such as decorated title pane gradients, progress bar fill pattern, rotated tabs on left and right placement and some others). Personally, i’m very happy to see that some code in A03 is based on the code from Substance (which is, in turn, based on some code from Looks, Quaqua and Xoetrope).
- Elliott Hughes shares his frustration with the JTextPane implementation when it shows an HTML document. Starting from trying to prevent beeps on setText() API, he quickly gets into one of the biggest gaps in Swing as a modern UI toolkit (not mentioned in my previous rant) – support for HTML 4.0. Hasn’t it been eight years since it was finalized?
