In addition to the usual bug fixes and getting the internal implementation ready for the changes coming in the next major release, Substance 5.3 (code-named Reykjavik) will introduce three new skins. Graphite Aqua is joining Magellan and Gemini; it is based on the existing Raven Graphite skins, adding the blue highights found in HUD windows in iPhoto 09. To use it in your application, you have the following options:

• -Dswing.defaultlaf=org.jvnet.substance.api.skin.SubstanceGraphiteAquaLookAndFeel
• UIManager.setLookAndFeel(new SubstanceGraphiteAquaLookAndFeel())
• UIManager.setLookAndFeel("org.jvnet.substance.api.skin.SubstanceGraphiteAquaLookAndFeel")
• SubstanceLookAndFeel.setSkin(new GraphiteAquaSkin())

Here are a few screenshots that show this new skin. A small frame with a tabbed pane and a few different controls:

Highlights on selected items in lists and trees:

A thumbnail of the main Substance test application (click for full-size view):

Error dialog from SwingX components:

Login dialog from SwingX components:

A few sliders:

As with all Substance core skins, this is work in progress and will be polished over time. The Graphite Aqua skin will be officially available in the next few days as part of the 5.3 release candidate.

In addition to the usual bug fixes and getting the internal implementation ready for the changes coming in the next major release, Substance 5.3 (code-named Reykjavik) will introduce three new skins. The first is Magellan which is based on the design of the Ballpark website (found via Hongkiat) and is reminiscent of the vibrant colors of the Windows XP taskbar ans Start menu.

To use it in your application, you have the following options:

• -Dswing.defaultlaf=org.jvnet.substance.api.skin.SubstanceMagellanLookAndFeel
• UIManager.setLookAndFeel(new SubstanceMagellanLookAndFeel())
• UIManager.setLookAndFeel("org.jvnet.substance.api.skin.SubstanceMagellanLookAndFeel")
• SubstanceLookAndFeel.setSkin(new MagellanSkin())

Here are a few screenshots that show this new skin. A small frame with a tabbed pane and a few different controls:

Highlights on selected items in lists and trees:

A frame with menu bar, tool bar and status bar from SwingX project:

A thumbnail of the main Substance test application (click for full-size view):

Error dialog from SwingX components:

Login dialog from SwingX components:

A few sliders:

As with all Substance core skins, this is work in progress and will be polished over time. The Magellan skin will be officially available in the next few days as part of the 5.3 release candidate.

Trident animation library allows adding a short fade-out sequence to a Swing / SWT window that is being closed. This can provide an unobtrusive visual feedback to the user, confirming his action and smoothly guiding his eye to the new application state.

Here is a utility method to add a fade-out sequence to disposing a Swing window – this code requires the latest builds of JDK7 that added the Window.setAlpha(float) method:

public static void fadeOutAndDispose(final Window window,
      int fadeOutDuration) {
   Timeline dispose = new Timeline(window);
   dispose.addPropertyToInterpolate("opacity", 1.0f, 0.0f);
   dispose.addCallback(new UIThreadTimelineCallbackAdapter() {
      @Override
      public void onTimelineStateChanged(TimelineState oldState,
            TimelineState newState, float durationFraction,
            float timelinePosition) {
         if (newState == TimelineState.DONE) {
            window.dispose();
         }
      }
   });
   dispose.setDuration(fadeOutDuration);
   dispose.play();
}

and the matching method for disposing an SWT shell with a fade-out sequence, which requires SWT 3.4 to run:

public static void fadeOutAndDispose(final Shell shell, int fadeOutDuration) {
   Timeline dispose = new Timeline(shell);
   dispose.addPropertyToInterpolate("alpha", 255, 0);
   dispose.addCallback(new UIThreadTimelineCallbackAdapter() {
      @Override
      public void onTimelineStateChanged(TimelineState oldState,
            TimelineState newState, float durationFraction,
            float timelinePosition) {
         if (newState == TimelineState.DONE) {
            shell.dispose();
         }
      }
   });
   dispose.setDuration(fadeOutDuration);
   dispose.play();
}

Instead of calling Shell.dispose() or Window.dispose(), call the fadeOutAndDispose() method, passing the duration of the fade-out sequence in milliseconds. A previous entry has discussed another option – overriding the Window.dispose() method in your custom Swing class. While this works in Swing, SWT does not allow extending the Shell class outside the org.eclipse.swt.widgets package.

Over the course of this week i’m talking about different concepts in the Trident animation library for Java applications. Part ten talks about the plugin layer allows interested applications to provide additional property interpolators for custom application classes and support additional Java-based UI toolkits.

Plugin overview

The core functionality of the Trident library can be extended to address custom needs of the specific applications. Out of the box Trident supports:

• Interpolating float and integer fields of any Java object that provides the matching public setter methods.
• Swing and SWT UI toolkits, respecting the threading rules and providing interpolators for the custom graphic classes

The extensibility (plugin) layer allows interested applications to:

• Provide additional property interpolators for custom application classes
• Support additional Java-based UI toolkits

Creating a Trident plugin

A Trident plugin is specified by the META-INF/trident-plugin.properties file that should be placed in the runtime classpath. Note that you can have multiple plugins in the same runtime environment – if each one is coming from a different classpath jar, for example.

The format of trident-plugin.properties is simple. Each line in this file should be of the following format:

Key=FullyQualifiedClassName

There are two supported keys:

• PropertyInterpolatorSource allows specifying custom property interpolators
• UIToolkitHandler allows supporting custom UI toolkits

Sample plugin specification

The core Trident library contains a plugin that supports Swing and SWT UI toolkits, as well as property interpolators for a few core classes. Here are the contents of the plugin descriptor:

UIToolkitHandler=org.pushingpixels.trident.swing.SwingToolkitHandler
PropertyInterpolatorSource=org.pushingpixels.trident.swing.AWTPropertyInterpolators

UIToolkitHandler=org.pushingpixels.trident.swt.SWTToolkitHandler
PropertyInterpolatorSource=org.pushingpixels.trident.swt.SWTPropertyInterpolators

PropertyInterpolatorSource=org.pushingpixels.trident.interpolator.CorePropertyInterpolators

Property interpolator plugins

The PropertyInterpolatorSource entries in the plugin descriptor files allow application code to provide property interpolators for custom application classes. The value associated with this key must be the fully qualified class name of an application class that implements the org.pushingpixels.trident.interpolator.PropertyInterpolatorSource interface.

This interface has one method – public Set<PropertyInterpolator> getPropertyInterpolators() – which returns a set of custom property interpolators. Custom property interpolators can be used in two ways:

• The Timeline.addPropertyToInterpolate(String, Object, Object, PropertyInterpolator) API to explicitly specify the property interpolator to be used
• The Timeline.addPropertyToInterpolate(String, Object, Object) API that will choose the property interpolator that matches the types of the from and to values

Property interpolator specification

The org.pushingpixels.trident.interpolator.PropertyInterpolator interface has two methods.

The public Class getBasePropertyClass() is used to choose the property interpolator in the Timeline.addPropertyToInterpolate(String, Object, Object). Internally, all registered property interpolators are queried to check whether they support the specified from and to values using the Class.isAssignableFrom(Class). The first property interpolator that has a match for both values will be used.

For example, the PointInterpolator in the core AWT property interpolator source (AWTPropertyInterpolators class) has the following implementation of this method:

	@Override
	public Class getBasePropertyClass() {
		return Point.class;
	}

The public T interpolate(T from, T to, float timelinePosition) is used to compute the interpolated value during the current timeline pulse. For example, the PointInterpolator in the core AWT property interpolator source (AWTPropertyInterpolators class) has the following implementation of this method:

	public Point interpolate(Point from, Point to, float timelinePosition) {
		int x = from.x + (int) (timelinePosition * (to.x - from.x));
		int y = from.y + (int) (timelinePosition * (to.y - from.y));
		return new Point(x, y);
	}

Bringing it together

Let’s look at the following Swing snippet that has a class with a Point field and a timeline that interpolates the value of that field:

import java.awt.*;

public static class MyRectangle {
	private Point corner = new Point(0, 0);

	public void setCorner(Point corner) {
		this.corner = corner;
	}

	...
}

Timeline move = new Timeline(rectangle);
move.addPropertyToInterpolate("corner", new Point(0, 0),
	new Point(100, 80));
move.playLoop(RepeatBehavior.REVERSE);

What happens when move.addPropertyToInterpolate is called? Internally, the Trident core looks at all available property interpolators and finds that the AWTPropertyInterpolators.PointInterpolator is the best match for the passed values (which are both java.awt.Points). Then, at every pulse of the move timeline, the MyRectangle.setCorner(Point) is called.

Note that the application code did not explicitly specify which property interpolator should be used.

UI toolkit plugins

Graphical applications are a natural fit for animations, and Trident core has built-in support for Swing and SWT. This support covers threading rules, custom property interpolators and repaint timelines.

The UIToolkitHandler entries in the plugin descriptor files allow application code to support additional Java-based UI toolkits. The value associated with this key must be the fully qualified class name of an application class that implements the org.pushingpixels.trident.UIToolkitHandler interface. Most modern UI toolkits have threading rules that the applications must respect in order to prevent application freeze and visual artifacts. The threading rules for both Swing and SWT specify that the UI-related operations must be done on a special UI thread, and the methods in the UIToolkitHandler are used to determine the relevance of these threading rules.

Respecting the threading rules

The UIToolkitHandler.isHandlerFor(Object) is used to determine whether the main timeline object is a component / widget for the specific UI toolkit. At runtime, all fields registered with the Timeline.addPropertyToInterpolate methods will be changed on the UI thread using the UIToolkitHandler.runOnUIThread method.

In the simple Swing example that interpolates the foreground color of a button on mouse rollover, the timeline is configured as

	Timeline rolloverTimeline = new Timeline(button);
	rolloverTimeline.addPropertyToInterpolate("foreground", Color.blue,
			Color.red);

If you put a breakpoint in the JComponent.setForeground(Color) – which is called on every timeline pulse – you will see that it is called on the Swing Event Dispatch Thread. Internally, this is what happens:

• When the timeline is created, all registered UI toolkit handlers are asked whether they are handlers for the specified object
• The org.pushingpixels.trident.swing.SwingToolkitHandler registered in the core library returns true for the button object in its isHandlerFor(Object)
• On every timeline pulse, a Runnable object is created internally. The run() method calls the setters for all registered fields – using the PropertyInterpolator.interpolate method of the matching property interpolator
• This Runnable is passed to the UIToolkitHandler.runOnUIThread

method of the matching UI toolkit handler.

And this is how SwingToolkitHandler.runOnUIThread() is implemented:

	@Override
	public void runOnUIThread(Runnable runnable) {
		if (SwingUtilities.isEventDispatchThread())
			runnable.run();
		else
			SwingUtilities.invokeLater(runnable);
	}

Running custom application code on UI thread

The flow described above works for the fields registered with the Timeline.addPropertyToInterpolate methods. What about the custom application callbacks registered with the Timeline.addCallback()? If the callback methods need to respect the UI threading rules of the matching toolkit, the TimelineCallback implementation class needs to be tagged with the org.pushingpixels.trident.callback.RunOnUIThread annotation.

Callback implementations marked with this annotation will have both onTimelineStateChanged and onTimelinePulse invoked on the UI thread, making it safe to query and change the UI. The UIThreadTimelineCallbackAdapter is a core adapter class that is marked with this annotation.

Querying the readiness of the timeline object

The isInReadyState(Object) is the third and final method in the UIToolkitHandler interface. After the specific UI toolkit handler has declared that it will handle the main object of the specific timeline (by returning true from the isHandlerFor(Object) method), it will be used to interpolate the registered fields and run the registered callbacks. However, some UI toolkits may impose additional restrictions on when the UI object is ready to be queried / changed.

For example, once an SWT control is disposed, it will throw an SWTException in the setForeground method. So, if the application code is running a slow animation that changes the foreground color of a button, and the application window containing this button is disposed in the meantime, the call to setForeground should be skipped.

SWT implementation of the UI toolkit handler

The trident-plugin.properties descriptor bundled with the core Trident library has the following line:

UIToolkitHandler=org.pushingpixels.trident.swt.SWTToolkitHandler

And the SWTToolkitHandler is:

public class SWTToolkitHandler implements UIToolkitHandler {
	@Override
	public boolean isHandlerFor(Object mainTimelineObject) {
		return (mainTimelineObject instanceof Widget);
	}

	@Override
	public boolean isInReadyState(Object mainTimelineObject) {
		return !((Widget) mainTimelineObject).isDisposed();
	}

	@Override
	public void runOnUIThread(Runnable runnable) {
		Display.getDefault().asyncExec(runnable);
	}
}

This is a very simple implementation of a UI toolkit handler that respects the relevant threading rules:

• The first method implements the logic that associates this handler with all SWT widgets
• The second method marks disposed widgets to skip the property interpolation / callback invocations
• The third method runs the UI related logic on the SWT thread