Inside the JavaFX team, since times of yore (that is, since at least JavaFX 1.3, but perhaps earlier – my memory fails me here), we’ve had this remarkable little tool that was called Scenic View. It somehow just burst into existence, through the brilliance of Amy Fowler, whom many should know as the layout guru for both Swing and JavaFX. Scenic View is a tool that can be called to browse a live view of the application scenegraph. Here’s a screenshot:

The nice thing about Scenic View is that it can also display overlays in your user interface to indicate three things: the baselineOffset, the boundsInParent, and the layoutBounds. These let you very easily see why your user interface is the way it is. I’ve attached another screenshot below, which shows this. The third rectangle in has been selected in ScenicView, and as such has a yellow filled rectangle to indicate its boundsInParent, and a green dashed (and unfilled) rectangle to indicate the layoutBounds. The interesting thing to note is that despite the rectangle having been rotated, the layoutBounds still reflect the unrotated rectangle, and that this is what the layout containers use to lay out nodes. In other words, the rectangles on either side of the rotated rectangle make no allowance for the rotation (although there are ways to force this to happen if that is what you want – listen to Amy’s talk (linked below) to learn more).

Amy presented her Introduction to JavaFX layout talk at JavaOne San Francisco in October 2011, and I’ve gone on to re-present it at JavaOne conferences in Japan and India. What we covered in these talks was a whole bunch of layout fundamentals, and then we worked through how to use these fundamentals to build a JavaFX user interface. The worked example was on building aspects of the Scenic View application, and then we used the Scenic View application to demonstrate some of the layout concepts we had spoken about previously.

The Scenic View application shown above only differs visually from what Amy presented at JavaOne (which you can see in the link above). This is all I’ve done – the rest is all from Amy. What you can see in the image above is standard JavaFX, styled with a bit of custom CSS (borrowed heavily from Scene Builder). There are still a few visual quirks I’d like to improve, but I’ve been wanting to get this released for a very, very long time, so I’ll do that first, and then we can talk about improvements.

So, today, I am finally able to put up a jar file of the ScenicView application. Drop this into your project, and simply fire up Scenic View by calling ScenicView.show(scene) with the scene of your application. There is actually a secret shortcut that will automatically start up Scenic View from your running application, but that won’t stay around forever so I won’t publicise it (although it is in our open source code, so maybe you can find it)….

Please, leave comments, requests for functionality, and offers to add said functionality in the comments section below. I look forward to your feedback.

Original Code

Path path_4 = new Path();
ObservableList shape_4 = path_4.getElements();
shape_4.add(new MoveTo(50,50));
shape_4.add(new LineTo(150,50));
shape_4.add(new LineTo(150,150));
shape_4.add(new LineTo(50,150));
shape_4.add(new LineTo(50,50));
path_4.setStrokeWidth(2);
path_4.setStroke(Color.rgb(255,0,0));

So I hacked together a Extended version of the PathBuilder that ships with JavaFX 2.0 adding methods for all of the path elements like moveTo() etc. The end result seems much cleaner code to me, what do you think?

Code with new Builder

Path path4 = PathBuilderExtended.create()
        .moveTo(50, 50)
        .lineTo(150, 50)
        .lineTo(150, 150)
        .lineTo(50, 150)
        .closePath()
        .strokeWidth(2)
        .stroke(Color.RED)
        .build();

This seemed a lot cleaner and simpler to read. I have filed a feature request RT-19266 in JIRA to add this to the platform. Feel free to comment on the bug if you any feedback or better suggestions. Also I have attached a implementation of this builder to the bug so you can see how it would be implemented or use it with your code today.

As you may recall, it was October 2010, at JavaOne, where Oracle announced publicly that JavaFX was going to see a reboot. It was announced that JavaFX was to transition from the ‘JavaFX Script’ language to being built in Java. This decision was made inside Oracle only a month or two prior to the announcement, which led to a number of JavaOne sessions and BOFs being quickly cancelled and replaced to cover the new direction. At JavaOne 2010 the sessions were therefore discussing what was coming, rather than what was available in JavaFX 1.3.1 (which was the last release in the JavaFX 1.x line). I remember showing demonstrations of not much more than rectangles being drawn on screen, using what was then our Java APIs (but which permutated considerably during the course of development). This was the JavaFX 2.0 state of the art at the time, and we have come a long way since then!

Another vivid recollection I have from JavaOne 2010 is the various reactions that people had of this news. It varied from those in shock at losing their favourite language, to those who said it was long overdue and was the right way to proceed with JavaFX. I tried to ease people into this new approach by clarifying that, of course, now that JavaFX is in Java, many other JVM languages can come in to make developing JavaFX more enjoyable again, especially if developers were to write improved DSL extensions to these languages. Fortunately, exactly this has happened, with projects such as GroovyFX, ScalaFX, and of course, the JavaFX Script fork, Visage, coming in to simplify the development of rich JavaFX user interfaces.

Work continued apace in redeveloping JavaFX in Java through late 2010, and in early 2011 we begun to offer early access builds of JavaFX 2.0 to close partners. Despite the builds being made available to actual end-developers, API changes were happening at an incredibly rapid pace. I’m sure this led to great frustration (which is also why the builds were not more widely distributed). Internally, these major API changes were massively helped by our use of Lombok during the early prototype stages, as it allowed for us to create custom annotations to represent our properties, and simply update our Lombok code to recompile with a massively different API. As our API became more stable, we started to remove our dependency on Lombok, and today it is not used at all in our source code.

As development continued with JavaFX 2.0, we started to do something I was, and continue to be, very proud of – we started making pre-release builds available to the community. This let you, the consumers of the API, provide invaluable feedback to the developers. No one wins when ‘big bang’ releases are made without discussion, and frankly, the JavaFX community rock – whether it is in comments on blog posts, in the JavaFX forum, in the openjfx-dev mailing list, or in one-on-one emails sent to developers in the JavaFX team (it’s normally not hard to guess our @oracle.com email addresses!).

As JavaOne 2011 drew closer, JavaFX 2.0 was continuing to see refinement, with APIs being finalised, performance being improved, and bugs squashed. Unsurprisingly for most people, JavaFX 2.0 was released at JavaOne 2011. In addition to porting the JavaFX 1.3.1 source code to Java, JavaFX 2.0 also ships with a huge number of new features that were developed at the same time. I’m loathe to include a list, as I’m certain I’ll miss out plenty of cool stuff, but from my point of view as a controls team member, JavaFX 2.0 includes new API for properties, binding, collections, animation, new controls such as TreeView, TableView, ChoiceBox, Menus, SplitPane, TitledPane, HTMLEditor, and Accordion, improved layout APIs (including GridPane), the WebView component, and much more. In addition to the new API, JavaFX 2.0 ships as the first release to enable the brand new Prism graphics engine, as well as the new Glass framework for windowing and other native operating system integration. Of course, feel free to comment on your favourite new feature (especially if I missed it out)!

Perhaps the most controversial topic related to JavaFX was its lack of cross-platform support from the get-go – JavaFX 2.0 shipped as a Windows-only release. The uncertainty around what this meant led Richard (the newly crowned Java Client Architect) to blog about this in his ‘Is JavaFX 2.0 Cross Platform?‘ post. The general reasoning for this approach was that we could either make a tiered release plan (as we did), and get the Windows build out sooner, or hold back the release for a much longer time so that development of Windows, Mac OS, Linux, etc builds could all get up to the same level prior to release. We ended up doing the tiered release approach, as it meant we could get a solid Windows release out sooner, and focus on getting other platforms solid subsequently. I’m sure this upset people that wanted support for their preferred operating system from the start, but I’m also comfortable with the approach taken for the reason above.

Almost as soon as JavaFX 2.0 shipped, JavaFX 2.0.1 was released, as the JavaFX team jumped on the Java release train of alternating security and bug-fix releases. Because of this, JavaFX 2.0.1 shipped only a few weeks after JavaFX 2.0 did, with just a few security-related fixes. Very few engineers inside Oracle were involved in this release, with most focused on the forthcoming JavaFX 2.0.2 release instead.

JavaFX 2.0.2 was released to coincide with Java 7u2 (which JavaFX is co-bundled with) in early December. JavaFX 2.0.2 includes a huge number of bug fixes, optimisations, some new API, and an improved redistribution license. As mentioned, it was the first release following JavaFX 2.0 that features considerable development effort by all teams. For me it was an exciting release due to the huge number of bugs we were able to squash between JavaFX 2.0 going into code freeze (since about a month before JavaOne) and JavaFX 2.0.2 going into code freeze around early November.

Not content with this pace, JavaFX 2.1 early access builds were also announced in December. JavaFX 2.1 builds are available for Windows and Mac OS, allowing for the same JavaFX code to run on both operating systems without any changes necessary. The JavaFX 2.1 builds are intended to be weekly releases, and of course are not as production-ready as the JavaFX 2.0.2 release (but also not as exciting ). Already, people are exploring what is new in these builds, which as of JavaFX 2.1 build 06 includes a bunch of new collections API, a ComboBox control, new charts, and native DirectoryChooser support. There is also plenty more coming in JavaFX 2.1, but which has not hit a public release yet.

Aside from the amazing pace of releases containing bug fixes and new features, I can’t conclude this look back without mentioning the news that was announced at JavaOne 2011 that all of JavaFX will be open sourced. Already, the OpenJFX project exists, with the UI controls being available (and developed) in the open. Amazingly, the openjfx-dev mailing list, which opened up on December 1, has already had 442 posts in December, and there are 107 people already signed up to the list. The discussion is lively, and brings together community members and Oracle employees to discuss the future of the JavaFX API. Already there have been discussions on a range of topics, and your feedback is appreciated no end.

On a side note, FX Experience, the blog run by Richard, Jasper and I (Jonathan), also continues to grow at a nice pace. In 2009, FX Experience received 54,444 views, at an average of 259 views per day (for the seven months the site was running from June). In 2010, the average daily visitors was 326 people, which led us to have 118,926 visits in 2010. This year, with two days remaining, we grew the visitor numbers to average 530 views per day, resulting in 192,928 visits in the year. I’m very pleased at the growth this blog continues to see, and hope that it continues for the foreseeable future.

The top 12 posts this year were the following (ignoring the fact that this favours posts from earlier in the year):

1. JavaFX 2.0
2. Introducing FXML
3. Is JavaFX 2.0 Cross Platform?
4. Maps in JavaFX 2.0
5. JavaFX 2.0 Charts
6. Worker Threading in JavaFX 2.0
7. JavaFX 2.0 Beta is Available!
8. FXML: Why It Rocks, And The Next Phase
9. JavaFX links of the week, February 13
10. Simple 3D Cubes in JavaFX 2.0
11. SplitPane in JavaFX 2.0
12. FXML + Guice

Looking forward, the JavaFX roadmap was updated recently to detail our plans for JavaFX 2.1, 2.2 and 3.0. If you want to be more involved in these discussions, joining the openjfx-dev mailing list is the place to start. There are a number of exciting plans for next year, including full support for Mac OS and Linux, the JavaFX Scene Builder tool (for easily building user interfaces), as well as plenty of new features/API, and of course a huge number of bug fixes.

That’s all I can really recall for JavaFX this year. I’m sure I’ve forgotten more than I remember, but I hope that the insight into the year that has been has been interesting, and I hope you’re all enjoying using JavaFX. Next year stands to be another exciting year, so strap yourself in tight and hold on – it’s gonna be a fun ride!

In this code sample, the Table is an SWT table, but the chart is a JavaFX Chart. I create the data model and place it in an ObservableList, and supply this to both the table and the chart. As you edit the table, it ends up also directly manipulating the chart data model, which causes it to animate to the new value.

package swt.demo;
import javafx.collections.FXCollections;
import javafx.collections.ObservableList;
import javafx.embed.swt.FXCanvas;
import javafx.scene.Scene;
import javafx.scene.chart.BarChart;
import javafx.scene.chart.CategoryAxis;
import javafx.scene.chart.NumberAxis;
import javafx.util.Pair;
import org.eclipse.swt.SWT;
import org.eclipse.swt.custom.TableEditor;
import org.eclipse.swt.graphics.Point;
import org.eclipse.swt.graphics.Rectangle;
import org.eclipse.swt.layout.FillLayout;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Canvas;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Display;
import org.eclipse.swt.widgets.Event;
import org.eclipse.swt.widgets.Listener;
import org.eclipse.swt.widgets.Shell;
import org.eclipse.swt.widgets.TabFolder;
import org.eclipse.swt.widgets.TabItem;
import org.eclipse.swt.widgets.Table;
import org.eclipse.swt.widgets.TableColumn;
import org.eclipse.swt.widgets.TableItem;
import org.eclipse.swt.widgets.Text;

import com.sun.javafx.runtime.VersionInfo;

/**
*
* @author Richard
*/
public class SWTDemo {
   public static void main(String[] args) {
       Display display = new Display();
       Shell shell = new Shell(display);

       // Print version info
       System.out.println("SWT " +  SWT.getPlatform() + " " +  SWT.getVersion());
       String runtimeVersion = VersionInfo.getRuntimeVersion();
       System.out.println("FX " + runtimeVersion);

       shell.setLayout(new FillLayout());

       // Create the fake TabPane guy
       final TabFolder tabFolder = new TabFolder(shell, SWT.NONE);
       TabItem chartTab = new TabItem(tabFolder, SWT.NULL);
       chartTab.setText("JavaFX Chart and SWT Table");
       TabItem browserTab = new TabItem(tabFolder, SWT.NULL);
       browserTab.setText("Web Browser");

       Canvas canvas = new Canvas(tabFolder, SWT.NULL);
       GridLayout layout = new GridLayout(1, true);
       canvas.setLayout(layout);
       chartTab.setControl(canvas);

       // Create the data (I'll use the Chart's data model for
       // both the chart and the table)
       ObservableList<BarChart.Series> bcData = FXCollections.observableArrayList();
       bcData.add(createSeries(new Pair("2007", new Double(567)), new Pair("2008", new Double(956)), new Pair("2009", new Double(1154))));
       bcData.add(createSeries(new Pair("2007", new Double(1292)), new Pair("2008", new Double(1665)), new Pair("2009", new Double(1927))));
       bcData.add(createSeries(new Pair("2007", new Double(1292)), new Pair("2008", new Double(2559)), new Pair("2009", new Double(2774))));

       Canvas chart = createChart(canvas, bcData);
       chart.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
       Table table = createTable(canvas, bcData);
       table.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, false));
       createTableEditor(table);

       shell.pack();
       shell.open();
       while (!shell.isDisposed()) {
           if (!display.readAndDispatch()) {
               display.sleep();
           }
       }
   }

   private static BarChart.Series<String,Number> createSeries(Pair<String,Double>... values) {
       ObservableList<BarChart.Data> series = FXCollections.<BarChart.Data>observableArrayList();
       for (int i=0; i<values.length; i++) {
           series.add(new BarChart.Data(values[i].getKey(), values[i].getValue()));
       }
       return new BarChart.Series(series);
   }

   private static Canvas createChart(Composite shell, ObservableList<BarChart.Series> bcData) {
       final FXCanvas fxPanel = new FXCanvas(shell, SWT.NONE);
       CategoryAxis xAxis = new CategoryAxis();
       xAxis.setCategories(FXCollections.<String>observableArrayList("2007", "2008", "2009"));
       xAxis.setLabel("Year");
       double tickUnit = 1000.0;
       NumberAxis yAxis = new NumberAxis();
       yAxis.setTickUnit(tickUnit);
       yAxis.setLabel("Units Sold");
       final BarChart chart = new BarChart(xAxis, yAxis, bcData);
       fxPanel.setScene(new Scene(chart));
       return fxPanel;
   }

   private static Table createTable(Composite parent, ObservableList<BarChart.Series> bcData) {
       Table table = new Table (parent, SWT.BORDER | SWT.HIDE_SELECTION);
       table.setLinesVisible(true);
       table.setHeaderVisible(true);
       String[] titles = {"2007", "2008", "2009"};
       for (int i=0; i<titles.length; i++) {
           TableColumn column = new TableColumn (table, SWT.NONE);
           column.setText(titles [i]);
       }
       for (int i=0; i<bcData.size(); i++) {
           createRow(table, bcData.get(i));
       }
       for (int i=0; i<titles.length; i++) {
           table.getColumn (i).setWidth(400/3);
       }
       return table;
   }

   private static TableItem createRow(Table table, BarChart.Series<String,Number> series) {
       TableItem item = new TableItem (table, SWT.NONE);
       item.setData(series);
       int count = 0;
       for (BarChart.Data<String,Number> data : series.getData()) {
           item.setText(count++, data.getYValue().toString());
       }
       return item;
   }

   private static void createTableEditor (final Table table) {
       final TableEditor editor = new TableEditor (table);
       editor.horizontalAlignment = SWT.LEFT;
       editor.grabHorizontal = true;
       table.addListener (SWT.MouseDown, new Listener () {
           public void handleEvent (Event event) {
               Rectangle clientArea = table.getClientArea ();
               Point pt = new Point (event.x, event.y);
               int index = table.getTopIndex ();
               while (index < table.getItemCount ()) {
                   boolean visible = false;
                   final TableItem item = table.getItem (index);
                   for (int i=0; i<table.getColumnCount (); i++) {
                       Rectangle rect = item.getBounds (i);
                       if (rect.contains (pt)) {
                           final int column = i;
                           final Text text = new Text (table, SWT.NONE);
                           final String oldText = item.getText (i);
                           Listener textListener = new Listener () {
                               public void handleEvent (final Event e) {
                                   switch (e.type) {
                                       case SWT.FocusOut:
                                           item.setText (column, text.getText ());
                                           text.dispose ();
                                           break;
                                       case SWT.Traverse:
                                           switch (e.detail) {
                                               case SWT.TRAVERSE_ESCAPE:
                                                   text.setText(oldText);
                                                   //FALL THROUGH
                                               case SWT.TRAVERSE_RETURN:
                                                   item.setText (column, text.getText ());
                                                   text.dispose ();
                                                   e.doit = false;
                                           }
                                           break;
                                       case SWT.Dispose:
                                           if (item.isDisposed() || (text.getText().equals(oldText))) break;
                                           BarChart.Data<String,Number> oldData = ((BarChart.Series<String,Number>)item.getData()).getData().get(column);
                                           try {
                                               double result = Double.parseDouble(text.getText().trim());
                                               oldData.setYValue(result);
                                           } catch (NumberFormatException ex) {
                                               item.setText(column, oldText);
                                           }
                                           break;
                                   }
                               }
                           };
                           text.addListener (SWT.FocusOut, textListener);
                           text.addListener (SWT.Traverse, textListener);
                           text.addListener (SWT.Dispose, textListener);
                           editor.setEditor (text, item, i);
                           text.setText (item.getText (i));
                           text.selectAll ();
                           text.setFocus ();
                           return;
                       }
                       if (!visible && rect.intersects (clientArea)) {
                           visible = true;
                       }
                   }
                   if (!visible) return;
                   index++;
               }
           }
       });
   }
}

DataFX is a project Johan Vos and I have been working on for many months now, and it has gone through a number of iterations in that time. At JavaOne 2011 we put out a first release (let’s call it version 0.0.1 for lack of an official version number), and today I want to briefly introduce it for those of you who didn’t attend JavaOne. However, even if you didn’t attend JavaOne, we’ve put the slides online.

To be very clear, DataFX is not an Oracle project! Johan and I both developed this in our own time, and it does not necessarily represent the future plans of the official JavaFX project. This project was built to make many of the UI controls I develop easier to work with by filling in the gaps as of the current JavaFX 2.0 release. Oracle may or may not have future plans in the same area as DataFX, but for now DataFX exists to fill the gap. For more details, check out the DataFX FAQ.

To make things easier to understand let’s conceptually split DataFX into two sub-projects which attack a common problem from two different angles.

Data Sources

The first sub-project deals with the logistics of getting data into the user interface controls by providing various data source adapters. These adapters are intended to provide convenience around populating JavaFX controls such as ListView and TableView (at this stage, although we’d love to eventually also support populating TreeView and charts). This is achieved by abstracting away the implementation details surrounding data source retrieval and massaging, such that data can be rapidly loaded and seen on screen. This is done by essentially creating data sources that are ObservableList instances, allowing for them to be directly loaded into the ListView and TableView ‘items’ property. In the case of TableView, DataFX can also auto-generate TableColumn instances with pre-built cell value factories defined.

DataSourceReader dsr1 = new FileReader("foo.xml");
DataSourceReader dsr2 = new NetworkReader ("http://foo.bar/foo.xml");

XmlDataSource ds1 = new XmlDataSource(dsr1);

TableView tableView = new TableView();
tableView.setItems(ds1);
tableView.getColumns().addAll(ds1.getColumns());

An example of how to use this API is shown above. We define two DataSourceReader instances: one is a FileReader, the other a NetworkReader (although in this example the NetworkReader isn’t used any further). In both cases it is important to note that the DataSourceReader is datatype-agnostic – that is, it only cares about where the data is coming from, not the format of the data. At present DataFX only ships with these two DataSourceReader implementations, but it is probable that over time we will add more classes. You can see the JavaDoc for these classes in the org.javafxdata.datasources.io package.

Once the DataSourceReader instance is created, we must then create a DataSource using one of the implementations provided in the org.javafxdata.datasources.protocol package. In the example below, we create an XmlDataSource, which knows how to parse an XML data stream and create an ObservableList that can be set directly into a ListView or TableView. Also, because it extends TableWrapper, it has a getColumns() method that can be used to set the columns in a TableView instance. At present, we have DataSource implementations for CSV files, Java Objects, RedFX and XML files. Again, we intend to add further data source implementations in the future as time permits.

Now that the DataSource exists, we create a TableView instance, and set the items property to be the data source itself. We also add all the columns the data source generates into the TableView columns property. This not only creates a column header with default text, it also creates a default cell value factory to populate the cells in that column. This is often the most complex part of using a TableView, and is completely unnecessary in data sources by default (of course, you are free to just create your own TableColumn instances also).

With a (by default) version number of 0.0.1, we recognise that DataFX is not a finished product. For one, it never will be – it’s a free project that we are making available here – but also we recognise the gaping holes in the data sources sub-project. In particular, along with what I’ve listed above, we also want to provide much more convenience around features such as sorting, filtering, and on-demand loading. If there is anything else that you think is missing, you can find the contact details over at the DataFX website.

Cell Factories

A TreeView with support for CheckBoxes

The other sub-project of the DataFX project is dealing with the need to more easily visualise data once it is already appearing inside the ListView, TreeView and TableView controls. This customisation is done almost entirely using the cell factories API that is available in all three controls (I’ll try to blog more about cell factories in a future post). In other words, the default cell factory implementation provided by ListView/TreeView/TableView is sometimes not sufficient – it simply calls toString() on the data objects and shows it onscreen. In these circumstances, it is necessary to provide your own cell factory, and this is where DataFX comes in – it provides a number of useful cell factories that you can drop in and use, often with only one line of code.

There are a number of pre-built custom cells. You can see the full list on the cell factories page on the DataFX website, but briefly, it includes the following:

• TextField (for text editing)
• ChoiceBox (for selecting between a small number of choices)
• CheckBox (for toggling a boolean property)
• ProgressBar (for graphically representing a number as it progresses from 0.0 to 1.0)
• Money formatting (formats a Number instance using a default Locale, and applies CSS to make negative values red, and positive values green)
• Dynamically variable row heights (e.g. on mouse hover, a row will grow to show more information)

For each cell type mentioned above, there is a separate static factory class that contains a number of convenience methods. These methods should be your first port of call. You can find both the cells, and the more convenient cell factories API in the org.javafxdata.control.cell package. You should explore these javadocs as I have spent considerable effort ensuring that they contain all necessary information. For screenshots of all the cell factories currently available, you can go to the cell factories page on the DataFX website (clicking on the ticks will take you to a screenshot for that feature – I’ll try to make this more intuitive when I have time). I’ve attached one screenshot to this blog post, for the CheckBox TreeView.

In the code snippet below, I demonstrate how simple it is to make a ListView support text editing of cells when the user double-clicks on a row. In particular, note that the last line is the only line that uses the DataFX API (i.e. the reference to TextFieldCellFactory is from DataFX) – the other three lines are normal ListView API that should already be familiar to many developers.

ListView<String> listView = new ListView<String>();
listView.setItems(namesList);
listView.setEditable(true);
listView.setCellFactory(TextFieldCellFactory.forListView());

Again, the cell factories implementation certainly lacks features, but we think it provides a good starting point for the most common use cases. If there is a cell factory you think is missing, get in touch and let us know – we may just build it for you!

Conclusion

Johan and I both hope that DataFX is useful to you. We welcome feedback and requests for features – our goal is to make development of rich user interfaces in JavaFX 2.0 as simple as possible. Any use cases you can share with us will be much appreciated as we continue to refine our APIs, as well as provide additional data sources and cell factory implementations.

Download the latest 'Introducing FXML' document

In case you’re wondering what FXML is, FXML is a scriptable, XML-based markup language for constructing Java object graphs. It provides a convenient alternative to constructing such graphs in procedural code, and is ideally suited to defining the user interface of a JavaFX application, since the hierarchical structure of an XML document closely parallels the structure of the JavaFX scene graph.

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!

This release, 2.0, is called “Presidio”, and the next major release is called “Lombard”. So when you see that your issue is targeted at one of these, you know what we’re taking about! If it remains “untargeted”, then it has gone into the pool from which we draw features for future releases, but may not be targeted to a specific release until later in the planning cycle.

Google Maps in JavaFX 2.0

Download a copy of the application and try it out. The jar file is linked below, just download it and double click. This requires you to have the JavaFX 2.0 beta runtime installed.

Download double clickable jar

Using the Application

The toolbar at the top of the application is all JavaFX controls, it communicates with the web map by calling JavaScript functions. Clicking on the Road,Satellite, Hybrid or Terrain sends commands to the JavaScript map library to change the map style. The Google, Yahoo and Bing buttons change the HTML page to use different map providers. As you type in the location field it navigates to the location, try “London” or “New York” for example. The zoom in/out buttons call JavaScript functions to change the map zoom level.

Yahoo Maps in JavaFX 2.0

Bing Maps in JavaFX 2.0

How it’s Built

There are three parts to the application: the HTML and JavaScript code, the JavaFX application and the css styling.

The HTML Code

<html>
<head>
<meta name="viewport" content="initial-scale=1.0, user-scalable=no" />
<style type="text/css">
  html { height: 100% }
  body { height: 100%; margin: 0px; padding: 0px }
  #map_canvas { height: 100%; background-color: #666970; }
</style>
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false">
</script>
<script type="text/javascript">
  function initialize() {
    var latlng = new google.maps.LatLng(37.39822, -121.9643936);
    var myOptions = {
      zoom: 14,
      center: latlng,
      mapTypeId: google.maps.MapTypeId.ROADMAP,
      mapTypeControl: false,
      navigationControl: false,
      streetViewControl: false,
      backgroundColor: "#666970"
    };

    document.geocoder = new google.maps.Geocoder();
    document.map = new google.maps.Map(document.getElementById("map_canvas"),myOptions);

    document.zoomIn = function zoomIn() {
    	var zoomLevel = document.map.getZoom();
    	if (zoomLevel <= 20) document.map.setZoom(zoomLevel + 1);
    }

    document.zoomOut = function zoomOut() {
    	var zoomLevel = document.map.getZoom();
    	if (zoomLevel > 0) document.map.setZoom(zoomLevel - 1);
    }

    document.setMapTypeRoad = function setMapTypeRoad() {
    	document.map.setMapTypeId(google.maps.MapTypeId.ROADMAP);
    }
    document.setMapTypeSatellite = function setMapTypeSatellite() {
    	document.map.setMapTypeId(google.maps.MapTypeId.SATELLITE);
    }
    document.setMapTypeHybrid = function setMapTypeHybrid() {
    	document.map.setMapTypeId(google.maps.MapTypeId.HYBRID);
    }
    document.setMapTypeTerrain = function setMapTypeTerrain() {
    	document.map.setMapTypeId(google.maps.MapTypeId.TERRAIN);
    }

    document.goToLocation = function goToLocation(searchString) {
        document.geocoder.geocode( {'address': searchString}, function(results, status) {
      	  if (status == google.maps.GeocoderStatus.OK) {
            document.map.setCenter(results[0].geometry.location);
          } else {
            alert("Geocode was not successful for the following reason: " + status);
          }
        });
    }
  }
</script>
</head>
<body onload="initialize()">
  <div id="map_canvas" style="width:100%; height:100%"></div>
</body>
</html>

This is the code for using Google Maps API, there is similar code for Yahoo and Bing in the attached Netbeans project below. This is very basic use of the Google Maps API to create a full page map and provide some constant JavaScript functions that the JavaFX application can call. You could have called the Google API directly from JavaFX but it seemed simpler to provide a basic abstraction layer in JavaScript so the only difference the JavaFX app sees is the URL. The other two APIs Yahoo and Bing require that you register to get a API key to be able to use them. The code is provided you just need to insert you API keys into the HTML files.

The JavaFX Code

The most basic application without the toolbar to just show the map would be:

import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.paint.Color;
import javafx.scene.web.WebEngine;
import javafx.scene.web.WebView;
import javafx.stage.Stage;

public class WebMap extends Application {

    @Override public void start(Stage stage) {
        // create web engine and view
        final WebEngine webEngine = new WebEngine(getClass().getResource("googlemap.html").toString());
        final WebView webView = new WebView(webEngine);
        // create scene
        stage.setTitle("Web Map");
        Scene scene = new Scene(webView,1000,700, Color.web("#666970"));
        stage.setScene(scene);
        // show stage
        stage.setVisible(true);
    }

    static { // use system proxy settings when standalone application
        System.setProperty("java.net.useSystemProxies", "true");
    }

    public static void main(String[] args){
        Application.launch(args);
    }
}

The next step is to create the toolbar, this is just a bunch of JavaFX controls in a Toolbar with actions that call the JavaScript functions in the HTML page.

import ....

public class WebMap extends Application {
    private Timeline locationUpdateTimeline;

    @Override public void start(Stage stage) {
        // create web engine and view
        final WebEngine webEngine = new WebEngine(
                getClass().getResource("googlemap.html").toString());
        final WebView webView = new WebView(webEngine);
        // create map type buttons
        final ToggleGroup mapTypeGroup = new ToggleGroup();
        final ToggleButton road = new ToggleButton("Road");
        road.setSelected(true);
        road.setToggleGroup(mapTypeGroup);
        final ToggleButton satellite = new ToggleButton("Satellite");
        satellite.setToggleGroup(mapTypeGroup);
        final ToggleButton hybrid = new ToggleButton("Hybrid");
        hybrid.setToggleGroup(mapTypeGroup);
        final ToggleButton terrain = new ToggleButton("Terrain");
        terrain.setToggleGroup(mapTypeGroup);
        mapTypeGroup.selectedToggleProperty().addListener(
                            new ChangeListener<Toggle>() {
            public void changed(
                    ObservableValue<? extends Toggle> observableValue,
                    Toggle toggle, Toggle toggle1) {
                if (road.isSelected()) {
                    webEngine.executeScript("document.setMapTypeRoad()");
                } else if (satellite.isSelected()) {
                    webEngine.executeScript("document.setMapTypeSatellite()");
                } else if (hybrid.isSelected()) {
                    webEngine.executeScript("document.setMapTypeHybrid()");
                } else if (terrain.isSelected()) {
                    webEngine.executeScript("document.setMapTypeTerrain()");
                }
            }
        });
        // add map source toggles
        ToggleGroup mapSourceGroup = new ToggleGroup();
        final ToggleButton google = new ToggleButton("Google");
        google.setSelected(true);
        google.setToggleGroup(mapSourceGroup);
        final ToggleButton yahoo = new ToggleButton("Yahoo");
        yahoo.setToggleGroup(mapSourceGroup);
        final ToggleButton bing = new ToggleButton("Bing");
        bing.setToggleGroup(mapSourceGroup);
        // listen to selected source
        mapSourceGroup.selectedToggleProperty().addListener(
                            new ChangeListener<Toggle>() {
            public void changed(
                    ObservableValue<? extends Toggle> observableValue,
                    Toggle toggle, Toggle toggle1) {
                terrain.setDisable(true);
                if (google.isSelected()) {
                    terrain.setDisable(false);
                    webEngine.load(
                          getClass().getResource("googlemap.html").toString());
                } else if (yahoo.isSelected()) {
                    webEngine.load(
                          getClass().getResource("bingmap.html").toString());
                } else if (bing.isSelected()) {
                    webEngine.load(
                          getClass().getResource("yahoomap.html").toString());
                }
                mapTypeGroup.selectToggle(road);
            }
        });
        // add search
        final TextBox searchBox = new TextBox("95054");
        searchBox.setColumns(12);
        searchBox.setPromptText("Search");
        searchBox.rawTextProperty().addListener(new ChangeListener<String>() {
            public void changed(
                    ObservableValue<? extends String> observableValue,
                    String s, String s1) {
                // delay location updates to we don't go too fast file typing
                if (locationUpdateTimeline!=null) locationUpdateTimeline.stop();
                locationUpdateTimeline = new Timeline();
                locationUpdateTimeline.getKeyFrames().add(
                    new KeyFrame(new Duration(400),
                            new EventHandler<ActionEvent>() {
                        public void handle(ActionEvent actionEvent) {
                            webEngine.executeScript("document.goToLocation(\""+
                                    searchBox.getRawText()+"\")");
                        }
                    })
                );
                locationUpdateTimeline.play();
            }
        });
        Button zoomIn = new Button("Zoom In");
        zoomIn.setOnAction(new EventHandler<ActionEvent>() {
            public void handle(ActionEvent actionEvent) {
                webEngine.executeScript("document.zoomIn()");
            }
        });
        Button zoomOut = new Button("Zoom Out");
        zoomOut.setOnAction(new EventHandler<ActionEvent>() {
            public void handle(ActionEvent actionEvent) {
                webEngine.executeScript("document.zoomOut()");
            }
        });
        // create toolbar
        ToolBar toolBar = new ToolBar();
        toolBar.getStyleClass().add("map-toolbar");
        toolBar.getItems().addAll(
                road, satellite, hybrid, terrain,
                createSpacer(),
                google, yahoo, bing,
                createSpacer(),
                new Label("Location:"), searchBox, zoomIn, zoomOut);
        // create root
        BorderPane root = new BorderPane();
        root.getStyleClass().add("map");
        root.setCenter(webView);
        root.setTop(toolBar);
        // create scene
        stage.setTitle("Web Map");
        Scene scene = new Scene(root,1000,700, Color.web("#666970"));
        stage.setScene(scene);
        scene.getStylesheets().add("/webmap/WebMap.css");
        // show stage
        stage.setVisible(true);
    }

    private Node createSpacer() {
        Region spacer = new Region();
        HBox.setHgrow(spacer, Priority.ALWAYS);
        return spacer;
    }

    static { // use system proxy settings when standalone application
        System.setProperty("java.net.useSystemProxies", "true");
    }

    public static void main(String[] args){
        Application.launch(args);
    }
}

The CSS Code

The last part of the application is a little css to style the toolbar and make it look dark to stand out from the maps.

.map{
    -fx-background-color: #666970;
}
.map-toolbar .button, .map-toolbar .toggle-button, .map-toolbar .label {
    -fx-text-fill: white;
    -fx-background-radius: 0;
}
.map-toolbar{
    -fx-base: #505359;
    -fx-background: #505359;
    -fx-shadow-highlight-color: transparent;
    -fx-spacing: 5;
    -fx-padding: 4 4 4 4;
    -fx-background-color: linear (0%,0%) to (0%,100%) stops
                (0%,#919398)
                (4%,#919398)
                (4.1%,#666970)
                (66%,#494d53)
                (94%,#3c3f46)
                (94.1%,#515151);
}

Download Source

Download Netbeans Project

• Dynamic Data Support
• Animation
• Auto Ranging
• CSS Styling

There is a sample application called “Chart Sampler” that ships with JavaFX 2.0 Beta that shows some of what can be done with the new charts. Here are a few screen shots to tempt you to go and check it out