In this entry i’m going to talk about the second 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 areas
In the first step we have identified the decoration and functional areas of Cookbook UI. The screenshot below shows the application decoration areas:
and the next screenshot shows the application functional areas:
As you can see, the application decoration and functional areas are not the same. During this phase we are going to map the application functional areas to Swing container hierarchy and the application decoration areas to Substance decoration areas.
Mapping functional areas to Swing
This phase will in most cases take you from the realm of pure design to the limitations of Swing. While the application functional areas will in most cases define the hierarchy of your Swing containers, the mapping itself might not be straightforward. Designer’s work on the UI mockup screens does not consider the implementation limitations of the specific UI toolkit. This is especially true for such a dynamic area as resizability behavior – what happens when the user resizes the application window (if he is allowed to do so by the application code)?
If the UI design is done in a pixel-based tool (such as Photoshop), the most obvious choice for a Swing implementor would be to use absolute (null) layout manager. This is usually considered a bad Swing practice. Instead, you would usually employ a combination of core, third-party and custom layout managers that handle the initial sizing of the components and the dynamic resizing behavior.
Mapping decoration areas to Substance
This phase will take you further away from the pure design to the limitations of Substance. If you are not familiar with the concept of decoration areas and painters in Substance, please first read the following documentation:
- Decoration painters
<span style="color: darkblue;"><a href="https://substance.dev.java.net/docs/api/SetDecorationType.html">setDecorationType()</a></span> API.<span style="color: darkblue;"><a href="https://substance.dev.java.net/docs/api/GetDecorationType.html">getDecorationType()</a></span> API.
The list of available Substance decoration areas is defined in the <span style="color: darkblue;">org.jvnet.substance.painter.decoration.DecorationAreaType</span> enum.
As the documentation of <span style="color: darkblue;"><a href="https://substance.dev.java.net/docs/api/SetDecorationType.html">setDecorationType()</a></span> specifies, the passed decoration area type is applied to the component itself and recursively on all its children, unless a child is marked with another decoration area type (with the same API). When is this behavior useful? We’re going to see a more complicated example in a short while, but in the meantime here is a simple one:
This screenshot shows a footer bar of the recipe list panel. As you can see, while the add / remove buttons are using the same colors as the footer bar itself, the text field is skinned with a different color scheme. In Substance API, you would mark the footer bar with <span style="color: darkblue;">FOOTER</span> and the search text field with <span style="color: darkblue;">NONE</span>. All the buttons would get the <span style="color: darkblue;">FOOTER</span> from their parent (footer bar), while the search text field will use the color scheme bundle of the <span style="color: darkblue;">NONE</span> decoration are type.
While not necessarily required, it is useful to remember that most core (and supported third-party) components are already marked to belong to a specific Substance decoration area. This comes especially handy for the header application area. The header portion of Cookbook UI can be mapped to a decorated title pane (<span style="color: darkblue;">PRIMARY_TITLE_PANE</span> type) and an unfloatable toolbar (<span style="color: darkblue;">TOOLBAR</span> type). While not necessarily required, reusing existing Swing components will make the implementation part easier.
What is another usage of using different decoration area types on a parent component and one of its children? The answer is quite simple – when the application functional and decoration areas are different (like is the case with Cookbook UI). The screenshot below shows the sidebar part of Cookbook:
There is a clear visual continuation between the category list and recipe list as far as the decoration areas go. The textures (dark mahogany and golden brush) flow seemlessly across the boundaries of the functional areas, and the top bar with evenly-spaced diffused lights further enforces this continuation. The final polish comes from the vertical separator that uses matching colors in the different decoration areas.
If, for the reasons stated above, you have decided to build your Swing container hierarchy based on the application functional areas, you can use the matching Substance decoration area types on the specific sub-panels (without mixing the different types in the same hierarchy path). However, using the <span style="color: darkblue;"><a href="https://substance.dev.java.net/docs/api/SetDecorationType.html">setDecorationType()</a></span> API is only one part of the implementation. The second part comes from your custom decoration painter that is implementing the painting itself. While this topic is subject of the next phase, the ease of implementation is going to dictate mixing different decoration area types as shown in the next section.
Swing containers and Substance decoration areas
This section will show the Swing hierarchy behind the Substance-based implementation of Cookbook UI and the matching decoration area types. While most of the reasons behind this implementation are given in the sections above, one of them is part of the next phase (simplifying the implementation complexity of the custom decoration painter).
We’re going to start with the layout of the content pane:
Here, we’re using the core <span style="color: darkblue;">BorderLayout</span> and add toolbar at <span style="color: darkblue;">NORTH</span>, sidebar at <span style="color: darkblue;">WEST</span> and main recipe panel at <span style="color: darkblue;">CENTER</span>.
The next screenshot shows the children of the sidebar panel:
The top part is the only custom component which is not painted by Substance. This is done for purely implementation complexity considerations – it is much easier to override the <span style="color: darkblue;">paintComponent()</span> method to emulate the light holder than to do it with Substance decoration painters. The <span style="color: darkblue;">CENTER</span> part is another panel which is decorated with <span style="color: darkblue;">GENERAL</span> area type. As the next phase will show, this makes it easier to implement the evenly-spaced diffused lights (the continuous look of the texture is not a factor in this particular decision).
Inside this <span style="color: darkblue;">GENERAL</span>-decorated panels we have the <span style="color: darkblue;">BorderLayout</span> with two panels:
Note that these two panels do not have any decoration area type installed on them – they get the <span style="color: darkblue;">GENERAL</span> from the parent panel.
The last diagram shows the last level of Swing hierarchy as far as mapping the decoration areas goes:
Here, each (functional) panel has a footer bar and the main area. The footer bar is a panel decorated with <span style="color: darkblue;">FOOTER</span>, thus overriding the decoration area type inherited from the grandparent panel. The main areas do not have any decoration area types installed on them, inheriting the grandparent panel settings.
The final piece comes by installing the <span style="color: darkblue;">NONE</span> type on the search text field in the second footer bar, thus overriding the inherited <span style="color: darkblue;">FOOTER</span> setting.
In this entry i’m going to talk about the first 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.
Identifying application decoration areas
The first step in implementing a specific UI is identifying the application decoration areas. Here is a thumbnail of the main Cookbook design:
This screen has four main decoration areas. The following screenshots show a translucent light blue overlay to highlight each one of the areas.
The top portion of the application window is the header:
The bottom portion of the application window is the footer:
The left portion of the application window is the sidebar:
The center-right portion of the application window is the main:
Identifying application functional areas
Unlike the decoration areas that are primarily delineated by similar colors and textures, the functional areas are delineated primarily by the user-facing business logic. In Cookbook UI there are three main functional areas (in addition to the general control area in the header):
Note how the functional areas and decoration areas are not identical. In fact, every functional area intersects two decoration areas (and vice versa in most cases). Here is a fll-size view of the sidebar area in Cookbook UI:
Note that while the lists and footers have different visuals (colors, textures, gradients), they belong to the same functional group. For example, the footer controls for the category list are located directly beneath it, and the footer panel itself has the same width as the category list. This is especially true for dynamic scenarios when the entire UI is resized or re-proportioned.
This step may cross the line between the pure design and the implementation (Swing or other UI toolkits). As the developer, you will mostly be operating on the functional UI areas. It is important to understand that Substance supports the notion of different decoration and functional areas. However, in some cases the certain limitations of the Substance decoration layer will impose some restrictions on the way you structure the Swing hierarchy.
The next part will talk about mapping application functional areas to Swing container hierarchy and mapping the application decoration areas to Substance decoration areas.
Ben Galbraith had a very interesting session at this year’s JavaOne. Titled “Creating a Compelling User Experience” (see PDF slides), it talked about the importance of visual aesthetics combined with close collaboration between developers and designers to create applications that are both functional and appealing. Slide 75 shows a screenshot of an application called “Cookbook”. Contrary to what Ben mentioned, this application has never been publicly available as far as i know. One of the winners of My Dream App contest, it never moved past the screenshots and private developer builds. However, the screenshots show amazing attention to detail and painstaking polish in every UI element.
The big question that a lot of RIA frameworks try to address nowadays is bringing designers and developers together in the same cycle. Adobe and Microsoft have tools that allow both sides to work on the same project, designers defining and refining the visuals, and developers filling in the logic of business, communication, persistence etc. JavaFX promised tooling support as well, and it remains to be seen whether it will move past the Illustrator / Photoshop plugins.
What about Swing developers? How difficult it is to create a UI such as Cookbook (mockups) in Swing? Here is one of the final Cookbook designs (click to see full view):
Can this be done in Swing? Most certainly yes, if you have tons of time on your hands and are a Swing / Java2D guru. Can this be made reusable to use in other applications (for your portfolio suite)? Most certainly yes, but that will take even more time.
Here is a full-size version of the left part of this design:
Here is an incomplete list of small but important visual details that come together as a single well-tuned UI:
- Continuous look of the title pane and the toolbar.
- Similar texture and coloring of title pane / toolbar and the footer.
- Different texture on the left side bar.
- Two different panels on the left side bar (one of them is a scroll bar) sharing the same continuous texture and lights.
- Vertical separators extending from the side bar panels to the footer bar, changing the color to match the relevant areas.
- Continuous texture on the buttons in the toolbar and the footer.
- Single borders (border strip) on the buttons in the toolbar and the footer.
- The search text field in the footer is not using the same coloring as the footer itself.
And here is the implementation of the same UI as a combination of a custom Substance skin and a small amount of application Java2D code that is using published Substance APIs to achieve a similar look using no images (click for full-size version):
and the full size version of the left side of the screen:
This application is available as part of the first drop of the Substance Samples project that will grow to include implementation of additional rich UIs. The code is available in the SVN repository and I will go into more details of analyzing the specific UI, creating a custom Substance skin and augmenting it with a small amount of custom Java2D code in the next entries.
It is my fault that i have started working on this UI after announcing the release candidate for version 5.0. It is true what they say – you need to eat your own dog food. The decoration painters are one of the more advanced features in Substance, and i have not completely tested this area on such a demanding interface as Cookbook. During the implementation of this UI i ran into a number of issues with the current published API. While some of the issues result in boilerplate code (and as such can be delivered in additional APIs in the next release), i had to introduce breaking changes to the APIs delivered in 5.0 RC. The changes are very small:
- Adding a new parameter to the gradient painter API.
- Changing the visual behavior when a component has a number of parents each marked with a different decoration area (think a toolbar placed in a status bar).
This may break applications that used these published APIs. As much as i hate doing so, i can not postpone it to release 5.1 since it is not going to be a major one. We all make mistakes, and mine was in not initiating the work on the Substance Samples project sooner.
One final note – this is still work in progress. It does not intend to create an indentical copy of the target UI. While some of the colors will be tweaked (the Cookbook design uses more saturated yellows), the main goal of this project is to show the power of Substance in creating custom skins that can be reused in different applications and tweaked as required.
