JavaFX Tip 14: StackPane Children – Hidden But Not Gone

Another short tip: Swing provides a layout manager called CardLayout, which manages a set of components (cards) inside a container but always only shows one of them. The method CardLayout.show(Container, String) allows to switch between the components / the cards.

The same behaviour can be accomplished in JavaFX by using the StackPane, adding several children (each using the entire width and height of the pane) and calling the Node.toFront() method to switch between the children. However, there is one big difference: the StackPane will always layout all of its children, independent of wether they are currently showing or not. This might result in bad performance of your application and can be noticed when resizing the window that contains the pane.

My advice: manage your “cards” by adding them to or removing them from the scene graph. These operations are fast and flicker-free (this is JavaFX in Java 8, not Swing before Java 6).

JavaFX Tip 13: Study Modena CSS File

This is the easiest and shortest tip so far. If you want to do any of the following things:

  • learn how to use CSS
  • make your custom controls look like the standard controls
  • reuse an SVG path graphic used by a standard control (e.g. scrollbar arrows)
  • figure out how to navigate the structure of the standard controls
  • determine the color used for a specific item
  • consistently modify several standard controls

then simply take a look at the default CSS stylesheet that ships with JavaFX. The file is called modena.css and can be found in the jfxrt.jar file in this location: com/sun/javafx/scene/control/skin/modena/

e(fx)clipse 1.0 released

JavaFX Tip 12: Define Icons in CSS

When you are a UI developer coming from Swing like me then there is a good chance that you are still setting images / icons directly in your code. Most likely something like this:

import javafx.scene.control.Label;
import javafx.scene.image.ImageView;

public class MyLabel extends Label {

    public MyLabel() {
        setGraphic(new ImageView(MyLabel.class.
            getResource("image.gif").toExternalForm()));
    }
}

ImageExample

In this example the image file is looked up via Class.getResource(), the URL is passed to the constructor of the ImageView node and this node is set as the “graphic” property on the label.

This approach works perfectly well but with JavaFX there is a more elegant way. You can put the image definition into a CSS file, making it easy for your and / or others to replace it (once the marketing department has decided to change the corporate identity once again).

The same result as above can be achieved this way:

import javafx.scene.control.Label;

public class CSSLabel extends Label {

    public CSSLabel() {
        getStyleClass().add("folder-icon");
    }
}

Now you obviously need a CSS file as well:

.folder-icon {
	-fx-graphic: url("image.gif");
}

And in your application you need to add the stylesheet to your scene graph. Here we are adding it to the scene.

import javafx.application.Application;
import javafx.geometry.Pos;
import javafx.scene.Scene;
import javafx.stage.Stage;

public class MyApplication extends Application {

	public void start(Stage primaryStage) throws 
		                             Exception {
		CSSLabel label = new CSSLabel();
		label.setText("Folder");
		label.setAlignment(Pos.CENTER);
		
		Scene scene = new Scene(label);
		scene.getStylesheets().add(MyApplication.class.
		      getResource("test.css").toExternalForm());
		
		primaryStage.setScene(scene);
		
		primaryStage.setTitle("Image Example");
		primaryStage.setWidth(250);
		primaryStage.setHeight(100);
		primaryStage.show();
	}

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

With this approach you have a clean separation of your controls and their apperance and you allow for easy customization as well.

JavaFX Tip 11: Updating Read-Only Properties

Custom controls often feature “read-only” properties. This means that they can not be set from outside the control, not even from their own skin class. It is often the behaviour of a control that leads to a change of the read-only property. In JavaFX this behaviour can be implemented in the control itself and in the skin. So we sometimes end up with a skin wanting to update a read-only property of the control. How can this be done?

Backdoor: Property Map

The solution is quite simple: use the properties map of the control as a backdoor to the control class. The properties map is observable, so if the skin sets a value in the map then the control will be informed and can update the value of the read-only property itself.

The Control Class

The property in the control class might be defined like this:

private final ReadOnlyDoubleWrapper myReadOnly =
   new ReadOnlyDoubleWrapper();

public final ReadOnlyDoubleProperty myReadOnlyProperty() {
    return myReadOnly.getReadOnlyProperty();
}

public final Double getMyReadOnly() {
    return myReadOnly.get();
}

To update the property the control class registers a listener with its own property map and listens for changes to the property called “myReadOnly”:

getProperties().addListener(new MapChangeListener() {
  public void onChanged(Change c) {
    if (c.wasAdded() && "myReadOnly".equals(c.getKey())) {
      if (c.getValueAdded() instanceof Number) {
        myReadOnly.set((Double) c.getValueAdded());
      }
      getProperties().remove("myReadOnly");
    }
  }
});

Important: make sure to use a unique name for the property key or you might end up with naming conflicts. It is good practise to prefix the name with the package name of your control, e.g. com.myframework.myReadOnly.

The Skin Class

Now the skin class can update the property by setting the property value in the control’s property map:

getSkinnable().getProperties().put("myReadOnly", 42);

JavaFX Tip 10: Custom Composite Controls

Writing custom controls in JavaFX is a simple and straight forward process. A control class is needed for controlling the state of the control (hence the name). A skin class is needed for the apperance of the control. And more often than not a CSS file for customizing the apperance.

A common approach for controls is to hide the nodes they are using inside their skin class. The TextField control for example uses two instances of javafx.scene.text.Text. One for the regular text, one for the prompt text. These nodes are not accessible via the TextField API. If you want to get a reference to them you would need to call the lookup(String) method on Node. So far so good. It is actually hard to think of use cases where you would actually need access to the Text nodes.

But…

It becomes a whole different story if you develop complex custom controls. The FlexGanttFX Gantt charting framework is one example. The GanttChart control consists of many other complex controls and following the “separation of concerns” principle these controls carry all those methods and properties that are relevant for them to work properly. If these controls were hidden inside the skin of the Gantt chart then there would be no way to access them and the Gantt chart control would need to implement a whole buch of delegation methods. This would completely clutter the Gantt chart API. For this reason the GanttChart class does provide accessor methods to its child controls and even factory methods for creating the child nodes.

Example

The following screenshot shows a new control I am currently working on for the ControlsFX project. I am calling it ListSelectionView and it features two ListView instances. The user can move items from one list to another by either double clicking on them or by using the buttons in the middle. 

ListSelectionView 

List views are complex controls. They have their own data and selection models, their own cell factories, they fire events, and so on and so on. All of these things we might want to either customize or listen to. Something hard to do if the views are hidden in the skin class. The solution is to create the list views inside the control class via protected factory methods and to provide accessor methods.

The following code fragment shows the pattern that can be used:

public class ListSelectionView<T> extends Control {

    private ListView<T> sourceListView;
    private ListView<T> targetListView;

    public ListSelectionView() {
        sourceListView = createSourceListView();
        targetListView = createTargetListView();
    }

    protected ListView<T> createSourceListView() {
        return new ListView<>();
    }

    protected ListView<T> createTargetListView() {
        return new ListView<>();
    }

    public final ListView<T> getSourceListView() {
        return sourceListView;
    }

    public final ListView<T> getTargetListView() {
        return targetListView;
    }
}

The factory methods can be used to create standard ListView instances and configure them right there or to return already existing ListView specializations. A company called ACME might already provide a standard set of controls (that implement the company’s marketing concept). Then the factory methods might return a control called ACMEListView.

JavaFX Tip 9: Do Not Mix Swing / JavaFX

The JavaFX team has tried very hard to convince us that migrating from Swing to JavaFX is easy because of the option to embed Swing content in a JavaFX UI and vice versa. I must admit that I never tried it myself but based on the feedback I am getting from my customers I can only recommend to not mix Swing and JavaFX. At the time of this writing there were over 200 unresolved issues (120+ bugs) related to Swing integration (registered with the JavaFX issue management system).

Issue Types

The following is a list of issues that you might encounter if you still decide to go with it:

  • Appearance – there will always be a noticeable difference between the parts that were done in Swing and those that were done in JavaFX. Fields will show different font quality, different borders, different focus highlighting, etc….
  • Flickering – you might encounter flickering in your UI
  • Behaviour – controls will behave differently. The user will be able to scroll JavaFX controls with a gesture but not the Swing controls. The columns of a JavaFX TableView control will autosize when you double click the line between two column headers, the Swing JTable does not.
  • Threading – you are constantly dealing with issues related to the use of two different UI threads (the Swing EDT and the JavaFX application thread). You will run into freezing UIs and inconsistent state issues.
  • Window Management - controlling which window will be on top of which other windows and which window is blocking input (modality) for other windows becomes difficult / impossible. Popup windows might no longer hide themselves automatically.
  • Focus Handling- the wrong window might get the focus. Focus traversal between Swing controls and JavaFX controls might not work.
  • Context Menus – you might not be able to close the menu by clicking somewhere else in the UI or you might end up with two context menus open at the same time (one controlled by JavaFX, one controlled by Swing).
  • Cursor – setting different cursors on different controls / components will not work as expected.
  • Drag and Drop – wether within the SwingNode itself or between Swing and JavaFX, exceptions are heading your way.
  • Performance – the performance / rendering speed of JavaFX controls mixed with Swing components will degrade

Conclusion

What does this mean now? Well, it means that in the end you will not save time if you are following the Swing/JavaFX mixing strategy. At least not if quality is important to you. If your focus is only on making features available then maybe, but if you want to ship a commercial grade / professional application, then no.

If you have already decided to migrate to JavaFX, then do the Full Monty and redo your entire application in JavaFX, it is worth the wait.