April 22nd, 2008

Roadmap for Substance 5

With release 4.3 of Substance look-and-feel available last Monday (and a few patch releases to address bugs since then), it is time to think about the next release. Substance is now three years old and it has seen fourteen releases since it was started in April of 2005. Most of the minor releases did not introduce binary incompatibilities, and the last two major releases (3.0 and 4.0) touched the public APIs in ways that should have affected only a small portion of users. However, due to my very heavy commitment to make Substance the library of choice to create modern user interfaces (and resulting short release cycles), sometimes i have made bad decisions on the features to include and the APIs to expose them.

Over the last year and a half the Substance codebase has become a complex thing to understand and maintain. Every new feature that has been added (especially the skins and decoration areas) made it ever more difficult to maintain backwards compatibility and still address the needs of designing modern UIs. This sometimes led to an awkward implementation and even more awkward public APIs (as anyone who dared to use a SubstanceComplexTheme would attest).

Even though i am the single developer on the project (but thanks to all those who sent bug fixes and graciously contributed portions of code), i found it increasingly harder to understand and extend existing functionality. And here i am not talking about working on the project every other weekend; i look at and work with the code pretty much every day. Something had to be done, and over the last eight months i have considered the two options that i had.

The first option would be to start a new project. Learn from all the mistakes that i’ve made, all the features that were added and not used, all the accidental complexities that grew exponentially and didn’t really mesh well together, all the nice-to-haves that added performance hit even when not used. In short, stop working on Substance (moving into maintenance bug-fix mode only) and start anew.

The second option would be to wait for the next major release and do all the things necessary for the long term health and viability of the project. To rework the cruft and the mess into an API that best reflects my understanding of creating modern UIs as i see it at this moment. To put myself into my users’ shoes and question every client property, VM flag and API method. To see how hard it is to customize the default behavior without reading the Javadocs and the documentation. To see how hard it is to create a custom skin after reading the source code of existing core skins. And most of all, to see what can be sacrificed in the short term to address the long-term problems.

The first drop of the next major release (code-named Substance 5) will be available for download tomorrow. Here is the list of major changes that have been made to the core library and its plugins.

  • Requires JDK 6.0. The only VM that is being used for tests is 6u10.
  • SubstanceLookAndFeel class is now abstract and does not have any public constructors. Use a core skin-based LAF, extend to set a custom skin or use static setSkin method.
  • Removed support for pluggable text rasterizers (substance-bramble plugin based on SWT). 6u10 addresses poor Segoe UI rendering on Vista.
  • Addressing performance. The first drop of 5.0 is 20% faster than release 4.3. This is work in progress.
  • Reworked notion of themes. Split the functionality of SubstanceTheme, SubstanceComplexTheme and SubstanceSkin into SubstanceColorScheme, SubstanceColorSchemeBundle and SubstanceSkin. Tweaked most of the core skins to take advantage of the new more flexible and straighforward APIs.
  • Removed most of the VM flags. The only two flags are for tracing memory allocation and heap status. Use skin / image watermark / configuration APIs.
  • Reconciled APIs that were added to address specific user requests and did not result in a consistent API. This should make making a custom skin / tweaking default Substance behavior easier and more straightforward.
  • New client property to provide per-window skinning. Can use different skins for different top-level windows.
  • Removed the client properties and APIs for setting themes and painters on per-component level. Use colorization client property and per-window skins for custom tweaking.
  • The new default mode does not add any extra UI elements (menu search, lock icons etc).
  • Removed performance-adverse functionality of custom overlay and composites. Was unintentionally broken since release 4.2 and intentionally unfixed in both 4.2 and 4.3. A single complaint shows that this functionality is of minuscule use.
  • Removed combobox auto-completion. Use SwingX, GlazedLists or JIDE.
  • Moved UI debug mode (additional context menu on title panes and scroll bars) to a substance-tools plugin
  • Consolidated existing theme pack, button shaper pack and watermark pack into substance-extras plugin
  • New SubstanceApi annotation marks public APIs (classes, constructors, methods)
  • Internal restructuring of the packages to make the codebase more organized.

Undoubtedly, the most important bullet in this list is moving to JDK 6.0 as the runtime requirement. This has not been a minor decision. I understand that for a great number of users this will mean that they will not upgrade to Substance 5. I am doing this for the long-term health of the project.

At this point, release 4.3 officially enters into the longterm bugfix mode. With older releases i only backported bug fixes during the first week after a stable release. Release 4.3 will continue to receive all but most complicated bug fixes to accommodate users that can not upgrade to Substance 5 (due to JDK requirements).

For more information on changes to the client properties, VM flags and APIs consult the first draft version of the API change overview document. The project documentation will be updated in the following weeks.