The design space for a MoneyField is quite interesting. I did a bunch of research and tried out various different representations of “money” in Java, including Joda-Money, but in the end the parsing was not satisfactory and I concluded to just use a good old fashioned BigDecimal to represent a monetary value. The best blog I found talking about the issues with BigDecimal for representing Money is this one titled BigDecimal and Your Money. I think this same technique that I’m going to show works equally well whatever the data type is.

The most complex part of implementing this control was using the DecimalFormat for parsing the result back. In fact, I had a lot of trouble parsing the text in the MoneyField and producing a reliable BigDecimal out of it. I’m sure the implementation is lousy compared to what an expert in parsing such things could do, and I would welcome any feedback on my present implementation.

Writing the Control itself was trivial. I extended MoneyField from Control, and added a value property for holding the BigDecimal that would represent the monetary value of this control. I added a few other properties such as editable, promptText, and prefColumnCount. I also added an onAction event to MoneyField.

Now, there are some interesting things to talk about for you aspiring UI controls authors. Lets take a brief walk through the code.

public class MoneyField extends Control {
    /**
     * Creates a new MoneyField. The style class is set to "money-field".
     */
    public MoneyField() {
        getStyleClass().setAll("money-field");
    }

    @Override protected String getUserAgentStylesheet() {
        return getClass().getResource("MoneyField.css").toExternalForm();
    }
}

Every third party UI control must define the essential skeletal structure that you see in the above code snippet. You should provide a no-arg constructor (or it may not work in FXML). In your constructor, you should set the style class of the control to be the “css-ized” name of your control. Just toLowerCase and separate words by dashes. Then, because I want my skin to be entirely defined by CSS, I will override the getUserAgentStylesheet method and have it return a reference to a css file that I am going to define which acts as the “user agent stylesheet” for this control. That is, it provides the default CSS style for this control. Here is what my CSS file looks like:

#money-text-field {
    -fx-skin: "com.sun.javafx.scene.control.skin.TextFieldSkin";
}

.money-field {
    -fx-skin: "com.fxexperience.javafx.scene.control.skin.MoneyFieldSkin";
    -fx-background-color: -fx-shadow-highlight-color, -fx-text-box-border, -fx-control-inner-background;
    -fx-background-insets: 0, 1, 2;
    -fx-background-radius: 3, 2, 2;
    -fx-padding: 3 5 3 5;
    -fx-prompt-text-fill: derive(-fx-control-inner-background,-30%);
    -fx-cursor: text;
}

.money-field:focused {
    -fx-background-color: -fx-focus-color, -fx-text-box-border, -fx-control-inner-background;
    -fx-background-insets: -0.4, 1, 2;
    -fx-background-radius: 3.4, 2, 2;
}

.money-field:disabled {
    -fx-opacity: -fx-disabled-opacity;
}

There really isn’t a lot to say here, other than you can see I have a little trickery around the #money-text-field. Basically, I want the developer to be able to style the money field from CSS using .money-field, but I need to make sure the Skin used with the inner TextField is still a normal TextField. You’ll see how this fits together in a minute when I describe how the MoneyFieldSkin works.

Back in the MoneyField.java file, I also defined the above mentioned properties and events. First, here is what a “normal” property looks like. It is fully observable, readable, and writable.

    /**
     * The value of the MoneyField. If null, the value will be treated as "0", but
     * will still actually be null.
     */
    private ObjectProperty<BigDecimal> value = new SimpleObjectProperty<BigDecimal>(this, "value");
    public final BigDecimal getValue() { return value.get(); }
    public final void setValue(BigDecimal value) { this.value.set(value); }
    public final ObjectProperty<BigDecimal> valueProperty() { return value; }

I am using the SimpleObjectProperty, which takes as parameters a reference to the bean that defined it, and the name of the property. The value of the value property defaults to null. Our doclet produces javadoc on the getter and setter without having to actually write it manually, so that’s why docs are missing for those. The editable property is likewise defined as a SimpleBooleanProperty.

The onAction is a very straightforward implementation. If you write your own controls and want to include your own action events, it is very easy to do:

    /**
     * The action handler associated with this MoneyField, or
     * <tt>null</tt> if no action handler is assigned.
     *
     * The action handler is normally called when the user types the ENTER key.
     */
    private ObjectProperty<EventHandler<ActionEvent>> onAction = new ObjectPropertyBase<EventHandler<ActionEvent>>() {
        @Override protected void invalidated() {
            setEventHandler(ActionEvent.ACTION, get());
        }

        @Override public Object getBean() { return MoneyField.this; }
        @Override public String getName() { return "onAction"; }
    };
    public final ObjectProperty<EventHandler<ActionEvent>> onActionProperty() { return onAction; }
    public final EventHandler<ActionEvent> getOnAction() { return onActionProperty().get(); }
    public final void setOnAction(EventHandler<ActionEvent> value) { onActionProperty().set(value); }
}

You’ll notice that in the invalidated method of the property I call setEventHandler. This method exists for the registration of such event handlers with the system. Another interesting thing here is that I’m not extending SimpleObjectProperty, but rather I’m extending ObjectPropertyBase.

Every property must implement the getBean() and getName() method. SimpleXXX properties have fields which hold the bean & name, and you supply them in the constructor. But XXXPropertyBase properties have no such fields, and you must implement these methods. Why chose one over the other? Well, SimpleXXX properties will have smaller static footprint because they are using a class instead of defining a class, but will have larger dynamic footprint because they have two additional fields which must be saved for each instance. XXXPropertyBase uses larger static footprint because it defines a class, but smaller dynamic footprint because it doesn’t have to save these two fields. Since I had to subclass an object property anyway for the sake of implementing the invalidated method, I might as well extend ObjectPropertyBase and save a couple fields at runtime.

The Skin for MoneyField was quite interesting. At first I thought I would extend from TextFieldSkin (an internal implementation in JavaFX) but then discovered this wasn’t necessary. Instead, I could just implement the Skin interface and return a TextField as the “node” of the Skin. So the MoneyField defines my UI, and the TextField is actually what I end up using to represent the MoneyField. And then there is a pile of glue code which ties the TextField to the MoneyField. The other nice thing about this approach was that I could implement the entirety of MoneyField and MoneyFieldSkin without using any private API (which, when I started writing this, I didn’t think was possible).

public class MoneyFieldSkin implements Skin<MoneyField> {
    /**
     * The {@code Control} that is referencing this Skin. There is a
     * one-to-one relationship between a {@code Skin} and a {@code Control}.
     * When a {@code Skin} is set on a {@code Control}, this variable is
     * automatically updated.
     */
    private MoneyField control;

    /**
     * This textField is used to represent the MoneyField.
     */
    private TextField textField;

    /**
     * Create a new MoneyFieldSkin.
     * @param control The MoneyField
     */
    public MoneyFieldSkin(final MoneyField control) {
        this.control = control;

        // Create the TextField that we are going to use to represent this MoneyFieldSkin.
        // The textField restricts input so that only valid digits that contribute to the
        // Money can be input.
        textField = new TextField() { // ...
        };

        // ... and a lot more stuff!
    }

    @Override public MoneyField getSkinnable() {
        return control;
    }

    @Override public Node getNode() {
        return textField;
    }

    /**
     * Called by a Skinnable when the Skin is replaced on the Skinnable. This method
     * allows a Skin to implement any logic necessary to clean up itself after
     * the Skin is no longer needed. It may be used to release native resources.
     * The methods {@link #getSkinnable()} and {@link #getNode()}
     * should return null following a call to dispose. Calling dispose twice
     * has no effect.
     */
    @Override public void dispose() {
        textField = null;
    }

    // ... and a lot more stuff!
}

The above code lays out the very basic skeletal structure of a Skin. This skin implements the Skin interface directly. The constructor takes the MoneyField it will be working with, and creates the TextField which will represent the skin (or “draw” the skin). In the dispose method, we throw away the TextField.

If you ran the code above, you would find a MoneyField that looked and felt like a TextField. None of the properties on the MoneyField would work, but from a visual perspective and a text entry perspective you’d have, essentially, a TextField. The rest of MoneyFieldSkin is devoted to wiring up the MoneyField API to the TextField and implementing all the parsing and formatting necessary to make it look like a money field.

The remainder of the MoneyFieldSkin isn’t worth going through in this blog post, though you can download the Intellij project and check it out for yourself.

When Jonathan tried this out last night he was getting exceptions with the New Zealand currency. I suspect there may be problems in Australia too. I’m hoping one of our readers from down under will give it a look and see where my bug is .

Using the MoneyField is really very straightforward. I hope it is actually useful to boot. I’m wondering if anybody industrious out there might take this design strategy and write an EmailField and UrlField control, maybe a NumberField control too! It seems eminently doable using only the public API and would make a great addition to the ecosystem (as well as a great addition to the toolkit!).

I was inspired by Dean Iverson’s tweet with a audio equalizer in JavaFX:

#JavaFX rocks. Literally. An example from our upcoming Pro JavaFX 2 book: pic.twitter.com/tSI4Vry4
and the equalizer view from that Pro JavaFX 2 example app: pic.twitter.com/T6jxvrf9
. updated pic.twitter.com/FqzgVimG

So wanted to have a go at doing one my self, so little while later I have a design and built a working application. Demo video after the break.

The Design

I started the design with a free Photoshop file from Diego Monzon:

You will see that some of it like the cool VU meters made it direct though to my design but then I played around with the other parts. I have added a link to the Photoshop file I created so you can see what I have done if you are intrested. From the photoshop file I produced a few PNG files which are used in the application, you can see them in the src images directory. I found a free LCD dot matrix font from dafont which is what I am using for the text on the screen. You can see in the code how this is loaded in JavaFX.

Download the Photoshop File 18Mb

The Code

The application did not take that long to build, guess about a day in total and about 800 lines of code. I think it is fully working other than the balance is a little fiddly with the mouse. All the control customizations should have full keyboard navigation . It is mostly standard UI Controls just styled with Images and CSS. The round knobs like balance and volume I had to do something special for and created a knob skin for the Slider control. There was a bunch of the standard logic to load and parse M3U and XML playlists, a very simple data model object PlayList which just contains a url which it was loaded from and a observable list of Pairs, each Pair being a name for the song and a url to the song. We did not have all the low level media API I needed for the VU meters but as they are only really for show I made of some data from what we can get from AudioSpectrumListener.

Download the source and Netbeans Project 1.5Mb

Hope you enjoy playing with this fun little app as much as I did creating it. Hope it goes to show that you can create pretty much any UI that you can imagine in JavaFX 2.0 and even use standard controls so you maintain keyboard navigation, accessibility etc.

All of these are mostly created with multiple background fill layers each with a gradient. Then there is a little font tweaking and some subtle effects. So for example all you need to make a JavaFX button look like a Windows 7 button is:

#windows7-default {
    -fx-background-color:
        #3c7fb1,
        linear-gradient(#fafdfe, #e8f5fc),
        linear-gradient(#eaf6fd 0%, #d9f0fc 49%, #bee6fd 50%, #a7d9f5 100%);
    -fx-background-insets: 0,1,2;
    -fx-background-radius: 3,2,1;
    -fx-padding: 3 30 3 30;
    -fx-text-fill: black;
    -fx-font-size: 14px;
}

The first line defines the 3 background fills, first is solid color and the other two are linear gradients. The background-insets offsets the backgrounds so they do not 100% paint over each other and the second background is 1px in from the outside and the 3rd background is 2px in from the outside of the button. The background-radius us setting the corner radius’s of the 3 backgrounds getting smaller as the backgrounds move in, this makes the gap between the borders a consistent 1 pixel all the way around. Padding adds extra space around the text to make the button bigger by default. Then the last two lines set the text color and size. That is all there is too it.

I have not included styles for the pressed, over and focused states of all the buttons but they can all be easily added in a similar way. I have included a over and pressed state for the “Record Sales” button as a example.

You can download the complete Netbeans project with all the code here.
ButtonStyles.zip

Here is the CSS code of all the button styles you see above:

#green {
    -fx-background-color:
        linear-gradient(#f0ff35, #a9ff00),
        radial-gradient(center 50% -40%, radius 200%, #b8ee36 45%, #80c800 50%);
    -fx-background-radius: 6, 5;
    -fx-background-insets: 0, 1;
    -fx-effect: dropshadow( three-pass-box , rgba(0,0,0,0.4) , 5, 0.0 , 0 , 1 );
    -fx-text-fill: #395306;
}
#round-red {
    -fx-background-color: linear-gradient(#ff5400, #be1d00);
    -fx-background-radius: 30;
    -fx-background-insets: 0;
    -fx-text-fill: white;
}
#bevel-grey {
    -fx-background-color:
        linear-gradient(#f2f2f2, #d6d6d6),
        linear-gradient(#fcfcfc 0%, #d9d9d9 20%, #d6d6d6 100%),
        linear-gradient(#dddddd 0%, #f6f6f6 50%);
    -fx-background-radius: 8,7,6;
    -fx-background-insets: 0,1,2;
    -fx-text-fill: black;
    -fx-effect: dropshadow( three-pass-box , rgba(0,0,0,0.6) , 5, 0.0 , 0 , 1 );
}
#glass-grey {
    -fx-background-color:
        #c3c4c4,
        linear-gradient(#d6d6d6 50%, white 100%),
        radial-gradient(center 50% -40%, radius 200%, #e6e6e6 45%, rgba(230,230,230,0) 50%);
    -fx-background-radius: 30;
    -fx-background-insets: 0,1,1;
    -fx-text-fill: black;
    -fx-effect: dropshadow( three-pass-box , rgba(0,0,0,0.6) , 3, 0.0 , 0 , 1 );
}
#shiny-orange {
    -fx-background-color:
        linear-gradient(#ffd65b, #e68400),
        linear-gradient(#ffef84, #f2ba44),
        linear-gradient(#ffea6a, #efaa22),
        linear-gradient(#ffe657 0%, #f8c202 50%, #eea10b 100%),
        linear-gradient(from 0% 0% to 15% 50%, rgba(255,255,255,0.9), rgba(255,255,255,0));
    -fx-background-radius: 30;
    -fx-background-insets: 0,1,2,3,0;
    -fx-text-fill: #654b00;
    -fx-font-weight: bold;
    -fx-font-size: 14px;
    -fx-padding: 10 20 10 20;
}
#dark-blue {
    -fx-background-color:
        #090a0c,
        linear-gradient(#38424b 0%, #1f2429 20%, #191d22 100%),
        linear-gradient(#20262b, #191d22),
        radial-gradient(center 50% 0%, radius 100%, rgba(114,131,148,0.9), rgba(255,255,255,0));
    -fx-background-radius: 5,4,3,5;
    -fx-background-insets: 0,1,2,0;
    -fx-text-fill: white;
    -fx-effect: dropshadow( three-pass-box , rgba(0,0,0,0.6) , 5, 0.0 , 0 , 1 );
    -fx-font-family: "Arial";
    -fx-text-fill: linear-gradient(white, #d0d0d0);
    -fx-font-size: 12px;
    -fx-padding: 10 20 10 20;
}
#dark-blue Text {
    -fx-effect: dropshadow( one-pass-box , rgba(0,0,0,0.9) , 1, 0.0 , 0 , 1 );
}
#record-sales {
    -fx-padding: 8 15 15 15;
    -fx-background-insets: 0,0 0 5 0, 0 0 6 0, 0 0 7 0;
    -fx-background-radius: 8;
    -fx-background-color:
        linear-gradient(from 0% 93% to 0% 100%, #a34313 0%, #903b12 100%),
        #9d4024,
        #d86e3a,
        radial-gradient(center 50% 50%, radius 100%, #d86e3a, #c54e2c);
    -fx-effect: dropshadow( gaussian , rgba(0,0,0,0.75) , 4,0,0,1 );
    -fx-font-weight: bold;
    -fx-font-size: 1.1em;
}
#record-sales:hover {
    -fx-background-color:
        linear-gradient(from 0% 93% to 0% 100%, #a34313 0%, #903b12 100%),
        #9d4024,
        #d86e3a,
        radial-gradient(center 50% 50%, radius 100%, #ea7f4b, #c54e2c);
}
#record-sales:pressed {
    -fx-padding: 10 15 13 15;
    -fx-background-insets: 2 0 0 0,2 0 3 0, 2 0 4 0, 2 0 5 0;
}
#record-sales Text {
    -fx-fill: white;
    -fx-effect: dropshadow( gaussian , #a30000 , 0,0,0,2 );
}
#rich-blue {
    -fx-background-color:
        #000000,
        linear-gradient(#7ebcea, #2f4b8f),
        linear-gradient(#426ab7, #263e75),
        linear-gradient(#395cab, #223768);
    -fx-background-insets: 0,1,2,3;
    -fx-background-radius: 3,2,2,2;
    -fx-padding: 12 30 12 30;
    -fx-text-fill: white;
    -fx-font-size: 12px;
}
#rich-blue Text {
    -fx-effect: dropshadow( one-pass-box , rgba(0,0,0,0.8) , 0, 0.0 , 0 , 1);
}
#big-yellow {
    -fx-background-color:
        #ecebe9,
        rgba(0,0,0,0.05),
        linear-gradient(#dcca8a, #c7a740),
        linear-gradient(#f9f2d6 0%, #f4e5bc 20%, #e6c75d 80%, #e2c045 100%),
        linear-gradient(#f6ebbe, #e6c34d);
    -fx-background-insets: 0,9 9 8 9,9,10,11;
    -fx-background-radius: 50;
    -fx-padding: 15 30 15 30;
    -fx-font-family: "Helvetica";
    -fx-font-size: 18px;
    -fx-text-fill: #311c09;
    -fx-effect: innershadow( three-pass-box , rgba(0,0,0,0.1) , 2, 0.0 , 0 , 1);
}
#big-yellow Text {
    -fx-effect: dropshadow( one-pass-box , rgba(255,255,255,0.5) , 0, 0.0 , 0 , 1);
}
#iphone-toolbar {
    -fx-background-color: linear-gradient(#98a8bd 0%, #8195af 25%, #6d86a4 100%);
}
#iphone {
    -fx-background-color:
        #a6b5c9,
        linear-gradient(#303842 0%, #3e5577 20%, #375074 100%),
        linear-gradient(#768aa5 0%, #849cbb 5%, #5877a2 50%, #486a9a 51%, #4a6c9b 100%);
    -fx-background-insets: 0 0 -1 0,0,1;
    -fx-background-radius: 5,5,4;
    -fx-padding: 7 30 7 30;
    -fx-text-fill: #242d35;
    -fx-font-family: "Helvetica";
    -fx-font-size: 12px;
    -fx-text-fill: white;
}
#iphone Text {
    -fx-effect: dropshadow( one-pass-box , rgba(0,0,0,0.8) , 0, 0.0 , 0 , -1 );
}
#ipad-dark-grey {
    -fx-background-color:
        linear-gradient(#686868 0%, #232723 25%, #373837 75%, #757575 100%),
        linear-gradient(#020b02, #3a3a3a),
        linear-gradient(#9d9e9d 0%, #6b6a6b 20%, #343534 80%, #242424 100%),
        linear-gradient(#8a8a8a 0%, #6b6a6b 20%, #343534 80%, #262626 100%),
        linear-gradient(#777777 0%, #606060 50%, #505250 51%, #2a2b2a 100%);
    -fx-background-insets: 0,1,4,5,6;
    -fx-background-radius: 9,8,5,4,3;
    -fx-padding: 15 30 15 30;
    -fx-font-family: "Helvetica";
    -fx-font-size: 18px;
    -fx-font-weight: bold;
    -fx-text-fill: white;
    -fx-effect: dropshadow( three-pass-box , rgba(255,255,255,0.2) , 1, 0.0 , 0 , 1);
}
#ipad-dark-grey Text {
    -fx-effect: dropshadow( one-pass-box , black , 0, 0.0 , 0 , -1 );
}
#ipad-grey {
    -fx-background-color:
        linear-gradient(#686868 0%, #232723 25%, #373837 75%, #757575 100%),
        linear-gradient(#020b02, #3a3a3a),
        linear-gradient(#b9b9b9 0%, #c2c2c2 20%, #afafaf 80%, #c8c8c8 100%),
        linear-gradient(#f5f5f5 0%, #dbdbdb 50%, #cacaca 51%, #d7d7d7 100%);
    -fx-background-insets: 0,1,4,5;
    -fx-background-radius: 9,8,5,4;
    -fx-padding: 15 30 15 30;
    -fx-font-family: "Helvetica";
    -fx-font-size: 18px;
    -fx-font-weight: bold;
    -fx-text-fill: #333333;
    -fx-effect: dropshadow( three-pass-box , rgba(255,255,255,0.2) , 1, 0.0 , 0 , 1);
}
#ipad-grey Text {
    -fx-effect: dropshadow( one-pass-box , white , 0, 0.0 , 0 , 1 );
}
#lion-default {
    -fx-background-color:
        rgba(0,0,0,0.08),
        linear-gradient(#5a61af, #51536d),
        linear-gradient(#e4fbff 0%,#cee6fb 10%, #a5d3fb 50%, #88c6fb 51%, #d5faff 100%);
    -fx-background-insets: 0 0 -1 0,0,1;
    -fx-background-radius: 5,5,4;
    -fx-padding: 3 30 3 30;
    -fx-text-fill: #242d35;
    -fx-font-size: 14px;
}
#lion {
    -fx-background-color:
        rgba(0,0,0,0.08),
        linear-gradient(#9a9a9a, #909090),
        linear-gradient(white 0%, #f3f3f3 50%, #ececec 51%, #f2f2f2 100%);
    -fx-background-insets: 0 0 -1 0,0,1;
    -fx-background-radius: 5,5,4;
    -fx-padding: 3 30 3 30;
    -fx-text-fill: #242d35;
    -fx-font-size: 14px;
}
#windows7-default {
    -fx-background-color:
        #3c7fb1,
        linear-gradient(#fafdfe, #e8f5fc),
        linear-gradient(#eaf6fd 0%, #d9f0fc 49%, #bee6fd 50%, #a7d9f5 100%);
    -fx-background-insets: 0,1,2;
    -fx-background-radius: 3,2,1;
    -fx-padding: 3 30 3 30;
    -fx-text-fill: black;
    -fx-font-size: 14px;
}
#windows7 {
    -fx-background-color:
        #707070,
        linear-gradient(#fcfcfc, #f3f3f3),
        linear-gradient(#f2f2f2 0%, #ebebeb 49%, #dddddd 50%, #cfcfcf 100%);
    -fx-background-insets: 0,1,2;
    -fx-background-radius: 3,2,1;
    -fx-padding: 3 30 3 30;
    -fx-text-fill: black;
    -fx-font-size: 14px;
}

A TableView control using default styling and API as provided in JavaFX 2.0.

Or, more specifically, why it doesn’t look like this:

A TableView without alternate row highlighting in empty rows

I can see where this question comes from, given this is how Swing’s JTable looks:

Swing JTable

It comes down to taste I guess, but given that there is a subset of developers who expect this look, I thought I’d put a blog post up here to clarify how it is done (and to save me having to explain it to people individually by email!) All you need is the following CSS for TableView:

.table-row-cell:empty {
    -fx-background-color: white;
}

.table-row-cell:empty .table-cell {
    -fx-border-width: 0px;
}

Similarly, for ListView, you can get away with just the first statement above (slightly modified for ListView):

.list-cell:empty {
    -fx-background-color: white;
}

The end result is precisely what you see in the second image above (there ain’t no photoshop trickery here!) Hopefully this helps people customising their user interfaces, and hopefully also encourages you to further explore what is possible. The best starting point is the excellent JavaFX documentation website, the CSS Reference (which is about to be updated for 2.0.2 I believe), and as always, the caspian.css file that ships with every JavaFX release (embedded within jfxrt.jar).

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.

In the very, very late stages of the JavaFX 2.0 EA program, we decided we didn’t really like this API all that much. The concept of having both left/right and top/bottom just didn’t really gel with us. After some discussion, we thought we’d use the same API style as we do elsewhere in JavaFX 2.0: expose a collection and allow for developers to place their content into it. This mean that to use a SplitPane, you’d use code such as the following:

import javafx.application.Application;
import javafx.geometry.Orientation;
import javafx.scene.Group;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.control.SplitPane;
import javafx.scene.layout.HBox;
import javafx.scene.paint.Color;
import javafx.stage.Stage;

public class SplitPaneSample extends Application {

    @Override public void start(Stage stage) {
        HBox hbox = new HBox(20);
        hbox.setTranslateX(20);
        hbox.setTranslateY(20);

        SplitPane splitPane1 = new SplitPane();
        splitPane1.setPrefSize(200, 200);
        final Button l = new Button("Left Button");
        final Button r = new Button("Right Button");
        splitPane1.getItems().addAll(l, r);
        hbox.getChildren().add(splitPane1);

        Scene scene = new Scene(new Group(hbox), 560, 240);
        scene.setFill(Color.GHOSTWHITE);
        stage.setScene(scene);
        stage.setTitle("SplitPane");
        stage.setVisible(true);
    }

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

The main segment of code is the middle block, where we create a SplitPane, set a preferred size, and add in the two buttons we want to display. I hope you see where I’m going with this: now that we aren’t constrained to just having ‘left’ and ‘right’ nodes, we can actually put in any number of nodes into the items collection – and the SplitPane will automatically create N – 1 dividers. For example:

        SplitPane splitPane2 = new SplitPane();
        splitPane2.setPrefSize(300, 200);
        final Button l2 = new Button("Left Button");
        final Button c2 = new Button("Center Button");
        final Button r2 = new Button("Right Button");
        splitPane2.getItems().addAll(l2, c2, r2);
        hbox.getChildren().add(splitPane2);

The result of this code is shown in the second SplitPane you see in the picture above. Now, a SplitPane wouldn’t be all that great if it only allows for the SplitPane content to run in a horizontal flow, so we also support setting an orientation on the SplitPane. As mentioned, the default value is HORIZONTAL, which is what you see in the screenshot above. You can also set it to VERTICAL, which you can see in the screenshot below.

        SplitPane splitPane1 = new SplitPane();
        splitPane1.setOrientation(Orientation.VERTICAL);
        splitPane1.setPrefSize(200, 200);
        final Button l1 = new Button("Left Button");
        final Button r1 = new Button("Right Button");
        splitPane1.getItems().addAll(l1, r1);
        hbox.getChildren().add(splitPane1);

        SplitPane splitPane2 = new SplitPane();
        splitPane2.setOrientation(Orientation.VERTICAL);
        splitPane2.setPrefSize(300, 200);
        final Button l2 = new Button("Left Button");
        final Button c2 = new Button("Center Button");
        final Button r2 = new Button("Right Button");
        splitPane2.getItems().addAll(l2, c2, r2);
        hbox.getChildren().add(splitPane2);

Now, you can’t have a single SplitPane with multiple orientations. However, you can quite easily embed one SplitPane inside another to get this effect:

        SplitPane splitPane1 = new SplitPane();
        splitPane1.setOrientation(Orientation.VERTICAL);
        splitPane1.setPrefSize(200, 200);
        final Button l1 = new Button("Top Button");
        final Button r1 = new Button("Bottom Button");
        splitPane1.getItems().addAll(l1, r1);

        SplitPane splitPane2 = new SplitPane();
        splitPane2.setOrientation(Orientation.HORIZONTAL);
        splitPane2.setPrefSize(300, 200);
        final Button c2 = new Button("Center Button");
        final Button r2 = new Button("Right Button");
        splitPane2.getItems().addAll(splitPane1, c2, r2);
        hbox.getChildren().add(splitPane2);

With the code above, you’ll end up with something a little like this:

I hope this helps to introduce you to our brand new SplitPane control, and I look forward to see you using it in your applications soon!

In JavaFX, putting the CheckBox into a mode where it can be indeterminate is quite simple, simply set the allowIndeterminate property to true:

        CheckBox cb = new CheckBox("Indeterminate CheckBox");
        cb.setAllowIndeterminate(true);

You manipulate the state of the check box through the use of two properties: selected and indeterminate. If allowIndeterminate is true, then as the user clicks on the check box, it will cycle through three state combinations:

• selected = true, indeterminate = false
• selected = false, indeterminate = true
• selected = false, indeterminate = false

Here is a full example:

import javafx.application.Application;
import javafx.beans.value.ChangeListener;
import javafx.beans.value.ObservableValue;
import javafx.geometry.Pos;
import javafx.scene.Group;
import javafx.scene.Scene;
import javafx.scene.control.CheckBox;
import javafx.scene.control.Label;
import javafx.scene.layout.VBox;
import javafx.stage.Stage;

public class IndeterminateCheckBox extends Application {
    Label label;
    CheckBox cbox;

    @Override public void start(Stage stage) {
        label = new Label();

        cbox = new CheckBox("Indeterminate CheckBox");
        cbox.setIndeterminate(true);
        cbox.setAllowIndeterminate(true);

        ChangeListener<Boolean> listener = new ChangeListener<Boolean>() {
            @Override
            public void changed(ObservableValue<? extends Boolean> prop, Boolean old, Boolean val) {
                updateLabel();
            }
        };

        cbox.selectedProperty().addListener(listener);
        cbox.indeterminateProperty().addListener(listener);
        updateLabel();

        VBox vbox = new VBox(7);
        vbox.setAlignment(Pos.CENTER);
        vbox.getChildren().addAll(label, cbox);
        Scene scene = new Scene(vbox, 400, 400);
        stage.setTitle("Hello CheckBox");
        stage.setScene(scene);
        stage.setVisible(true);
    }

    private void updateLabel() {
        final String txt = cbox.isIndeterminate() ? "The check box is indeterminate" :
                cbox.isSelected() ? "The check box is selected" :
                "The check box is not selected";

        label.setText(txt);
    }

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

So, whenever either the indeterminate or selected property changes, we update the label’s text to match. This is kind of gross though (now that I’ve typed it out), because I have to attach a listener to two different properties. It would be nicer if there were a proper event handler that I could attach to the CheckBox which would be notified whenever indeterminate or selected changed.

I’ve filed a JIRA RT-13992 to track this.

Meanwhile, I can also use the high level binding APIs to do this. Here is an alternative implementation.

import javafx.application.Application;
import javafx.beans.binding.Bindings;
import javafx.beans.value.ChangeListener;
import javafx.beans.value.ObservableValue;
import javafx.geometry.Pos;
import javafx.scene.Group;
import javafx.scene.Scene;
import javafx.scene.control.CheckBox;
import javafx.scene.control.Label;
import javafx.scene.layout.VBox;
import javafx.stage.Stage;

public class IndeterminateCheckBox2 extends Application {
    @Override public void start(Stage stage) {
        CheckBox cbox = new CheckBox("Indeterminate CheckBox");
        cbox.setIndeterminate(true);
        cbox.setAllowIndeterminate(true);

        Label label = new Label();
        label.textProperty().bind(
            Bindings.when(cbox.indeterminateProperty()).
                then("The check box is indeterminate").
                otherwise(
                    Bindings.when(cbox.selectedProperty()).
                        then("The check box is selected").
                        otherwise("The check box is not selected"))
        );

        VBox vbox = new VBox(7);
        vbox.setAlignment(Pos.CENTER);
        vbox.getChildren().addAll(label, cbox);
        Scene scene = new Scene(vbox, 400, 400);
        stage.setTitle("Hello CheckBox");
        stage.setScene(scene);
        stage.setVisible(true);
    }

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

And that’s pretty darn slick, IMHO.

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

So, unsurprisingly, today I got an email from a user of JavaFX, who claims to be a fan of FX Experience (hi Keith!), who was needing multiple selection for his work. I didn’t actually think it could be done very easily (and one of my main jobs is working on these controls, so I should know), but I spent a bit of time looking into it, and it turns out that it’s actually quite possible, with a number of warnings and rough edges, and also the use of a little bit of unpublished API. As long as you’re promising to not tell anyone, I thought I’d share this code….but just with you, so shhh

What I present to you today therefore is to be considered proof of concept only. Using this in your day job is considered risky, as some of the code may not work in future releases. Being a proof of concept, the code below is not fully implemented (which I’ll detail more shortly), and performance may degrade somewhat as the number of selected items increases. No attempt at performance optimisation has been made. Proceed at your own risk I hope that I’ve sufficiently scared you.

I wanted to briefly show the code, and then just provide you with a jar file to download and use in your own projects. Firstly though, here’s a screenshot I sent to Keith to detail what he should expect to see when he runs the new control:

Do not adjust your TV sets (for those of you, ah, accessing the net via your TV?). The ListView on the right looks odd because the label is rotated inside the cell, to make it apparent that you can get multiple selection even when using a custom cell factory. To get the multiple rows selected I just held down ctrl or shift as I left-clicked, as is usually the case in list controls in other UI toolkits. Here’s the code I wrote to create the app in the screenshot above:

Stage {
    title: "Multiple Selection Demo"
    scene: Scene {
        width: 340
        height: 260
        content: [
            HBox {
                spacing: 10
                content: [
                    MultiSelectListView {
                        items: [1..100]
                    },

                    MultiSelectListView {
                        items: [1..100]
                        cellFactory: function() {
                            def cell:ListCell = MultiSelectListCell {
                                node: Label {
                                    rotate: 180
                                    text: bind if (cell.item == null)
                                        then "" else "{cell.item}";
                                }
                            }
                        }
                    }
                ]
            }
        ]
    }
}

Pretty much the kind of code you’d expect to see when creating a ListView, except the control is called MultiSelectListView, and the ListCell used in the second list is called MultiSelectListCell.

The code for MultiSelectListView is shown below. There is nothing special in here, it simply extends ListView, and adds a bit more API for selectedIndexes and selectedItems, as well as a default cell factory if one isn’t specified by the user.

import javafx.scene.control.ListView;
import javafx.scene.control.ListCell;
import javafx.scene.Node;
import javafx.scene.control.Label;

public class MultiSelectListView extends ListView {

    public-read var selectedItems:Object[];

    public var selectedIndexes:Integer[] on replace {
        selectedItems = for (i in selectedIndexes) items[i];
    }

    override var cellFactory = function():ListCell {
        var label:Label;
        def cell:ListCell = MultiSelectListCell {
            onUpdate: function() {
                def item = cell.item;
                if (item == null) {
                    cell.node = null;
                } else if (item instanceof Node) {
                    cell.node = item as Node;
                } else {
                    if (label == null) {
                        label = Label { }
                    }
                    label.text = if (item instanceof String) then item as String else "{item}";
                    if (cell.node != label) cell.node = label;
                }
            }
        }
    }
}

Moving on, we come to MultiSelectListCell, which is where the real warning comes – this class has unpublished API being used, and we offer no guarantee that it’ll stay this way. Use it at your own risk, and seriously, don’t build your business around this API being available. You’ve been warned.

This class creates a custom MultiSelectListCellSkin, and binds to the selectedIndexes sequence to determine if it is selected or not. When this property changes, it calls some impl_ code to re-evaluate its state, to allow for the background selection colour to be turned on or off as necessary. The rest of the code is pretty straightforward (i.e. don’t question it)

import javafx.scene.control.ListCell;
import javafx.scene.control.Skin;
import com.sun.javafx.scene.control.skin.ListCellSkin;
import com.sun.javafx.scene.control.skin.SkinAdapter;
import javafx.util.Sequences;

public class MultiSelectListCell extends ListCell {

    def multiSelected = bind Sequences.indexOf((listView as MultiSelectListView).selectedIndexes, index) != -1 on invalidate {
        impl_pseudoClassStateChanged("selected");
    }

    package override function createDefaultSkin():Skin {
        SkinAdapter {
            rootRegion: MultiSelectListCellSkin { }
        }
    }

    override function impl_getPseudoClassState():String[] {
        [
            if (multiSelected) "selected" else null,
            super.impl_getPseudoClassState()
        ]
    }
}

MultiSelectListCellSkin is hidden inside MultiSelectListCell (for no particular reason), and its job is simply to just extend ListCellSkin, apply a small bug workaround, and apply a custom behavior, which is where the actual multiple selection magic happens.

class MultiSelectListCellSkin extends ListCellSkin {
    override var behavior = MultiSelectListCellBehavior { }

    postinit {
        // This fixes an issue where the mouseReleased function is called twice.
        overlay.onMouseReleased = null;
    }
}

The final class is a slight extension of the ListCellBehavior class, not surprisingly called MultiSelectListCellBehavior. This class handles the mouse click event, including determining if ctrl or shift is held down, and acting appropriately.

import com.sun.javafx.scene.control.behavior.ListCellBehavior;
import javafx.util.Sequences;

public class MultiSelectListCellBehavior extends ListCellBehavior {

    override function mouseReleased(e) {
        // Note that list.select will reset selection
        // for out of bounds indexes. So, need to check
        def listCell = skin.control as MultiSelectListCell;
        def listView = listCell.listView as MultiSelectListView;

        // If the mouse event is not contained within this ListCell, then
        // we don't want to react to it.
        if (listCell.contains(e.x, e.y)) {
            if (listCell.index >= sizeof listView.items) return;

            var row = listCell.index;

            if (e.controlDown) {
                if (Sequences.indexOf(listView.selectedIndexes, row) == -1) {
                    insert row into listView.selectedIndexes;
                } else {
                    delete row from listView.selectedIndexes;
                }
            } else if (e.shiftDown) {
                var start = listView.focusedIndex;
                var end = row;
                var range = if (start < end)
                    then [start..end] else [end..start];

                listView.selectedIndexes = range;
            } else {
                delete listView.selectedIndexes;
                insert row into listView.selectedIndexes;
                listView.focus(row);
            }
        }
    }
}

That’s all there is to it. Note that whilst I wrote this, because it is not a ‘production-quality’ control, I haven’t tested it at all, past a few user tests. I’m sure it’ll have issues. If you report them to me I’ll revise this post to ensure the best control we can have. You should also note that this in no way reflects how we’ll do multiple selection in the future, when it is supported ‘natively’.

Now, on to the warnings I warned you were coming. In general, don’t use the select() function any more – just directly manipulate the selectedIndexes sequence. Also, don’t use the selectedItem / selectedIndex properties any more – just use the selectedItems and selectedIndexes sequences instead. If you think you’re going to forget this, it should be possible to just keep overriding more functions / properties to have everything work as expected, but unless I feel sufficiently nagged, I’ll probably just leave this as a user exercise. Similarly, there is no support for keyboard navigation / multiple selection in this version.

So – that’s it really. You can download a NetBeans project containing this source code, or if you’re just wanting to use the code as-is, I’ve also put up a jar file for you to use directly in your own applications. Feel free to leave comments.

These days ‘Hello World’ has been replaced by building a Twitter client, so I’ve decided to frame this topic in terms of building a Twitter client. Because I don’t actually care about the whole web service side of thing, I’ve neglected to implement the whole ‘real data’ / web services aspect of it. If you want to see an actual running implementation with real data, have a look at William Antônio’s Twitter client, which is using this ListCell implementation.

So, in all the posts to this site related to cells, I’m sure you’ve probably come to appreciate the ways in which you should create a ListView or TreeView with custom cell factories. Therefore, what I really want to cover in this post is just the custom cell implementation, and the importance of caching. A Twitter client wouldn’t be a true client without showing the users profile image, so this is my target for caching. Without caching, each time the cell was updated (i.e. the content changes due to scrolling, or when we scroll a user out of screen and then back in), we’d have to redownload and load the image. This would lead to considerable lag and a poor user experience. What we need to do is load the image once, cache it, and reuse it whenever the image URL is requested by a cell. At the same time, we don’t want to run the PC dry of memory by loading all profile images into memory. Enter: SoftReference caching.

Word of warning: I’m not a caching expert. It is possible that I’ve done something stupid, and I hope you’ll let me know, but I believe that the code below should at least be decent. I’ll happily update this example if anyone gives me useful feedback.

Check out the code below, and I’ll continue to discuss it afterwards.

import model.Tweet;

import java.lang.ref.SoftReference;
import java.util.HashMap;

import javafx.geometry.HPos;
import javafx.geometry.VPos;
import javafx.util.Math;
import javafx.scene.control.Label;
import javafx.scene.control.ListCell;
import javafx.scene.image.Image;
import javafx.scene.image.ImageView;
import javafx.scene.layout.Container;
import javafx.scene.text.Font;
import javafx.scene.text.FontWeight;

// controls whether the cache is used or not. This _really_ shouldn't be false!
def useCache = true;

// map of String -> SoftReference (of Image)
def map = new HashMap();

def IMAGE_SIZE = 48;

public class TwitterListCell extends ListCell {

    // used to represent the users image
    var imageView:ImageView;

    // a slightly bigger and bolder label for the persons name
    var personName:Label = Label {
        font: Font.font("Arial", FontWeight.BOLD, 13);
    }

    // the message label
    var message:Label = Label {
        textWrap: true
    }

    override var node = Container {
        content: bind [ imageView, personName, message ]

        override function getPrefHeight(width:Number):Number {
            def w = listView.width;
            Math.max(IMAGE_SIZE, personName.getPrefHeight(w) + message.getPrefHeight(w));
        }

        override function doLayout():Void {
            var x:Number = -1.5;
            var y:Number = 0;
            var listWidth = listView.width;
            var cellHeight = height;

            // position image
            Container.positionNode(imageView, x, y, IMAGE_SIZE, cellHeight,
                HPos.CENTER, VPos.TOP, false);

            // position text at the same indent position regardless of whether
            // an image exists or not
            x += IMAGE_SIZE + 5;
            var textWidth = listWidth - x;
            var personNameHeight = personName.getPrefHeight(textWidth);
            Container.resizeNode(personName, textWidth, personNameHeight);
            Container.positionNode(personName, x, y, listWidth - x, personNameHeight,
                HPos.LEFT, VPos.TOP, false);

            y += personNameHeight;
            Container.resizeNode(message, textWidth, message.getPrefHeight(textWidth));
            Container.positionNode(message, x, y, listWidth - x, height - personNameHeight,
                HPos.LEFT, VPos.TOP, false);
        }
    }

    override var onUpdate = function():Void {
        var tweet = item as Tweet;

        personName.text = tweet.person.name;
        message.text = tweet.message;

        // image handling
        if (map.containsKey(tweet.person.image)) {
            // the image has possibly been cached, so lets try to get it
            var softRef = map.get(tweet.person.image) as SoftReference;

            // get the image out of the SoftReference wrapper
            var image = softRef.get() as Image;

            // check if it is null - which would be the case if the image had
            // been removed by the garbage collector
            if (image == null) {
                // we need to reload the image
                loadImage(tweet.person.image);
            } else {
                // the image is available, so we can reuse it without the
                // burden of having to download and reload it into memory.
                imageView = ImageView {
                    image: image;
                }
            }
        } else {
            // the image is not cached, so lets load it
            loadImage(tweet.person.image);
        }
    };

    function loadImage(url:String) {
        // create the image and imageview
        var image = Image {
            url: url
            height: IMAGE_SIZE
            preserveRatio: true
            backgroundLoading: true
        }
        imageView = ImageView {
            image: image;
        }

        if (useCache) {
            // put into cache using a SoftReference
            var softRef = new SoftReference(image);
            map.put(url, softRef);
        } else {
            map.remove(url);
        }
    }
}

You’ll note that in this example most of the code is pretty standard. A few variables are created for the image and text, and then I’ve gone the route of laying the content out in a Container, but you can achieve a similar layout using the available layout containers. Following this I have defined an onUpdate function, which is called whenever the cell should be updated. This is usually called due to a user interaction, which may potentially change the Cell.item value, which would of course require an update of the cell’s visuals.

The bulk, and most important part, of the onUpdate function deals with loading the users profile image, or retrieving and reusing the cached version of it. Note the use of the global HashMap, which maps between the URL of the users image and the Image itself. Because it is global (i.e. static), this map will be available, and used, by all TwitterListCell instances. Also important to note is that I didn’t put the ImageView itself into the HashMap as a Node can not be placed in multiple positions in the scenegraph, but an Image can be.

The rest of the code in this class really just deals with the fact that a SoftReference may clear out it’s reference to the Image object if the garbage collector needs the memory, in which case we need to reload the image again. The other obvious part is the need to also put the image into the cache if it’s not already there.

Shown below is the end result, but remember that there is a working version of this demo in William Antônio’s Twitter client, which is a very early work in progress.

I hope this might be useful to people, and as always we’re keen to hear your thoughts and feedback, and what you’re hoping us to cover. Until next time – cheers!