In designing JavaFX 2.0, we of course needed to address both how the scene graph would behave in the presence of multiple threads, and how developers could effectively do work in background threads and keep the UI responsive. In short, the JavaFX scene graph, like all other mainstream GUI toolkits, is not thread-safe and must be accessed and manipulated from the UI thread (call the FX Application thread). Swing and AWT had the same basic policy (only work with Swing or AWT from the Event Dispatching Thread), as did SWT (only interact with SWT resources and components from the thread that owns them), as do all other major toolkits (JavaScript / HTML included).

The most common problem with this design is that developers who do not do work on background threads invariably create unresponsive applications, since this long lived (potentially blocking) code happens on the same thread that processes user events. That is, while your long lived operation is running, no mouse or key events are being processed, which leads to an application that appears to “hang”.

Further, actually writing well behaved background workers is difficult and error prone. Even if you create a Runnable and create a Thread and do your long-lived work in that background thread, at some point you need to communicate back to the UI, either with the result of the long-lived computation, or by communicating to a ProgressIndicator of some kind what the progress of this long-lived operation is. This is error prone, because you must be sure to communicate with the UI by putting events back onto the event queue (using Platform.runLater, the equivalent of Swing’s invokeLater).

Note: This article is a sneak peek at a new API which is coming in the next couple of weeks, but is not currently available in the Beta builds! There is a deprecated Task class in the beta builds which will be removed and replaced with the one detailed here.

Suppose we have a simple background thread which just counts from 0 to 1 million. Suppose I have a single ProgressBar, and that I need to update the progress of this ProgressBar as the counter runs. A naive implementation might look like this:

final ProgressBar bar = new ProgressBar();
new Thread(new Runnable() {
    @Override public void run() {
        for (int i=1; i<=1000000; i++) {
            final int counter = i;
            Platform.runLater(new Runnable() {
                @Override public void run() {
                    bar.setProgress(counter/1000000.0);
                }
            });
        }
    }
}).start();

This is a hideous hunk of code, a crime against nature (and programming in general). First, you’ll lose brain cells just looking at this double nesting of Runnables. Second, it is going to swamp the event queue with little Runnables — a million of them in fact. Clearly, we needed some API to make it easier to write background workers which then communicate back with the UI.

Java comes with a very complete set of concurrency libraries in the java.util.concurrent package. We wanted to leverage what was already defined in Java, but we needed to extend these APIs to take into account the FX Application thread and the constraints that GUI programmers are under. The javafx.concurrent package contains three core files: Worker, Task, and Service.

Before diving into the rather verbose description (taken from the proposed javadocs) for Worker, Task, and Service I wanted to cut to the chase and show some examples. The first key thing to mention, is that Worker is an interface that is implemented by both Task and Service, and which adds the sort of convenience API necessary for a background worker that is useful for communicating back with a UI. Second, Task extends from java.util.concurrent.FutureTask. This means that a Task can very cleanly fit into the concurrent libraries. As you may know, FutureTask implements Runnable, and can be passed to an Executor’s execute() method.

So real quick, here is the same example as above, but it suffers from none of the flaws exhibited in the naive implementation.

Task task = new Task<Void>() {
    @Override public Void run() {
        static final int max = 1000000;
        for (int i=1; i<=max; i++) {
            updateProgress(i, max);
        }
        return null;
    }
};
ProgressBar bar = new ProgressBar();
bar.progressProperty().bind(task.progressProperty());
new Thread(task).start();

In this example, I first create my Task. The task implementation just does its work, invoking the protected updateProgress method defined on Task, which ends up updating progress, totalWork, and workDone properties on the Task. I then create my ProgressBar and bind its progress property with the progress property of the Task. Then, since Task is a Runnable, I can just create a new Thread passing it the Task and then start the Thread.

Alternatively, I could create an Executor or ExecutorService (such as a ThreadPoolExecutorService) and execute the task using the ExecutorService.

Edit July 11, 2011: I have updated the API slightly since this post was originally written, and I’ve updated the post to reflect the current names. In particular, the “progress” property is now a value between 0 and 1 (or -1), matching the “progress” property on ProgressIndicator and other parts of the platform. “workDone” and “totalWork” are used to indicate the total units of work to do (such as bytes to be downloaded) and the total units of work that have been done (such as the bytes that have been downloaded). I’m not totally jazzed by the names, but felt it was important for “progress” to mean the same thing on Worker and ProgressIndicator.

Below are some further descriptions taken from the javadocs.

Worker

A Worker is an object which performs some work in one or more background threads, and who’s state is observable and available to JavaFX applications and is usable from the main JavaFX Application thread. This interface is primarily implemented by both Task and Service, providing a common API among both classes which makes it easier for libraries and frameworks to write user interfaces with observable workers.

A Worker may, or may not be reusable, depending on the implementation. A Task, for example, is not reusable while a @link Service is.

A Worker has a well defined life cycle. Every Worker begins in the READY state. When the Worker has been scheduled for work (for example, when a Service’s start() method is called), it is transitioned to SCHEDULED. Even Workers which are not technically scheduled, but started immediately (such as with Task#run()) will transition through SCHEDULED on its way to the RUNNING state.

When the Worker is actually performing its work, the state will have been transitioned to RUNNING. If the Worker completes normally, it will end in the SUCCEEDED state, and the result of the Worker will be set as the value property. If however an Exception occurs during the execution of the Worker, then the state will be set to FAILED and the exception property will be set to the Exception which occurred.

At any time prior to the conclusion of the Worker (that is, if the state is not already SUCCEEDED or FAILED) the developer may invoke the Worker#cancel() method. If called, the Worker will cease execution (if possible, including use of Thread.interrupt) and the state changed to CANCELLED.

The only valid beginning state for a Worker is READY, and the valid ending states are CANCELLED, SUCCEEDED, and FAILED. The running property is set to true when the state is either SCHEDULED or RUNNING.

The Worker’s progress can be monitored via three different properties, workDone, totalWork, and progress. These properties are set by the actual implementation of the Worker interface, but can be observed by anybody. The workDone is a number between -1 (meaning indeterminate progress) and totalWork, inclusive. When workDone == totalWork the progress will be 100% (or 1). totalWork will be a number between -1 and Long.MAX_VALUE, inclusive. The progress will be either -1 (meaning indeterminate), or a value between 0 and 1, inclusive, representing 0% through 100%.

A Worker which is in the READY or SCHEDULED states will always have workDone and progress set to -1. A Worker which is in the SUCCEEDED state will always have workDone == totalWork and progress == 1 or -1. In any other state, the values for these properties may be any value in their respective valid ranges.

Task

A fully observable implementation of a FutureTask. Tasks exposes additional state and observable properties useful for programming asynchronous tasks in JavaFX, as defined in the Worker interface. An implementation of Task must override the Task#call() method. This method is invoked on the background thread. Any state which is used in this method must be safe to read and write from a background thread. For example, manipulating a live scene graph from this method is unsafe and will result in runtime exceptions.

Tasks are flexibly and extremely useful for the encapsulation of work. Because Service is designed to execute a Task, any Tasks defined by the application or library code can easily be used with a Service. Likewise, since Task extends from FutureTask, it is very easy and natural to use a Task with the java concurrency java.util.concurrent.Executor API. Finally, since a Task is Runnable, you can also call it directly (by invoking the Task#run() method) from another background thread. This allows for composition of work.

Although java.util.concurrent.ExecutorService defines several methods which take a Runnable, you should generally limit yourself to using the execute method inherited from java.util.concurrent.Executor.

As with FutureTask, a Task is a one-shot class and cannot be reused. See Service for a reusable Worker.

Because the Task is designed for use with JavaFX GUI applications, it ensures that every change to the public properites, as well as change notifications for state, errors, and for event handlers, all occur on the main JavaFX application thread. Accessing these properties from a background thread will result in runtime exceptions being raised.

Service

A Service is a non-visual component encapsulating the information required to perform some work on one or more background threads. As part of the JavaFX UI library, the Service knows about the JavaFX Application thread and is designed to alieviate the application developer from the burden of manging multithreaded code that interacts with the user interface. As such, all of the methods and state on the Service are intended to be invoked exclusively from the JavaFX Application thread.

Service implements {@link Worker}. As such, you can observe the state of the background operation and optionally cancel it. Service is a reusable Worker, meaning that it can be reset and restarted. Due to this, a Service can be constructed declarativley and restarted on demand.

If an java.util.concurrent.Executor is specified on the Service, then it will be used to actually execute the background worker. Otherwise, a daemon thread will be created and executed. If you wish to create non-daemon threads, then specify a custom Executor (for example, you could use a ThreadPoolExecutor).

Because a Service is intended to simplify declarative use cases, subclasses should expose as properties the input parameters to the work to be done. For example, suppose I wanted to write a Service which read the first line from any URL and returned it as a String. Such a Service might be defined, such that it had a single property, url. It might be implemented as:

public class FirstLineService extends Service {
    private StringProperty url = new StringProperty();
    public final void setUrl(String value) { url.set(value); }
    public final String getUrl() { return url.get(); }
    public final StringProperty urlProperty() { return url; }

    protected Task createTask() {
        final String _url = getUrl();
        return new Task<InputStream>() {
            protected String call() {
                URL u = new URL(_url);
                BufferedReader in = new BufferedReader(
                        new InputStreamReader(u.openStream()));
                String result = in.readLine();
                in.close();
                return result;
            }
        }
    }
 }

Conclusion

We anticipate that libraries of Tasks, both specialized for your specific application and also general libraries of Tasks will be developed over time that perform common operations such as downloading files, performing HTTP form submits, copying files, uploading files, sorting, doing statistical analysis, and so forth. These reusable bodies of code can then be combined together, used with thread pools or other rich executor services, and used with Services.

Let us know what you think!

The ListView and TreeView controls support a huge number of items, but the ‘cost’ of having the control actually visually represented is only what you see on screen. Of course, there is also the cost of simply having the data lying around (which is not really in the domain of the control to handle – needless to say – be smart ). In other words, we are very smart about not creating nodes for list items that aren’t actually visible, and about updating the cell content based on user interactions such as scrolling and keyboard navigation. Also, each cell is reused, rather than being created and thrown away as necessary for each individual item in the ListView.

Of course, the other part of our job is to make easy to use API’s, so we’ve worked hard on this aspect as well. By default when you put an item into a ListView, we create a simple String-based cell that shows the text in the cell when necessary. In other words, if all you’re wanting is the same output as what you saw in JavaFX 1.2, you don’t need to change anything. On the other hand, if you want a more fancy ListView, that is where the concept of a cell factory comes into play. You can see a cell factory on a ListView control, and then whenever the ListView needs to update (because the visible items change), the cellFactory is consulted and you’re responsible for populating the cell as appropriate.

Prior to showing off the code, it would be useful to quickly summarize our key design goals, so that you’ll hopefully better understand why we did things the way we did. Our goals were the following:

• Both time and memory efficient for large data sets
• Easy to build and use libraries for custom cells
• Easy to customize cell visuals
• Easy to customize display formatting (12.34 as $12.34 or 1234% etc)
• Easy to extend for custom visuals
• Easy to have “panels” of data for the visuals
• Easy to animate the cell size or other properties

Right, now definitely seems like a good time to actually show off some code. As a first example, if I were to create a custom cell which formatted numbers such that they would appear as currency types, I might do so like this:

import javafx.scene.control.*;

ListView {
    items: [1.23, 3.33, 4.83, 5.32, 6.32]
    cellFactory: function() {
        def cell:ListCell = ListCell {
            node: Label {
                text: bind if (cell.empty) then "" else "${%(,.2f cell.item as Number}"
            }
        }
    }
}

In this example the cellFactory is a simple function which returns a ListCell who’s node content is a Label. The text of that Label is bound to the cell’s item. Whenever the item associated with a Cell is changed (which might happen if the user scrolls and the cell is reused to represent some different item in the ListView), then the Label’s text is automatically updated. In addition, if the cell is “empty” (meaning it is used to fill out space in the ListView but doesn’t have any data associated with it), then we just use the empty String.

Cell factories are really very powerful. The custom cells that are created can be anything from simple strings to full blown panels with movies and any other arbitrary content. They can change their size dynamically, and they can be styled easily from CSS.

We make it extraordinarily simple in JavaFX to change the color of cells. Each cell can be styled directly from CSS. So for example, if you wanted to change the default background of cells in a ListView to be a bit more interesting you could do the following CSS:

.list-cell {
   -fx-padding: 3 3 3 3;
   -fx-background-color: honeydew;
}

If you run an application with this style, you will notice that not all cells use this new color, only half of them. The other half (as it turns out, the odd numbered rows) are styled by a different rule in CSS which also needs to be specified:

.list-cell:odd {
    -fx-background-color: mistyrose;
}

Yikes! Looks like a crazy pair of socks. Clearly Jasper was not involved in picking the colors for this posting

If you wanted to set the color of selected ListView cells to be yellow, you could add this to your CSS file (yikes, the result is truly fearsome!):

.list-cell:filled:selected:focused, .list-cell:filled:selected {
    -fx-background-color: yellow;
    -fx-text-fill: black;
}

Each of these examples require no code changes. Simply update your CSS file to alter the colors. You can also use the “hover” and other pseudoclasses in CSS the same as with other controls.

Suppose you had a sequence of Numbers to display in a ListView and wanted to color all of the negative values red and all positive or 0 values black. One way to achieve this is with a custom cellFactory which changes the styleClass of the Cell based on whether the value is negative or positive:

import javafx.scene.control.*;

ListView {
    items: [1.23, -3.33, -4.83, 5.32, -6.32]
    cellFactory: function() {
        def cell:ListCell = ListCell {
            styleClass: bind if ((cell.item as Number) < 0) then "negative" else "list-cell"
            node: Label { text: bind if (cell.empty) then "" else "{cell.item}" }
        }
    }
}

You would then update the CSS file so that the text-fill of anything with a styleClass equal to “negative” would use red:

.negative {
    -fx-text-fill: red
}

There is one problem with this solution in JavaFX 1.3 however, which is that we currently only support a single style class, whereas in HTML CSS multiple style classes are supported. We’re working hard on fixing this limitation. In the meantime, you will need to copy a chunk of the default caspian stylesheet for your “negative” class for this to work properly:

.negative {
    -fx-text-fill: red;
    -fx-cell-size: 24;
    -fx-padding: 3;
    -fx-background-color: -fx-control-inner-background;
}

.negative:focused {
    -fx-background-insets: 0, 1.4;
    -fx-background-color: -fx-focus-color, -fx-control-inner-background;
}

.negative:odd {
    -fx-background-color: derive(-fx-control-inner-background,-5%);
}

.negative:focused:odd {
    -fx-background-insets: 0, 1.4;
    -fx-background-color: -fx-focus-color, derive(-fx-control-inner-background,-5%);
}

.negative:filled:selected:focused, .negative:filled:selected {
    -fx-background: -fx-accent;
    -fx-background-color: -fx-selection-bar;
    -fx-text-fill: -fx-selection-bar-text;

}

Cell Factories
Although the code necessary for creating cell factories is relatively terse, it is also repetitive boilerplate that could be (and should be) handled by libraries. For example, you could provide static functions which create various standard ListCell factories:

import javafx.scene.control.*;

function currencyCellFactory():ListCell {
    def cell:ListCell = ListCell {
        node: Label { text: bind if (cell.empty) then "" else "${%(,.2f cell.item as Number}" }
    }
}

ListView {
    items: [1.23, 5.23, 4.44, 5.93, 1.34, 33.23]
    cellFactory: currencyCellFactory
}

Or the following example might be used to generate a cell factory which can format dates according to some specified format String:

import javafx.scene.control.*;

function dateCellFactory(format:String):ListCell {
    // ... exercise left to the reader
    ListCell { }
}

ListView {
    items: [date1, date2, date3, date4]
    cellFactory: dateCellFactory("%tF")
}

There are times when you may wish to create much more elaborate factories based on many different parameters. One approach is to create a class which represents the state of the factory, and which has one or more factory functions on it. For example, I might write the following class:

 public class MyCellFactory {
     public var format:String;
     public function listCellFactory():ListCell {
         ...
     }
     public function treeCellFactory():TreeCell {
         ...
     }
}

And then when creating my ListView or TreeView, I could instantiate an instance of MyCellFactory and then link to the appropriate cellFactory function defined on that class:

 ListView {
     items: [1.23, 3.24, 5.32]
     cellFactory: MyCellFactory { format: "%(,.2f" }.listCellFactory
 }

In this way the parameters, functions, state, and so forth associated with the custom cell factories can be grouped together in a sensible way.

Building a panel of data
Since the content node of a Cell may be any node type, it is possible to build up more complicated Cell content than a single text string. For example, suppose you wanted to produce a ListView that was composed of a Label and a Button. Suppose each of these cells represents a Job object in your application’s domain model. Perhaps clicking the button is supposed to start a Job. You might build the cell like this:

ListView {
    items: bind jobs
    cellFactory: function() {
        def cell:ListCell = ListCell {
            node: HBox {
                spacing: 7
                content: [
                    Label { text: bind if (cell.empty) then "" else "{(cell.item as Job).title}" }
                    Button {
                        text: "Start"
                        visible: bind cell.selected and not cell.empty
                        action: function() {
                            def job = cell.item as Job;
                            job.start();
                        }
                    }
                ]
            }
        }
    }
}

When the Cell is selected, the visible attribute of the Button changes to true and you can see the button. Click on the button and it will start the Job. You can create arbitrarily complicated Cells in this manner.

These are just a few of the many interesting things that can be done with the ListView control in JavaFX 1.3. We’ll have additional blog posts in the near future showing in more detail some specific tricks (such as how to make a cell change size dynamically, and some more Jasper-approved visual design tweaks to make ListView really stand out).

In the meantime, here’s a call to action for all you experts out there doing library work (hint hint, Stephen and Dean). I’m excited to see what kind of cool libraries of cell factories can be built to make the ListView control really sweet to use!

One such idiom has to do with encapsulation. I was presented with the following problem in a recent email. The developer wanted to create a chunk of scenegraph which looked differently depending on some flag. There would be 10 such flags with 10 such chunks of scenegraph. In essence here is what the raw code would look like:

def imgPending = Image { url: "..." }
def imgDone = Image { url: "..." }

var flag1 = false;
var flag2 = false;
var flag3 = false;
// ... and so on

var group = Group {
    content: [
        HBox {
            content: [
                Text { content: "Item 1" }
                ImageView { image: bind if (flag1) then imgPending else imgDone }
            ]
        }
        HBox {
            content: [
                Text { content: "Item 2" }
                ImageView { image: bind if (flag2) then imgPending else imgDone }
            ]
        }
        HBox {
            content: [
                Text { content: "Item 3" }
                ImageView { image: bind if (flag3) then imgPending else imgDone }
            ]
        }
        // ... and so on
    ]
}

So for each flag we’re creating a different HBox with a Label and ImageView. The ImageView shows a different image based on the flag. Clearly the code as written is simple enough but really verbose. It is ripe for copy/paste errors and makes maintenance painful. What can we do about it?

In JavaFX, the best way to encapsulate a chunk of scenegraph such as this is to create a CustomNode. In JavaFX 1.3 you also have the option of extending directly from Parent. For the sake of this article, I’ll stick with the 1.2 approach (which still works in 1.3) and extend from CustomNode.

Unlike a Group, CustomNode is a Parent node who’s content is private. This gives you a nice way to encapsulate some chunk of scenegraph and provide a nice clean API to it without having to expose to everybody the actual details of that private chunk of scenegraph. The other benefit to this form of encapsulation is that it helps to clean up your source code by breaking it up into logical chunks.

Here is the reworked example using proper encapsulation:

// in Indicator.fx
def imgPending = Image { url: "..." }
def imgDone = Image { url: "..." }

public class Indicator extends CustomNode {
    public var text:String;
    public var done:Boolean;

    override function create() {
        HBox {
            content: [
                Label { content: bind text }
                ImageView { image: bind if(not done) then imgPending else imgDone }
            ]
        }
    }
}

// in Main.fx
var flag1 = false;
var flag2 = false;
var flag3 = false;
// ... and so on

var group = Group {
    content: [
        Indicator { text: "Item 1", done: bind flag1 }
        Indicator { text: "Item 2", done: bind flag2 }
        Indicator { text: "Item 3", done: bind flag3 }
        // ... and so on
    ]
}

In my earlier post on this topic I hinted that we had found a resolution to the issue surrounding the warning message, I hinted further in some of my replies to comments, and I even left it as sort of a cliffhanger as to what the resolution was. So, here’s the resolution.

We’ve decided that when a node is added to a group, that node is automatically removed from the group that previously owned it, if any. (Let’s call this the “auto-remove” feature.) We’ve also decided to turn off the warning message by default, but to have it be enabled optionally, possibly via a system property, for debugging purposes. Finally, we’ve relaxed the enforcement of some scene graph invariants in cases where the group’s content sequence is bound.

…

During the development of our current release, we kept running into this issue. A couple of us wrote code that we thought was reasonable, yet it surprised us when the warning message came out! We had a few hallway conversations from time to time, but a clear-cut answer never emerged. Finally, we realized that we had to get the interested parties in a room and have a knock-down, drag-out meeting to resolve the issue. And so on October 7, 2009, Amy Fowler, Kevin Rushforth, Richard Bair, and I got into a conference room to decide the issue. Three hours later — with no breaks! — we had decided. Actually, it was a great meeting, without a lot of conflict. There were just a lot of issues to cover. Each of us came into the meeting with our initial opinions, but the issues were so close that I think each one of us switched sides at least once during the meeting.

This lookup function currently only operates over the “public” or “logical” scenegraph, not the physical one. For example, a Button is a Control which delegates its visuals to its Skin. The Skin has a sub-scenegraph. But since we typically want to encapsulate all that, we hide it from the programmer such that most things don’t find this part of the scenegraph. Seems like a reasonable thing to do (Swing went the other way and all the gory details were public which led to issues sometimes where people would dig around and rely on internal details — the horror! — and this made it incredibly difficult to fix bugs later in Swing).

CustomNode was our level of encapsulation. Any CustomNode’s children was explicitly not part of the public API. However, a number of people have complained, likely because they aren’t using CustomNode for encapsulation but rather for modularization of their source code (ie: break a huge file into several files where each piece extended from CustomNode).

So it seems like this partitioning of “logical” and “physical” scenegraphs is quite confusing at times. So the question is, should the lookup function operate on the physical scenegraph? Vote!

var g = bind Group {
    translateX: someX
    content: node
}

In this code, whenever “someX” changes, a new Group is created and the node is mysteriously moved from this Group to the new one, and in the process the “infernal scenegraph warning message” is printed. Stuart goes into a lot of great history and detail to give context to the problem, but here is probably the money-quote as to why the warning message was useful:

When we added the enforcement code, we were surprised that it uncovered a few bugs and quite a number of questionable coding practices in our code, both in our runtime library and in our samples. In one case a node from the scene graph was also being used as a clip. This was illegal and didn’t actually work, but nobody had noticed up to that point. As for questionable coding practices, the enforcement turned up quite a number of cases where a scene graph was being constructed with some initial structure, and some code later on would rearrange the nodes into a different structure for no good reason. This caused the scene graph machinery to do a lot of extra work. The fix was to rewrite the code to create the scene graph in the desired structure, avoiding the rearranging and any error messages that the old code had caused.

Go visit his blog to get more information, I’m waiting for the second installment which I anticipate will go into all the nitty gritty details. Its kind of a cliff hanger because he doesn’t tell you what the final unanimous decision was regarding the warning message. Codify it as an error? Remove it? Something else?

Having spent several weeks on this problem during the Spring and Summer of this year, the blog on how Silverlight is addressing the issue I found very interesting. It’s fun for me as a developer to see my counterparts in other toolkits wrestling with the same issues and coming to many of the same conclusions. In this case I think we have a stronger solution. I’m going to do a little compare and contrast not in the spirit of competition but rather just to describe what we’re doing.

In the 1.2 release of JavaFX we released the ListView (our equivalent of ListBox in WPF/Silverlight or JList in Swing). The ListView wasn’t very customizable. Each list item would only display the “toString” of the associated data item. However, the guts of the ListView were very complex to support UI Virtualization. Following JavaOne I completely rewrote the Control. The current implementation (still being finalized by some great engineers on the UI Controls team) now exposes API for allowing you to completely customize each cell while also being very efficient in terms of handling very large lists.

During the refactoring I created a (currently private) class called VirtualizedFlow which handles most of the dirty work. I found reading the Silverlight blog linked to above that WPF has a similar class, called VirtualizingStackPanel. It’s always fun to see how other people address the same problem, and a lot of fun when you find out you came to the same conclusions.

WPF has supported UI virtualization for a long time. The ListBox and ListView controls use VirtualizingStackPanel as their default panel, and VSP knows to create UI containers (ListBoxItems or ListViewItems) when new items are about to be shown in the UI, and to discard those containers when items are scrolled out of view.

This is a good start, but actually not good enough. Another feature I built into ListView from the start (1.2 release) was the notion of recycling the cells used. In the Silverlight blog, it is mentioned that .NET 3.5 SP1 also supports this:

.NET 3.5 SP1 supports the reuse of UI containers already in memory. For example, imagine that when a ListBox is loaded, 30 ListBoxItems are created to display the visible data. When the user scrolls the ListBox, instead of discarding ListBoxItems that scroll out of view and creating new ones for the data items that scroll into view, WPF reuses the existing ListBoxItems. This results in significant performance improvements compared to previous versions because it decreases the time spent initializing ListBoxItems. And since garbage collection is not instantaneous, it also reduces the number of ListBoxItems in memory at one time.

However, unlike .NET which requires you to take a separate step to enable recycling, we do it always and for free. The JavaFX API is designed such that it is a natural part of how the system works. When designing the JavaFX API, I wanted to avoid some of the odd corner cases that came out of Swing’s cell renderer concept, but keep the insane scalability. I think we’ve managed that. It is a little more complicated than the simple naive approach of creating a new Cell for every item, but not by much.

The basic concept in JavaFX revolves around the concept of a Cell (which is a Node). Cells are used to display data items in a ListView (and in the future, a TreeView and TableView and TreeTableView, etc). Each Cell represents a data item, though which data item is represented may change over time. For example, suppose I had the following ListView:

ListView {
    items: [1..1000]
}

This ListView will display the numbers 1 through 1000. Initially, enough Cells will be created to display each visible row. So you may have a Cell which will represent data item “1″, and another which represents data item “2″, and so forth maybe up to “10″. If the user then scrolls, then we will attempt to reuse Cells. So the Cell which used to represent “1″ now represents “33″.

When you look at the Cell API this is apparent:

public class Cell extends CustomNode, Resizable {
    /**
     * The data value associated with this Cell. This value is set by the
     * multiviewed Control when the Cell is created or updated. This represents
     * the raw data value.
     */
    public var item:Object;

    /**
     * Indicates whether or not this cell has been selected.
     */
    public var selected:Boolean;

    /**
     * Called by the system whenever the state of the Cell has been updated.
     */
    public var onUpdate:function():Void;

    /**
     * A container for the nodes that represent the content of this cell. Since
     * Cells must be resized to fit within some space, and since their preferred
     * sizes are important for determining the size of a cell, a Container of
     * some kind is required as the root of the content for the cell.
     */
    public var node:Node;

    /**
     * The container for the nodes used to represent the background of the cell.
     * If this is left empty, then the Skin for the Control is responsible for
     * creating a default background, if it so chooses. In this way, custom
     * cells can be created that define both the content and background, or that
     * define only the content with the background being provided by the skin.
     */
    public var background:Node;
}

As you can see in this API, each Cell has an item and the item can change over time. The Cell also has a node which represents the cell’s body, as well as a background which is typically used for rendering selection and so forth and if left null will be supplied by the ListView skin implementation. So to create a custom Cell, all you would need to do is provide the node, and wire it up (bind it) to the item. The system then will reuse Cells, simply updating the item over time as the Cell represents something different, and the bindings will then update the node. There is also a procedural approach where we invoke an onUpdate function variable, which allows the Cell author to respond procedurally if it makes more sense (for example, when working with FXD content exported from the JavaFX Production Suite this might make sense).

The last part of the puzzle is some way for the system to create your custom Cell whenever it needs a new one (which it pools up itself). This is actually very trivially done by exposing a function variable callback on ListView which allows you to create and return a new Cell. In this way you can create custom Cells for representing data richly in your JavaFX apps.

ListView {
    items: [1..1000]
    cellFactory: function():ListCell {
        ListCell {
            node: Panel { ... }
        }
    }
}

Since cell factories are simple functions, it is also easy to create shared libraries of static functions which return your own implementations and reuse them across your application. You can also subclass ListCell with your own custom implementations so as to reuse them across your application.

There is one last thing that JavaFX does that I think is quite unique (from the blog it doesn’t look like Silverlight supports it, and I don’t think Flex does, however Android might I’m not sure). First I’ll quote from the Silverlight blog as to the problem:

Currently WPF supports UI virtualization only when scrolling by item. Pixel-based scrolling is also called “physical scrolling” and item-based scrolling is also called “logical scrolling”.
[...]
I’m often asked if there is a way to work around this limitation. Well, anything is possible, but there is no *easy* workaround. You would have to re-implement significant portions of the current virtualization logic to combine pixel-based scrolling with UI virtualization. You would also have to solve some interesting problems that come with it. For example, how do you calculate the size of the thumb when the item containers have different heights? (Remember that you don’t know the height of the virtualized containers – you only know the height of the containers that are currently displayed.) You could assume an average based on the heights you do know, or you could keep a list with the item heights as items are brought into memory (which would increase accuracy of the thumb size as the user interacts with the control). You could also decide that pixel-based scrolling only works with items that are of the same height – this would simplify the solution. So, yes, you could come up with a solution to work around this limitation, but it’s not trivial.

We have the exact same problem space — we support non-homogenous row heights, potentially incredibly large numbers of items, and scrolling. This presents some really interesting problems. We have a solution to this problem which for typical ListView’s combines pixel scrolling with position (or item) scrolling in a way that the user cannot detect that we’re doing anything special behind the scenes. You can “pan” the list by using the mouse and it looks like pixel scrolling, or move by items using the keyboard and it looks like item scrolling or drag the scrollbar and you won’t know if you are pixel scrolling or item scrolling (except in some very, very edge cases) or you can click the “up” and “down” arrows on the scrollbar and get pixel scrolling. We’re still working on the thumb size problem which I think will turn out to be some heuristic that adjusts the thumb size as it finds out more information on the size of the list (typically for large lists you can assume it needs to be the min size, while on small lists you might just create enough cells to get a reasonably accurate thumb. It only goes awry if you have whacked out differences in cell heights).

So since I want to close out the optimization issue report, I decided to write this blog detailing what we’re planning on doing. Each of our multi-valued controls (list, tree, table, etc) will use the same base Cell API (unlike TreeCellRenderer, TableCellRenderer, ListCellRenderer which were all different in some annoying ways). They’ll all support UI virtualization. Initially we won’t support “model virtualization” (ala TableModel, ListModel, TreeModel) though that will be coming in a future release.

When a Control is created, if you do not explicitly specify its width or height, then it is sized according to its preferred width and/or preferred height. If you use a Control within a layout Container (which was anticipated as being the common case) then you (almost) never explicitly manage its dimensions – you leave that chore to the Container. However, if you do not use a Control within a layout Container (which turns out seems to happen quite a bit) then it does not explicitly resize itself whenever, say, columns changes.

Take Button as another example. If you create a Button with the text “OK” and do not specify a width or height, then the Button will be initialized to its preferred size. However, if you then change the text of the Button to be “Cancel”, then the Button will not automatically resize, and will therefore not be wide enough to display all the text and you’ll see something like “C…”, if you’re lucky. Or “…” if you’re not.

I’ve filed RFE http://javafx-jira.kenai.com/browse/RT-5122 targeted at the next release. The idea here is to have an “autoSize” variable on Control which will be true by default. Problem solved, right? Well, not quite. The problem with autoSize is that when placed in a Container, the Control should not attempt to resize itself. So we’ll end up with code essentially like this:

if (autoSize and not (parent instanceof Container)) {
    // resize the width because the text has changed, or whatnot
}

Not very pretty. But given the options and the amount of frustration it is causing developers, I’m willing to accept that bit of nastiness. What do you think? Have any good ideas? Leave comments & votes on the bug if you like!

It’s great to see a lot of people starting to play with this part of the JavaFX space because we haven’t really given much guidance to it yet. We do have some great web service APIs as a starting point (basic HTTP with HttpRequest, RSS and ATOM feed support), but haven’t so far given any guidance as to writing an end to end app. I wanted to take just a moment and outline how we designed the Task API and how it ought to be used by third parties when creating background tasks or services, including communicating with a server.

I also wanted to give a shout out to an excellent blog by my colleague Baechul who has been writing some very detailed and well written articles on JavaFX. Of particular interest to this post is one he wrote on JavaFX 1.2 Async.

The Task class in the javafx.async represents the basic programming model for all asynchronous tasks in JavaFX and should form the base class for all such background Tasks. Its design was heavily influenced by the excellent work of Hans Muller on the Swing Application Framework. All JavaFX Tasks have the notion of “state” and “progress”. The state of the Task is expressed though a series of public API members:

• started:Boolean
• stopped:Boolean
• failed:Boolean
• succeeded:Boolean
• done:Boolean

We chose to break these states out into Boolean properties rather than have a single property with an enum for two reasons. First, it makes it a little cleaner in the onDone event handler to find out what state the Task ended up in, especially when checking for several states. Second, this allows you to bind to the state of the Task from an external class using some rather clean code. For example, suppose you had a progress indicator and error icon and wanted to make it so that if the task failed, the error icon would be made visible, otherwise the progress indicator would be visible and display progress appropriately.

Group {
    content: [
        ProgressIndicator {
            visible: bind task.started and not task.failed and not task.stopped
            progress: bind task.percentDone
        }
        ErrorIndicator { // this class doesn't exist, but you could write a CustomNode
            visible: bind task.started and task.failed
            causeOfFailure: bind task.causeOfFailure
        }
    ]
}

You’ll notice in this code block I’m also taking advantage of another really nice feature of Task and ProgressIndicator. A ProgressIndicator has a progress property which, if -1, means it is indeterminate but if between 0 and 1 then it indicates the percent done. Task also has a similar property called percentDone where, if -1, it means that the progress of the Task is also indeterminate. This makes binding a ProgressIndicator to a Task very clean. Simply bind like this: ProgressIndicator { progress: bind task.percentDone } and the rest works exactly like it should (switching between determinate and indeterminate mode automatically).

There are several API members for tasks for tracking progress:

• progress
• maxProgress
• percentDone

To help explain these properties lets imagine that our Task was to read a file from disk. In this case, progress could be used to indicate the number of bytes read from disk. maxProgress would indicate the size of the file in bytes, and percentDone would be automatically calculated based on progress and maxProgress. In this way, you can create a UI which will track not only the percent done, but also the discrete amount of work to be done, and how much has been done.

Another simple example would be computing prime numbers. Suppose your app wanted to compute the first 5 prime numbers. In this case, maxProgress would be 5, and progress would be incremented each time a prime number is computed.

Finally, there are two event handlers that all Tasks share: onStart and onDone. onStart is called whenever the Task’s start() method is called, not when the background task is actually started. For example, your Task implementation might push work onto a worker queue. In this case, onStart should be called immediately after start() is invoked, not when the actual background worker that was pushed on the queue starts working.

The onDone function is called whenever the task stops, for any reason. If the task was cancelled manually, or if there was a failure, or if the task completed successfully. In all these cases onDone will be called. I’d like to add “onSuccess” and “onFailure” and “onStopped” events in the future. It is the developer’s responsibility in onDone to check the state of the Task to determine whether the task succeeded or failed or was stopped by checking the state booleans of the Task.

All background operations in JavaFX should extend from Task. This design gives application developers a single common programming model to use with all background operations developed by the JavaFX team or by third party developers. HttpRequest was refactored to be a Task in 1.2 (hence the reason for some of the API changes between 1.1 and 1.2).

There is one major caveat that I need to make clear. As of JavaFX 1.2, JavaFX Script is single threaded. All background work must be done in Java code. The JavaTaskBase abstract class is the base class intended to be used by all background threading implementations in JavaFX 1.2. Unfortunately, the hookup between JavaTaskBase and RunnableFuture didn’t come out right in 1.2 and you’re left with very little guidance as to how to do this appropriately.

The key thing is to understand that nothing should touch JavaFX variables from a background thread. So the idiom to use is to have the JavaTaskBase subclass to have a Java language peer which does the background work. The JavaTaskBase subclass would register a listener on the peer, and the peer would communicate back to the JavaTaskBase through that listener interface. The JavaTaskBase subclass would then pump events from the peer back onto the JavaFX thread (i.e. event thread) using FX.deferAction.

That’s a whole other blog entry though. For starters, I suggest reading Baechul’s take on it.

There is one last thing I wanted to mention, which is a futures item which Brian Goetz and I have been bouncing around a bit. It’s completely pie-in-the-sky at this point, take it with a grain of salt, etc etc. Having to write background tasks in Java is a pain at the moment primarily because you cannot create JavaFX objects in a background thread. Also, it involves writing a messaging interface, a Java class, and a JavaTaskBase subclass. What I’d like to see is something like this:

var task = BackgroundTask {
    run: function() {
        // code in this function runs in a background thread
        defer(function() {
            // code in this function runs on the JavaFX thread
        });
    }
}

The kicker is, the compiler would check and enforce that you don’t illegally modify application state from the background thread, but that you can when using “defer” or “deferAction”. The thing that gets me all excited about the idea is that we don’t have to expose a full threading model (with synchronicity, concurrent collections, memory barriers, semaphores, or anything else), but can instead simplify the problem by having a much more limited coarse grained approach of “this body of work happens in some background thread”. If you want or need to have a full threading model, then we still make that available by writing a JavaTaskBase subclass, but for the vast majority of uses, you could just use the simplified BackgroundTask model.

There are basically three different levels of support for skinning in JavaFX.

Levels of Skinning

At the most basic level, which is also the most powerful and flexible, you have the ability to completely replace the Skin for any Control. The Skin is responsible for the entire visual appearance and, ultimately, the visual interaction for a Control. There are not explicit “ButtonSkin” or “RadioButtonSkin” or “ListViewSkin” types that must be extended. There are simply Skins. So for example, you could completely replace the Skin for a Button using your own implementation that, for instance, simply used an image for the button.

While it is the most powerful mechanism for skinning a Control, it is also the most tedious as there are many details to pay attention to, such as overriding the functions to provide meaningful preferred size information for the Control with this Skin, wiring everything up to the model information in the Control, and handling all the mouse input and preferably forwarding the input on to a Behavior (which you also must providing in JavaFX 1.2 since the skin and behavior implementations for our default look, Caspian, have not been made public in this release).

The next level up restricts a bit what you can do, but also makes it a lot easier to style. This is to use the JavaFX Production Suite to produce skins for your Controls. As of the time of this writing, this support is still in prototype form (Martin Brehovsky demo’d this at JavaOne and it is definitely something I’d like to see released this year, but we’ll see how the schedules work out). The basic idea is pretty simple: the tool would provide its own basic Skin base classes. Vector or Image artwork produced by Illustrator or Photoshop and exported via the Production Suite could then get wired up on top of these Skin base classes to form a complete Skin for a Control.

There are several great things about this approach. First, visual designers can create nice graphics and use these directly. We lowly developer types don’t have to worry about taking a designer’s design and replicating it in code (which is good, ’cause mostly we’re lousy at it). Also, it opens up the opportunity to allow your company to contract out to designers and have them produce skins. It also allows designers to create suites of prebuilt custom skins fairly easily and sell these “themes” for the basic controls. Creating custom skins for custom controls is likewise also not terribly difficult for a designer.

However, as mentioned above, this isn’t released yet, so for the moment you would have to manually wire up the output of an FXD file to the skins. This is actually not very difficult, and could be achieved in a matter of an hour or so by somebody skilled at writing skins.

The third approach is to use CSS for styling the Controls. This is by far the most accessible method and, hopefully, will accommodate the 60-80% use case of simply wanting to style the prebuilt skins. In the 1.2 release, styling Controls with CSS is only just supported. In the next release we’ll both document and declare “stable” the attributes which can be styled from CSS. We’re pretty excited about the range of options we’re going to support, because our hope is that we’ll be able to address the vast majority of uses with just simple CSS.

And remember in JavaFX, CSS attributes can be specified in stylesheets, or directly on Nodes in the scenegraph by specifying the “style” property, much like in HTML. This makes it really easy to style a specific Control (which is a Node in the scenegraph) directly, or indirectly in a stylesheet.

In CSS you can easily specify attributes for a Control when it is in different states. For example, you can specify the a Button should have a base color of “red”, and a Button which has the mouse over it (hover) is “blue”. This is done by specifying the base and/or accent Color in CSS like this:

Button {
    style: "base: red"
    text: "Red Button"
}

There are a whole host of additional attributes which we’d like to expose in the next release, such as cornerRadius, padding, margins, shadowFill, textFill, and so forth (actually, I think we have committed to textFill already, I’ll let Jasper verify). One idea we’ve been kicking around is that of having a TexturePaint where, from CSS, you could specify an image file and also a set of insets and then we’d do the 9-square resizing technique for you. This would make it trivial then to build skins from CSS based on either Colors, Gradients, or Images. If we then expose some information for animations so you could control simple animation transitions from CSS too, then CSS becomes a very compelling proposition.

I hope this outline helps understand a bit better where we are now, and where we’re headed in the next release. Today, the best supported option is to create completely custom Skins. The second best option is to do some basic styling from CSS. In a few months time we plan to release complete CSS customizability which will give probably 80% use case coverage. We should also have basic support in the Production Suite to produce skins for Controls (though there may be some hand coding involved, we’ll try to make it pretty trivial).