This entry is going to summarize the process of taking the UI definitions from your designer and converting them to a live implementation. Illustrated by taking design of Cookbook UI (from the My Dream App contest) and turning it into a Swing application using Substance look-and-feel, the main five phases of this process are:

• Analysing the original design
• Mapping design to UI toolkit
• Implementing the decoration painting
• Implementing the skin
• Polishing the visuals

The customization layer of Substance (especially the painters) aims to create a customizable and powerful separation between painting layer and the rest of the application code (business logic such as persistence, authentication, communication and more). In this separation, Substance allows working on the application visuals as a separate work flow (although the process of mapping the application areas to Swing and Substance may require closer cooperation with implementing the actual UI container structure).

The ideal end result of this process is a self-contained implementation of the application skin that can be:

• tweaked as the design changes
• reused in other applications under the same portfolio
• even swapped out for a completely different appearance (such as using a native look-and-feel)

It took me about 20 hours to create the final visuals as shown below (click to see the full-sized version):

As the developer of Substance i have an advantage of knowing how the library is built and what APIs are available. My hope is that this series will make it easier for Swing developers to understand the customization layer of Substance and use it to its fullest potential.

An important question that needs to be addressed is: why do you need to do it with Substance? Why would you want to tie yourself to a third-party library when you can override paintComponent and use Java2D to create all the visuals? While you can most certainly do so (and in fact, the light bar holder is implemented this way), Substance gives you quite a few advantages:

• Cleaner separation of the painting logic from your main application. A close cooperation with your design team that is made aware of the current Substance limitations may result in zero custom painting code in your components even for such a complicated design as Cookbook UI.
• Performance improvements in version 5.0 (available tomorrow) bring Substance on par with the core look-and-feels. If your painting code is making heavy use of Java2D and images, you will need to provide a sophisticated caching layer to make sure that the UI remains responsive.
• Substance skin can be reused across multiple portfolio applications. Embedding custom painting code in your UI components may result in a code that is harder to refactor into reusable building blocks.
• Substance provides animation effects (rollover, selection, others) on the core and supported third-party components out of the box. These effects add a modern touch expected from visually rich applications.
• Substance supports third-party component suites, such as SwingX, Flamingo and (partially) JIDE. In addition, it provides a well-defined plugin mechanism to support additional third-party components.
• Substance makes your applications safer by checking EDT violations during the UI construction.

The code behind the process is available in the Substance Samples project that aims to provide a collection of blueprints for creating visually rich UIs in Swing.

In this entry i’m going to talk about the fifth step in the process of taking the UI definitions from your designer and converting them to a live implementation. This process is illustrated by taking design of Cookbook UI (from the My Dream App contest) and turning it into a Swing application using Substance look-and-feel. The code behind the process is available in the Substance Samples project that aims to provide a collection of blueprints for creating visually rich UIs in Swing.

Lather, rinse, repeat

Unless you are using the exact same images that the designer was using for creating the screen mockups, the process of implementing the required visuals is hardly ever done. The slightest variations in color saturation, hues and brightness can result in a drab appearance. Not paying attention to artfully placed visual separators (gaps, margins, borders) can result in a cluttered appearance. Failing to remove visual noise that does not bother you as a programmer can result in visual distractions for the users, even at the unconscious level.

Here is a screenshot of the very first implementation of Cookbook UI header before all the visual tweaks introduced in the previous phases:

and here is the current implementation:

Here is a screenshot of the first implementation of Cookbook UI footer:

and here is the current implementation:

The devil is in the details

While the first two phases (analysis and mapping) operated on more abstract layers (decoration areas, functional areas, container hierarchy), the implementation phases (decoration and skin creation) must pay painstaking attention to all the minute details of the target design. Not closely following the design may seem insignificant to the developer, but it will in most cases result in deteriorated user experience.

The following is an incomplete list of Cookbook UI minute visuals that have been pointed out before. Most of these can be easily addressed with Substance painters and skins.

• Seamless and continuous texturing of header, footer and sidebar areas.
• Light-dark fill gradients for the buttons.
• Darker gradients for the button borders with translucent fading inner borders.
• Color schemes used for the selected buttons in the header and scroll bar in the sidebar.

Here are two more examples of fine details that are easily missed at a cursory glance. The following is a zoomed screenshot of the seam between the sidebar and the footer area. The vertical separator has two lines, darker on the left and lighter on the right. The same appies to the horizontal separator. In addition, the horizontal separator is painted on top of the vertical one to further enforce the boundary between the application functional areas:

In the implementation, the vertical separators are painted as a custom border installed on the relevant panels. While this can be achieved with the decoration painter, in this specific case it is easier to use borders and supported Substance APIs (to fetch the color schemes). These borders are the only usage of Substance APIs outside the self-contained definition of the custom skin. This is an example of the tradeoff between containing the painting routines inside the skin definition and the limitations of the Substance skinning layer that impose greater complexity on implementing this specific feature.

The next screenshot shows a zoomed version of the buttons in one of the footers:

In addition to the details on the gradient fill and the double border, there is one more important thing – the seamless appearance of the buttons as one joined group. In order to implement this, i am using the <span style="color: darkblue;">org.jvnet.flamingo.common.JCommandButtonStrip</span> component from Flamingo component suite with the matching Substance plugin. Buttons placed in the <span style="color: darkblue;">JCommandButtonStrip</span> will have continuous background, a single separator line between them and correct rounded corners on the left / right buttons.

Using Flamingo also facilitates creation of custom icons for the header and footer buttons. In this case, i am using the offline Flamingo SVG transcoder to transcode a few icons from the Tango iconset to pure Java2D based classes. A combination of a few filters can make these icons white with a darker halo shade.

Even when you think you’re done

The process of defining, implementing and refining the visuals can take a few iterations until both sides (design and implementation) are satisfied with the results. In this process, paying attention to the work of the designer is as important as handling all the corner cases in the business logic. Indeed, a few ill-advised pixels or a drab color scheme are not going to bring your application down. However, if you are interested in providing an appealing and immersive flow to your users, it is most certainly worth extra few days of investment.

In this entry i’m going to talk about the fourth step in the process of taking the UI definitions from your designer and converting them to a live implementation. This process is illustrated by taking design of Cookbook UI (from the My Dream App contest) and turning it into a Swing application using Substance look-and-feel. The code behind the process is available in the Substance Samples project that aims to provide a collection of blueprints for creating visually rich UIs in Swing.

Anatomy of a skin

While the concepts of decoration areas and decoration painters introduced in the second phase and implemented in the third phase are one of the most powerful features in Substance, they are part of the more comprehensive package of settings designed to facilitate creation of consistent and configurable visuals for modern graphical user interfaces. In Substance terminology it is called a skin.

The skin definition in Substance consists of the following:

• Decoration areas and color scheme bundles:
  • List of supported decoration areas.
  • Color scheme bundles for the supported decoration areas.
  • Optional background color schemes for the supported decoration areas.
• Watermarking:
  • Optional watermark.
  • Optional watermark color scheme.
• Painters:
  • Gradient painter.
  • Decoration painter.
  • Highlight painter.
  • Border painter.
• Miscellaneous:
  • Button shaper.
  • Optional list of decoration area types that have drop shadow borders on the top pixels.
  • Optional values for start and end values of selected tab fade.

This phase of Cookbook UI implementation will focus on creating the other parts of the skin, including color schemes, color scheme bundles, the gradient painter and the border painter.

Color schemes

A color scheme is a set of information that allows painting a control in a specific visual state. In general, a color scheme defines a collection of colors that are used by the various Substance painters to paint different control areas (such as background fill, border etc) under a specific visual state.

The color schemes were implicitly used in the previous phase to drive the colorization of the decoration area textures. At the most basic level a color scheme can be thought of as a palette that provides colors to the different painters. Each color scheme defines seven basic colors, six for background and one for foreground. In addition, a color scheme exposes derived colors that are used for painting watermarks, text selections, focus rings and more. The derived colors are usually implemented as a combination of one or more basic colors and can be overriden by the custom skin.

The main two color schemes for Cookbook UI are Golden Brown and Dark Brown. Here are their background palettes:

At the present moment Substance does not provide a visual tool to create a color scheme from an image palette. These two color schemes were created manually using the simple image editor and color pick tool.

Looking at the Cookbook UI design we can see that Golden Brown color scheme is used for:

• Background fill and texture of header and footer areas.
• Background fill of default buttons in header and footer areas.
• Highlights on the selected elements in sidebar area.
• Scroll bar in sidebar area.

The Dark Brown color scheme is used for:

• Background fill and texture of sidebar area.
• Selected buttons in header and footer area.
• Slider track in header area.

The definition of color scheme bundles in the custom Substance skin will use these two color schemes as the main building blocks. Dark Brown will be used for:

• <span style="color: darkblue;">GENERAL</span> area, controls in default and disabled state. Disabled controls will be painted with 70% opacity.
• <span style="color: darkblue;">PRIMARY_TITLE_PANE</span>, <span style="color: darkblue;">TOOLBAR</span> and <span style="color: darkblue;">FOOTER</span> areas, controls in active states. This will make the selected button in the toolbar painted with dark background.

Golden Brown will be used for:

• <span style="color: darkblue;">GENERAL</span> area, controls in active state. This will paint the sidebar scroll bar since the enabled scroll bars are painted in active state (this is true for all Substance skins).
• <span style="color: darkblue;">PRIMARY_TITLE_PANE</span>, <span style="color: darkblue;">TOOLBAR</span> and <span style="color: darkblue;">FOOTER</span> areas, controls in default and disabled state. Disabled controls will be painted with 70% opacity.

For the comparison, here is a part of Cookbook UI:

And here is its implementation with a custom Substance skin:

Note the correct color schemes for the relevant decoration areas, including the background, textures, buttons, scroll bar and slider. The only discrepancy comes from the slider track – by design Substance uses the same default (Golden Brown) color scheme to paint its track unless the mouse is over the slider.

In addition to the two color schemes above, we define three color schemes to be used on <span style="color: darkblue;">NONE</span> area type. In case of Cookbook UI these schemes are only relevant for the search text field in the second footer panel (marked as <span style="color: darkblue;">NONE</span> to create the custom visuals). Since every Substance skin must define a color scheme bundle for the <span style="color: darkblue;">NONE</span> area type, this is a step that you can not omit. Here are the palettes for the active, default and disabled color schemes of <span style="color: darkblue;">NONE</span>:

Gradient and border painters

Here is a zoomed version of footer buttons in Cookbook UI:

Analyzing the visuals, we can see:

• The gradient fill goes from light at the top to dark at the middle with no brightness inflection.
• The gradient is overlayed with the continuous texture of the relevant region.
• The outer border is a gradient that goes from dark at the top to very dark at the bottom.
• The inner border is a gradient that goes from very light at the top to completely translucent at the bottom.

The implementation has a custom gradient painter and a custom border painter. Base Substance painters provide extension points for computing the relevant stop point colors, handling all the rest of the logic (anti-aliasing, stroke widths, insets, scaling gaps, caching etc). All we need to do in our custom painter implementation is to emulate the colors of the target design.

Here are the original design and the custom Substance implementation side-by-side:

In this entry i’m going to talk about the third step in the process of taking the UI definitions from your designer and converting them to a live implementation. This process is illustrated by taking design of Cookbook UI (from the My Dream App contest) and turning it into a Swing application using Substance look-and-feel. The code behind the process is available in the Substance Samples project that aims to provide a collection of blueprints for creating visually rich UIs in Swing.

Overview of the application and Substance decoration areas

In the first step we have identified the decoration areas of Cookbook UI, and in the second step we mapped these areas to Substance decoration areas. The screenshot below shows the application decoration areas:

And the screenshot below shows an overlay of the Swing container hierarchy and the tagging of relevant containers associating them with the matching Substance decoration areas:

It is now time to implement the visuals of Cookbook decoration areas.

Fidelity to the original design

During the implementation stage you should strive to be as close as possible to the original design. While sometimes the technical limitations of the specific UI toolkit / library may prevent achieving the exact visuals and dynamic behavior as designed, you as the developer should not decide to change the design without providing feedback to the design team and waiting for the reworked visuals to implement.

As far as the implementation is concerned, a valid and in most cases simpler option would be to work on the image level. Most probably the design team uses a tool that allows compositing multiple layers into the final files that they are passing to the development. Those layers that represent decoration textures can be used directly to provide high-fidelity implementation. There is a number of important points to remember if you decide to go this route:

• Target user machines can have different monitor sizes, and some environments may be multi-monitor setups. The images need to be big enough to accomodate dynamically resizable UIs that can sometimes span multiple monitors.
• If you decide to use a smaller size image and replicate (tile) it to cover the entire span of the relevant area, make sure that the image edges provide seamless appearance when placed in succession. Even the smallest discrepancy will unconsciously bother the users and degrade the user experience.
• You need to decide on the anchor point. Is it the top-left corner of the monitor, or the top-left corner of the application window? Some UI toolkits (such as Swing) may employ drawing optimization techniques that can result in image shearing on partial redrawing.

Another option is to implement the target design programmatically. While it is harder to achieve the exact visuals using pure code (even with such an advanced API as Java2D), this approach may be suitable for the programmers who are at ease with the APIs presented by the relevant layers. While the exact visuals will be most probably impossible to achieve, with the right amount of tweaking and feedback from the designers it is possible to arrive at a solution that satisfies both sides.

Implementing Substance decorations

To show my appreciation of the power of Java2D (and as a programmer myself), this specific implementation is going to use pure code to achieve visuals that are significantly close to the target UI. To speed up the development process i’m going to use the excellent collection of filters available from Jerry Huxtable under the Apache 2.0 license.

The header and the footer portions of the Cookbook UI use a texture that looks like a cross between brushed metal and wood. To implement this texture, i’m using a combination of <span style="color: darkblue;">BrushedMetalFilter</span> and <span style="color: darkblue;">LookupFilter</span> to create a brushed texture that is mapped to the colors of the relevant Substance color scheme (more on the color scheme selection in the next phase).

Here is the texture image that is going to be painted on top of the gradient fill:

The screenshot on the left shows a portion of Cookbook UI header area, and right next to it is its implementation with a custom Substance decoration painter based on the above filters:

The screenshot on the left shows a portion of Cookbook UI footer area, and right next to it is its implementation with a custom Substance decoration painter based on the above filters:

The sidebar of the Cookbook UI uses a fine-wood texture. To implement this texture, i’m using a combination of <span style="color: darkblue;">WoodFilter</span> and <span style="color: darkblue;">LookupFilter</span> to create a wood texture that is mapped to the colors of the relevant Substance color scheme.

Here is the texture image that is going to be painted on top of the gradient fill:

The screenshot on the left shows a portion of Cookbook UI header area, and right next to it is its implementation with a custom Substance decoration painter based on the above filters:

Positioning and sizing the generated textures

As mentioned in the mapping step, the implementation must not expose the discrepancy between application and implementation areas. In our case, the sidebar spans two adjacent panels, and the footer spans three panels that don’t even have the same immediate parent. It is absolutely critical not to let these details escape into the UI visuals. The visuals presented to the user must be seamless as though painted in the same step.

Considerations when using images are applicable for the pure Java2D implementation. If you’re going to tile smaller images, you need to make sure that the edges are seamless. If you’re going to create one big image, you need to query the toolkit and compute the combined bounds of all monitors (in this aspect it is easier to go pure-Java2D route than use images). Last, you need to anchor the images so that partial rendering does not result in sheared tiling.

The specific implementation uses APIs available on <span style="color: darkblue;">GraphicsEnvironment</span>, <span style="color: darkblue;">GraphicsDevice</span>, <span style="color: darkblue;">GraphicsConfiguration</span> to query the monitor configuration and compute the combined bounds of all monitors. The images created using filters thus cover the entire screen setup. There are two disadvantages of doing so – longer computation time and higher memory footprint. On the other hand, we do not need to worry about tile edges. Also, large areas will be painted in one Java2D call, as opposed to possibly multiple renderings of different areas of a smaller tile. Last, the anchoring is done to the top-left corner of the application window.

When the specific panel needs to be painted, we compute the offsets to the top-left corner of the application window. These offsets are then used to compute the area of the texture image to be painted on the panel. This ensures that even though the “perceived” (application) decoration area is implemented by multiple containers / components, the appearance is seamless and continuous.

Implementing the lights

The “light bar” of Cookbook UI proved to be the most challenging of the visuals. While it can be considered a tiled texture, it is explicitly anchored to a specific point in the window (the bottom-left corner of the light holder). While other textures (header, footbar) can be arbitrarily anchored (as long as all relevant areas use the same anchor point), this assumption does not hold here.

In addition, remember that the application sidebar is implemented as two separate Swing panels that do not share the same immediate parent. This is due to the functional restrictions detailed in the first step. If we mark each one of these panels as <span style="color: darkblue;">GENERAL</span>, we’re going to store an explicit reference to the top part of the sidebar (the light holder) in our decoration painter. This is not desirable since it creates an explicit dependency between the skin and the application, which may prove problematic if we want to reuse this skin in other portfolio applications.

The solution presented in the second step is to mark the center panel of the sidebar container as <span style="color: darkblue;">GENERAL</span>, and mark the inner footer panels as <span style="color: darkblue;">FOOTER</span>. As the parent decoration area type is propagated to all children that do not define their own type, the sidebar panels are painted with <span style="color: darkblue;">GENERAL</span> type. When the specific sidebar panel is painted, we compute the offsets to the farthest container parent that is decorated with <span style="color: darkblue;">GENERAL</span>. These offsets will effectively hold the distance to the bottom-left corner of the custom component that implements the light holder visuals (more on this in the next step).

Having these offsets in hand we can start tiling an image of a single light until we cover the entire width of the currently painted panel. This ensures that even though the sidebar application decoration area is implemented by multiple containers / components, the appearance of the light bar is seamless and continuous.

It might be easier to ask the designers to provide a single translucent image of a light bulb with the matching diffused light cone. The present implementation imitates this with a blurred mushroom shape with a translucent gradient applied to it. However, my recommendation would be to use an image-based approach for such fine visuals as this.

Here is the result of Java2D-based implementation of a single light:

The next screenshot shows the light bar area of the Cookbook UI:

And the Java2D-based implementation which is not as close as the other visuals presented in this step: