Click on the button below to launch a signed WebStart application that shows the available Substance features.
Trident 1.2 is a stabilization release and has a few new APIs.
You’re more than welcome to download the release candidates for Trident, Substance and relevant plugins. If you see any exceptions, visual artifacts or anything else that shouldn’t be there – don’t assume that i know about it. Drop me a line on project forums or mailing lists. The final releases for the libraries are scheduled on April 14.
The Trident animation library was born in February 2009 out of the internal animation layer used in Substance look-and-feel over the last three years. A year after, it is nearing its third official release which focuses mainly on stabilizing the API and ironing out the existing bugs.
The major milestone for this release is moving Substance 6.0 to use Trident – along with validating the library performance and flexibility to support a wide variety of UI animations. Trident 1.2 has also added a few new APIs to address a few common application requirements.
Custom property accessors
The default mechanism to retrieve and update the interpolated field is to use reflection to look up and call the matching published getter and setter. Application code that does not wish to expose these methods should use the following APIs:
TimelinePropertyBuilder.getWith(PropertyGetter) – new in 1.2
TimelinePropertyBuilder.setWith(PropertySetter)
TimelinePropertyBuilder.accessWith(PropertyAccessor) – new in 1.2
Where the relevant interfaces are defined in the TimelinePropertyBuilder class as follows:
If the timeline property builder is configured with a custom property setter / accessor, the set() will be called at every timeline pulse passing the object, the name of the field and the new value to set on the field. If the timeline property builder is configured with a custom property getter / accessor, the get() will be called when the current value of the field is needed. For example, when the builder is configured with fromCurrent(), the get() will be called to get the current field value when the timeline starts playing.
The following sample shows usage of a custom property setter:
public class CustomSetter {
private float value;
public static void main(String[] args) {
final CustomSetter helloWorld = new CustomSetter();
Timeline timeline = new Timeline(helloWorld);
PropertySetter propertySetter = new PropertySetter() {
@Override
public void set(Object obj, String fieldName, Float value) {
SimpleDateFormat sdf = new SimpleDateFormat("ss.SSS");
float oldValue = helloWorld.value;
System.out.println(sdf.format(new Date()) + " : " + oldValue
+ " -> " + value);
helloWorld.value = value;
}
};
timeline.addPropertyToInterpolate(Timeline. property("value")
.from(0.0f).to(1.0f).setWith(propertySetter));
timeline.play();
try {
Thread.sleep(3000);
} catch (Exception exc) {
}
}
}
Here, the CustomSetter class does not wish to expose the value field via a public setter. Instead, a custom property setter is provided to be called on every timeline pulse. Note that while this sample code does update the matching object field, it is not a strict requirement. Your custom property setter can do anything it wants in the set implementation – update a key-value map, update multiple fields or even ignore some of the values altogether.
The following sample shows usage of a custom property accessor backed up by a key-value map:
public class CustomAccessor {
private Map values = new HashMap();
public static void main(String[] args) {
final CustomAccessor helloWorld = new CustomAccessor();
Timeline timeline = new Timeline(helloWorld);
PropertyAccessor propertyAccessor = new PropertyAccessor() {
@Override
public Float get(Object obj, String fieldName) {
return helloWorld.values.get("value");
}
@Override
public void set(Object obj, String fieldName, Float value) {
SimpleDateFormat sdf = new SimpleDateFormat("ss.SSS");
float oldValue = helloWorld.values.get("value");
System.out.println(sdf.format(new Date()) + " : " + oldValue
+ " -> " + value);
helloWorld.values.put("value", value);
}
};
helloWorld.values.put("value", 50f);
timeline.addPropertyToInterpolate(Timeline. property("value")
.fromCurrent().to(100.0f).accessWith(propertyAccessor));
timeline.setDuration(300);
timeline.play();
try {
Thread.sleep(1000);
} catch (Exception exc) {
}
}
}
Note that both examples assume that the setter / accessor is used only for one specific field (“value”). You can use the same getter / setter / accessor implementation to access multiple fields – using the fieldName parameter passed to the get() and set() methods.
Stopping a timeline
In some cases you will want to stop a running timeline. There are three different APIs that you can use, each with its own semantics:
Timeline.abort(). The timeline transitions to the idle state. No application callbacks or field interpolations are done.
Timeline.end() – new in 1.2. The timeline transitions to the done state, with the timeline position set to 0.0 or 1.0 – based on the direction of the timeline. After application callbacks and field interpolations are done on the done state, the timeline transitions to the idle state. Application callbacks and field interpolations are done on this state as well.
Timeline.cancel(). The timeline transitions to the cancelled state, preserving its current timeline position. After application callbacks and field interpolations are done on the cancelled state, the timeline transitions to the idle state. Application callbacks and field interpolations are done on this state as well.
In addition, there is a method to indicate that a looping timeline should stop once it reaches the end of the loop. For example, suppose that you have a pulsating animation of system tray icon to indicate unread messages. Once the message is read, this animation is canceled in the application code. However, immediate cancellation of the pulsating animation may result in jarring visuals, especially if it is done at the “peak” of the pulsation cycle. Calling Timeline.cancelAtCycleBreak() method will indicate that the looping animation should stop once it reaches the end of the loop.
The animation series that was published on this blog last week has been largely the product of reworking the animation layer in Substance look-and-feel and replacing it with the Trident animation library. This work has some implications for the users of both library, and today i’m going to talk about those.
If you’re using Substance look-and-feel library in your applications, you will need to add the matching Trident jar to your classpath – starting from release 6.0 of Substance. The matching Trident version is 1.2 and it will be officially released at the same time with Substance 6.0. While this is not a major Trident release, it does remove deprecated APIs and as such will break applications that are using those APIs. All the removed APIs have direct replacements, and the final release notes will provide additional information (if you cannot find it in the code). The final Trident 1.2 / Substance 6.0 releases are scheduled for March-April 2010 timeframe.
Substance 6.0 breaks API signatures of most published painter interfaces. The painter interfaces that received two color schemes and the cycle position now only receive a single color scheme. If you are just using Substance as the application look-and-feel, you should not need to worry. If you are using Substance painter APIs to create consistent visuals for your custom / 3rd party components, you will need to change the code. If you have passed the same color scheme to a painter API call, changing your code is simple. If you passed two different color schemes, you will need to call the Substance API twice, changing the graphics composite to match the value of the cycle position.
Breaking the painter APIs is a necessary step to enable multi-state color transitions discussed at length in this series. The old APIs assumed that animating a control always involves two states – previous and current. This assumption is not correct. Suppose your buttons are painted with light blue color. When the mouse is over a button, the button is painted with light yellow color, and when the button is pressed, it is painted with saturated orange. Substance animates the button colors based on the state transitions. Suppose it takes 500ms to complete a single animation. The user moves the mouse over a button, and Substance starts animating the color from light blue to light yellow. Halfway through the animation (250ms), the user presses the button. Now, there are three states participating in the animation: default with light blue, rollover with light yellow and pressed with saturated orange. All the states contribute to the overall appearance of the button as long as the combined animation is in progress.
Tracking state transitions is done internally in Substance – in a layer built on top of Trident base timeline APIs. The tracking layer is not going to be part of Trident 1.2, since it is closely tied not only to Swing classes, but to Substance skinning model. Applications interested in adopting multi-state transitions should not use the internal state tracker layer of Substance. It is subject to change at any point in time. The base rules for multi-state transitions are derived from the examples in this series that have shown different movement paths of a physical object between three points.
The current implementation of the multi-state transitions in Substance 6.0dev does not model most of the physical laws discussed in this series. Handling momentum / inertia, direction change involving smooth turns, and the matching velocity models are not implemented. The work on this will continue throughout 2010, and some of it might find its way to the Trident itself. I am not aware of any other animation library (Java based or otherwise) that provides out-of-the-box support even for simple animations based on the physical rules discussed in this series.
Substance animations deal exclusively with colors. The current straight-line / straight-turn / no-momentum movement paths in the RGB color space result in visually consistent and smooth animations, for any reasonable durations. However, the long term goal for both Trident and Substance is to create mathematically correct animation model which is based on the rules of the physical world – where applicable. At the present moment the mathematics behind the graphs in this series is left as an exercise to the readers.
The main goal of Trident project is to provide a general purpose animation library for Java applications. Animations are a natural fit for modern client applications, and Trident has special built-in support for Java based UI toolkits such as Swing and SWT. The latest 1.2dev drop of Trident provides first support for Android, Google’s software stack for mobile devices.
First, a video that illustrates Trident looping timeline that animates the foreground color of an Android button running in an emulator:
And here is the code of the main activity behind this screen:
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
Button button = new Button(this);
button.setText("Hello, Android");
setContentView(button);
button.setTextColor(Color.BLUE);
button.setTextSize(30);
Timeline timeline = new Timeline();
timeline.addPropertyToInterpolate(Timeline. property(
"textColor").from(Color.BLUE).to(Color.RED).interpolatedWith(
AndroidPropertyInterpolators.COLOR_INTERPOLATOR));
timeline.setDuration(500);
timeline.playLoop(RepeatBehavior.REVERSE);
}
Those of you who are familiar with the Trident APIs can see that it is the same exact approach as with Swing and SWT. The only difference for Android is the explicit usage of the color interpolator, since the Android APIs use integers for colors – and the built-in mechanism for auto-discovering the matching property interpolator cannot handle this case without explicit coding in either the app code or future Android code base.
Apart from the explicit usage of property interpolator, the application code does not need to handle the UI threading issues (making sure that the TextView.setTextColor is called on the matching UI thread).
If you’re interesting in using Trident in your Android apps, take the latest Trident 1.2dev (code named Cookie Jar) and add it to your Android project. The project documentation describes the basic terminology of Trident, and will provide more Android-specific examples in the next few weeks.
