Just Java

The behavior of the Timeline has changed for performance reasons in 1.3. Now the sequence containing the KeyFrames is only recalculated/updated if you call evaluateKeyValues manually.

But also the behavior has changed in another way:
I have a Timeline that contains an optional KeyFrame. When looking at the docs the timeline should simply skip a KeyFrame if the time is negative:

KeyFrames having time < 0s will be ignored by the Timeline.

Exactly what I am looking for. But never believe the documentation:

[cc lang="c"]
Timeline {
keyFrames: [
KeyFrame {
time: -1ms
action: function () {
throw new UnsupportedOperationException("aaah!");
}
}
]
}.playFromStart();[/cc]

This small snippet throws the exception… Any ideas or comments?

Here is a small template that helps you to create your own custom control without any problem:

Just paste this code into your fx file and rename the classes using the IDE you prefer…

[cc lang="c"]
public class MyOwnControl extends Control {
init {
if ( skin == null ) {
skin = MyOwnControlSkin {};
}
}
}

public class MyOwnControlSkin extends Skin {
def myBehavior = bind behavior as MyOwnBehaviour;
def myControl = bind control as MyOwnControl;

init {
behavior = MyOwnBehaviour{};

node = Rectangle {
width: bind control.width
height: bind control.height
}
}

override function getPrefWidth( number ) {
//return your pref width – hard coded values are ok for most cases
}

override function getPrefHeight( number ) {
//return your pref height – hard coded values are ok for most cases
}

/*
//It is not absolutly necessary to override those methods, but strongly recommended.
override function getMaxWidth() {
//Return the max width
}

override function getMaxHeight() {
//Return the max height
}

override function getMinWidth() {
//Return the min width
}

override function getMinHeight() {
//Return the min height
}*/

override function contains( localX: Number, localY: Number ): Boolean {
node.contains( localX, localY );
}

override function intersects( localX: Number, localY: Number, localWidth: Number, localHeight: Number ): Boolean {
node.intersects( localX, localY, localWidth, localHeight );
}
}

public class MyOwnBehaviour extends Behavior {
def myControl = bind skin.control as MyOwnControl;
}
[/cc]

The 1.3 release of JavaFX is a huge on. Many things have been improved. Also some incompatible API changes occured.

Creating Custom controls has been really hard in 1.2. I have created a template that did what it should. But with the 1.3 release this template does no longer work.

So here we go and look at the issues related to custom controls one more time…. It is the same setup: The custom control is placed within a Stack.

Empty control

We start with an empty control without a skin. The result is the same as in 1.2: Everything is 0.

Simple Control with and empty Skin

Now we create a control and assign an empty skin. This is done within the init-block since createNode no longer exists. This results in the same behavior as in 1.2: There are hard coded values for prefWidth/height that are queried by the stack, set as width/height of the custom control and reflected by the layoutBounds. The boundsInLocal are still (0/0/0/0).

The Stack implementation has been changed. In 1.2 the Stack resized all nodes that implement Resizable to fill the available space. The default behaviour in 1.3 is to use the prefWidth/height.
The old behavior can be achieved by overwriting getHFill()/getVFill.

Skin containing just a Rectangle

The skin returns a Rectangle {widht:70 height:150}. The layoutBounds are not affected in any way. But the boundsInLocal are bound to the bounds of the node.

The result looks different than in 1.2: But just because the control is not resized! As a result the rectangle is drawn somewhere near the middle (but not in the middle). The position of the upper left border of the rectangle is placed by the Stack using the layoutBounds (drawn in red) as initial value for calculation.

So the result might be a little bit “dangerous”: For skins that have boundsInLocal that are near the hard coded values for prefWidth/height (and therefore width/height and therefore layoutBounds) the layout might be “good enough”. So the missing connection between width/height and boundsInLocal could be overlooked…

Skin with prefWidth/Height methods

The implementation of the prefWidth/Height methods is crucial – as written before. It has the expected results: The width/height of the control (and as result the layoutBounds) are changed accordingly by the container.

Connecting the width/height of the rectangle

As written before it is necessary to bind the width/height of the rectangle to the width/height of the control. When this is done the result looks as expected.

Conclusion

Creating custom controls in JavaFX is still quite difficult. And the documentation is still very poor. The template has to be changed slightly (due the removal of the create method). I will do this after the weekend.

The default of the Stack has been changed (and I like that). So it uses the prefWidth/Height per default. While this is the better behavior (imho) it might hide the fact that you have forgotten to implement the getPrefWidth/Height methods.

Please Oracle: Make those methods abstract asap!

Binding is one of the biggest strengths of JavaFX. I really like that.

And now – with release 1.3 – it seems to work much better. At least some of the simplest cases now work as expected.

The main difference is, that now bindings are lazy by default. They are not evaluated every time a var has changed. This is a big performance improvement for many cases.

As (propably) everybody knows, since yesterday JavaFX 1.3 is available.

And I don’t like that new kind of release-date-will-be-a-surprise stuff. Google does it with Android. Oracle with JavaFX… At the same time the code is kept secretly.

I prefer an open source stack. Just to be independent if some big company uses its petty cash to buy some stuff… I have heard this has happened recently…

When assigning a new skin in the object literal of the control, it may be ignored if the control doesn’t take care of it.

Instead of the commonly used code:
[cc lang="c"]
override function create(): Node {
skin = MyOwnControlSkin { };
super.create();
}
[/cc]

it is necessary to check whether a skin has already been set:

[cc lang="c"]
override function create(): Node {
if ( skin == null ){
skin = MyOwnControlSkin { };
}

super.create();
}
[/cc]

I think the API should be improved! What about some kind of default skin? Abstract method? Function? Field?

I have updated the template accordingly.

Update:
This template is made for JavaFX 1.2! For 1.3 use the template posted here instead.

Here is a small template that helps you to create your own custom control without any problem:

[cc lang="c"]
public class MyControl extends Control {
override function create(): Node {
if ( skin == null ){
skin = MySkin{};
}
super.create();
}
}

public class MySkin extends Skin {
def myBehavior = bind behavior as MyOwnBehaviour;
def myControl = bind control as MyOwnControl;

init {
node = Rectangle {
width: bind control.width
height: bind control.height
}
behavior = MyOwnBehaviour{};
}

override function getPrefWidth( number ) {
//return your pref width – hard coded values are ok for most cases
}

override function getPrefHeight( number ) {
//return your pref height – hard coded values are ok for most cases
}

/*
//It is not absolutly necessary to override those methods, but strongly recommended.
override function getMinWidth() {
}

override function getMinHeight() {
}

override function getMaxWidth() {
}

override function getMaxHeight() {
}
*/

override function contains( localX: Number, localY: Number ): Boolean {
node.contains( localX, localY );
}

override function intersects( localX: Number, localY: Number, localWidth: Number, localHeight: Number ): Boolean {
node.intersects( localX, localY, localWidth, localHeight );
}
}

public class MyOwnBehaviour extends Behavior {
def myControl = bind skin.control as MyOwnControl;
}
[/cc]

Is is quite difficult to create custom controls in JavaFX that perform like they should. This is the result of lack of documentation, unavailability of source code and a not-so-good API…

I struggled with that issue for two days. And finally I think I understood the hole concept. I wrote about that process in this blog some days ago.

If you are just looking for a template, continue here.

Here is a small drawing that visualizes the relevant methods/fields related to custom controls:

width/height

The width and height are set by the container. The container calculates the width/height based on the values returned by getPrefWidth/Height and getMaxWidth/Height.

layoutBounds

The layoutBounds are calculated automatically based on the values of width/height of the control.

Attention: The layoutBounds do not depend on the layoutBounds of the node created by the Skin!

This might be counter-intuitive. But it is necessary since the Control is resizable. And therefore the layoutBounds have to depend on the width/size (which are set by the container).

boundsInLocal

The boundsInLocal are bound to the boundsInLocal of the node created by the skin. Just as you might have expected.

getMin/Pref/MaxWidth/height

The control delegates those method calls to the currently active Skin. At least it is necessary to implement the getPrefWidth/Height methods. The default implementation just returns hard coded values (100/50). If you don’t have implemented those methods, the layoutBounds of the control will be wrong. And this will result in odd layout behaviour of your custom node!

Which methods to extend? Which fields to bind?

There are two things you have to do:

Step 1: Override getPrefWidth/Height in Skin

This is *really* necessary. Those methods should have been made abstract. I can’t imagine any case where those methods don’t have to be overridden… So just override them. Returning hard coded values is ok for most cases.

Step 2: Bind the size of the node to Control#width/height

Whenever the layoutBounds of the control change, the size of the node must be adjusted. It depends on your implementation how the relationship might be. For simple nodes without any effects a simple bind should be enough:

[cc lang="c" escaped="true" tab_size="2" lines="20"]
class MySkin extends Skin {
init {
node = Rectangle {
width: bind control.width
height: bind control.height
}
}
…
[/cc]

Now you have created a custom Control that behaves as expected – and is resizable…

I have created a template to create custom a control and skin.

There are several misunderstandings related to bounds. (Amy Fowler tried to explain the layout mechanisms some days ago)

There are three bounds that can be used:

• layoutBounds – represent the *logical* bounds used to layout the node
• boundsInLocal – represent the *real* bounds used to paint the node
• boundsInParent – the boundsInLocal transformed to the coordinates of the parent.

And now there is simple stuff you should remember:

layoutBounds are used for layouting (only). They do not have anything to do with boundsInLocal. They are just a logical concept. Sometimes they are the same as the boundsInLocal. Sometimes they are smaller, sometimes larger.

Some examples

layoutBounds == boundsInLocal

This is the case for many very simple nodes. For example a rectangle without any effects like drop shadows.

layoutBounds < boundsInLocal

This is the case for nodes that have some type of effect – for example a drop shadow. That shadow must not be included into the layout. If the layout algorithm used the boundsInLocal (including the drop shadow) the nodes would look misaligned to the human eye.

Aligned using the layoutBounds:

Aligned using the boundsInLocal:

layoutBounds > boundsInLocal

This is the case if some parts of the node are (yet) invisible, but the human eye interpolates them:

If those Pacman like circles are aligned using the boundsInLocal this will result in:

While the human eye expects the alignment to be more like that:

Disclamier:

I know that this post does not contain many (if any) new informations. It is just a little bit shorter. And therefore might be helpful for somebody.

There are two ways how a custom control/node can be created. The simple way is to extend CustomNode. Then everything should work as expected.

The second possibility is to extend Control, Skin and Behaviour. This is the better way if you want to support different skins. And of course it seems to be the more MVC-like approach. Therefore I decided to try it that way…

Problems with the *bounds*

Implementing a new control seems to be very straight forward. Just follow the examples found everywhere. But if you try to use your newly created component, you probably be surprised…

If placing the control within a Stack, the control sticks to the upper left corner. It is not layouted as I expected. During debugging I realized that the layoutBounds look strange. They are not bound to the node created by the skin. Instead they seem to be hardcoded to 0/0/100/50.

But boundsInLocal seems to be okay…

Finding the reason..

So what can we do? Just taking a look at the source code of Control should be enough… But those sources are not available!

Okay, let’s find out on our own. I created a small scene containing a Stack with its width/height bound to the scene dimensions (800/600). That stack contains the custom control.

Step 1: Simple Control without any Skin

I created a control and I did not set a skin. What happened?

As expected, the layoutBounds and the boundsInLocal where both set to (0/0/0/0).

Step 2: Simple Control with an empty Skin

I now set a skin in create() of my Control. The skin does not do anything (node is null). Result?

The layoutBounds are initially set to (0/0/100/50)!
They are then adjusted to the size of the Stack (as expected?). The layoutBounds seem to be bound to width/height of the control, as expected when reading the jfxdoc for Resizable.
The boundsInLocal stay at (0/0/0/0).

Conclusion:

There exist hard coded default values for each control (100/50). Those are used for the inital layoutBounds and the prefWidth/Height.

Step 3: Skin containing just a Rectangle

The skin assigns a Rectangle {width:70 height:150} to the node in init.

The layoutBounds didn’t change: (0/0/800/600) – influenced by the Stack size. But the boundsInLocal are now calculated correctly based on the rectangle: (0/0/150/70).

The Rectangle is now painted in the upper left corner of the stack. This is not surprising since the Stack expects the Control to be much bigger (800/600).

The prefWidth/Height returns also the hard coded values of 50/100.

Conclusion:

The boundsInLocal are bound to the node created by the skin automatically. But the layoutBounds are bound to the width and size inherited by Resizable (correctly following the documentation). But there is missing a connection between the layoutBounds of the control and those of the node created by the skin.

Additionally the prefWidth/Height and min/max methods have to be connected to the skin.

Step 4: Create custom maxWidth/Height methods

The skin overrides the maxWidth/Height methods and returns 340/320. Since the control delegates to the skin the control don’t have to be modified.

The Stack now resizes the control to its maximum width/height. Therefore the control has a size of 340/320 that are reflected by the layoutBounds. The boundsInLocal stay at the “real” size of 150/70.

The positioning of the control is different now. The stack uses the changed layoutBounds for its calculations. Therefore the rectangle has been moved towards the center. But it is still not at the center (because the layoutBounds are larger than the drawn rectangle).

Resizing the scene changes the actual width/height and layoutBounds of the control. But of course the Rectangle keeps its size.

Step 5: Implement  minWidth/Height methods

Those methods return a minWidth/Height of 50/70.This does not have any effects. The Stack seems to ignore them. So the actual size of a control may become smaller than the values returned by the min-methods.

Step 6: Bind the Rect width/height to control.width/height

Since the control is resizable we bind the width/height of the Rectangle to the width/height of the control (that is modified by the Stack).

The control has the size of 340/320 (provided by getMaxWidth/Height). The rectangle has the same dimensions and therefore is placed at the center of the Stack.

The layoutBounds and the boundsInLocal are the same now. Resizing works as expected.

Step 7: Fixing getPrefWidth/Height

Now we want to adjust the preferred width and height. Therefore we override those methods. It is probably a good idea to delegate those requests to the skin… For now those methods return 110/90.

When the control is placed within a Group, the preferred size and with is used. Since the Group is not resizable the Stack can’t change the size.

The control is layouted with its preferred size in the center of the Stack.