• Home
  • Events
  • About
  • JavaFX Abacus Tutorial, Part VII – proper structure with OpenDolphin

    March 3rd, 2013

    This is the seventh part of a basic tutorial on JavaFX. The other parts can be found here and the code is on github. The running example of the tutorial is to build an abacus. If you are curious how the final solution will look like, please
    have look at this 7 min video.

    Until part six, we have developed a nice-looking and basically functional abacus. It isn’t yet fully functional since the overflow rule is missing: when pushing balls to right and we come to the last available ball, we must push all balls on the current rail back to the left and add a ball in the rail above. You can see this effect in the video around the 1:50 timestamp. We could do this work just as manually as one does it with a physical abacus but it would be much more convenient if the application could do it for us – imagine how much easier it would be to calculate 999’999 + 1 if we had an automatic overflow (video).

    With this new requirement we have reached the limit where it no longer feels appropriate to

    • have all view and controller logic as well as starter configuration in one class
    • have controller logic working directly on the view without any model.

    Now, we could go the route of creating model classes like Board and Rail and Ball and work with observable lists and bindable properties (and I advice you give this approach a try) but that would mean that we model the domain while at the same time we make the domain aware of the view’s presentation technology (because of all the additional observable/bindable work).
    Let’s go for different approach, where we use presentation models with the help of OpenDolphin.

    Enter OpenDolphin

    OpenDolphin gives us a very clean structure with a clear separation of the following modules

    • client: only containing the view; depends on the view technology (JavaFX) and optionally on shared
    • server: only containing controller logic (actions), optionally depends on shared
    • shared: optionally share constants between client and server, depends on nothing
    • combined: starter configuration that depends on all the above

    There is a huge number of benefits that come with OpenDolphin but for the sake of brevity, we will only use a few of them. We can see a first obvious benefit from only looking at the dependency structure: the actions have no access to the view. The view and the view technology isn’t even on the classpath! No longer can you “accidentally” reach out from a controller onto a view. But how can an action do its work then?

    Presentation models are synchronized between client and server.
    Actions work on presentation models (CRUD operations).
    Views bind against presentation models and send commands to the controller.
    Presentation models are generic, i.e. we do not have to implement any specific class.

    Setting up

    Creating the modules and the dependencies may sound like a lot of work but there is a template that we have used to create the current codebase. The template is available from DolphinJumpStart where we used the dist/jumpstart-maven.zip, unzipped it to dolphinized, and changed the application name in the maven POMs.

    There also is a Gradle variant but if you are using Gradle, you will probably find your way around anyway.

    Abacus_Project_ViewTo get started, you best point your favorite IDE to the root pom.xml and let the IDE create a project for you.

    Tip: with multiple modules and source roots, it is often more convenient to use the “package view” (see screenshot on the right) than the classical directory view.

    Lifting the curtain

    AbacusStarter is the class with a main method that you use for starting the application. It sets up OpenDolphin with the in-memory mode since we currently run client and server in the same JVM (we can add remoting later). It also registers the AbacusDirector, which works a bit like a movie director: it tells what “actors” are in the play.

    After the setup, the AbacusStarter starts the show.

    And ” ACTION ! “

    We have two actions: the CreateBallsAction that initially creates a presentation model for each ball in the abacus, and the ToggleAction that is called when a ball is clicked.

    The gist of the CreateBallsAction creates a presentation model for each row/column combination:

    In the presentation model, we think in terms of “digits on a scale” and whether that digit is switched “on”. The view in contrast – which is only one of many possible views – uses the concept of balls sitting on a rail.

    The ToggleAction is a bit more involved as it contains two command handlers: one for toggling a digit (and its neighbors), and one for the overflow rule.

    The important point to note here is that the server knows, which ball has been touched on the client for toggling, because there is a special presentation model with the constant name PM_TOUCHED which is shared between client and server.

    The overflow rule is a value change listener on the server side that is triggered whenever a “leftmost” digit in switched to “on”.

    We get the nice effect that the overflow rule works separately from the toggling and that the proliferated overflow as in “99 + 1” comes automatically.

    The separation of the overflow rule in this manner is not quite as easy to achieve without OpenDolphin. One has to ensure a proper sequence of events: pushing the ball to the right, moving the ball in the rail above, moving all balls in the current row to the left. It is all-too easy to fall for a “sham solution” that occasionally leaves balls in the wrong position because they are first moved left and then to the right.
    OpenDolphin guarantees a proper event sequence – even though it executes all actions asynchronously.

    Simple View

    This leaves us with the AbacusApplication JavaFX view. It has been slimmed down to the bare essentials: displaying the presentation models, calling the toggle command when needed.
    Two points are of main interest: the start method and the click handler.
    The start method now looks as follows:

    Note that we create the touchedBall presentation model on the client side and we are sending the CMD_CREATE_BALLS command to the server. Only when that command is finished, we have all necessary presentation models on the client to bind against. Therefore, we provide an OnFinishedHandler that is called when the command has finished with all newly available presentation models.

    The click handler is now registered like so:

    When a ball is clicked we first have to update the touchedBall state before we send the toggle command. Updating via apply essentially copies all values from the ballPm over to the touchedBall presentation model.

    But wait – the toggle action (see above) changes that value of the touchedBall – not of the ballPm that was copied. How is the change propagated back?
    That is because of the qualifier that we have set when creating the presentation models. This qualifier has been copied as well and when a value changes, all presentation models with the same qualifier are updated to the same value.
    Such a construction is only possible because all OpenDolphin presentation models live in a managed object space. OpenDolphin is always in total control of all presentation models, can retrieve them by id or other features, and cares for consistent updates.


    This has of course only been a short introduction to OpenDolphin – or better not an introduction at all but a very special use case that can only show a very small fraction of its capabilities.
    I hope you found it useful and it made you curious to find out more.

    I planned this series to have 7 posts, which means we have now completed the curriculum. Congratulations!

    However, our final solution is so versatile, it would be a shame not to make use of it.
    It is has become simple to test the application logic (set/assert the presentation models), use other number systems (binary abacus anyone?), or make more use of cool JavaFX features to dramatically change the visual representation by solely changing the view. So don’t be surprised if you hear about post (8/7) in the near future.

    Please send me your questions/ideas/suggestions on twitter

    JavaFX Abacus Tutorial, Part VI – Styling

    February 14th, 2013

    This is the sixth part of a basic tutorial on JavaFX. The other parts can be found here and the code is on github. The running example of the tutorial is to build an abacus. If you are curious how the final solution will look like, please
    have look at this 7 min video.

    We have so far created the JavaFX abacus application without giving
    any thoughts to the visual appeal of the app.

    The good news is that JavaFX very nicely supports keeping functionality and
    display aspects apart by means of CSS styling. We can simply apply style classes to
    the various visual components and think about the actual visual properties later –
    or even provide multiple styles that the user can choose from.

    Styling comes in three steps:
    – assign style classes to the components
    – add a stylesheet to the scene
    – fill the stylesheet

    Adding a style class is easy. Each node has a getStyleClass() method that
    returns an observable list of Strings, each of which is a name of a style class such
    that we call

    BTW: the method name is a bit odd It should be named “getStyleClasses”.

    The various builders make this even easier with the builder method styleClass(“mystyle”).

    Second comes adding a CSS style sheet to the scene. Following the meanwhile
    expected JavaFX pattern this is done via

    The “/abacus.css” refers to a resource (file) that resides in the root of the classpath.
    That makes it easy to package your styles together with the application in the same
    jar file. There are more options for referring to styles like reading from external
    sources or even to define styles right in the code, which is conventionally called
    “inline styles”.

    Last not least, we have to fill the CSS stylesheet, which is pretty much the same
    experience like working with stylesheets for HTML. There are a few specialities
    though when it comes to the availability of style classes, selectors, property names,
    functions, and values.
    The JavaFX CSS Reference Guide is an indispensible resource to get this work done.

    Let us start with our black and white style:


    First, we set an overall background for the “root” style class that JavaFX applies
    to whatever happens to be the root node of your scene.

    This gives us a nice sand-like background. The circles shall get two different
    styles for easier counting: the ones on the left like bright, on the right like
    darker wood. The shall also appear like balls, i.e. three-dimensional.

    Making circles appear like balls either requires some elaborate
    lighting-, shadow-, and reflection-effects or just a clever gradient. Let’s go for
    the latter. Luckily, JavaFX gives us the radial gradient, which is perfect for
    that purpose.

    With the base color of “burlywood” for the darker balls and “papayawhip” for
    a not too prominent highlight color, we place the highlight a little lower (16%)
    than top-centered and let it shine on only the top half of the ball (radius 50%).
    The ball should also be not 100% solid but slightly transparent with a
    opacity of 80%.
    Now comes the coolest trick: when you place balls close to each other like in
    the abacus, then one ball’s highlight will slightly reflect on the ball in the
    rail above.


    As the painters say: “the shape is made from the light in the shadow”.

    We achieve this effect by using the “reflect” property of the
    radial gradient. This leaves us with the following style definitions:

    With this style, your abacus now looks like depicted below:


    Not too shabby, I would say. But there is more.

    Here comes another piece of painting knowledge: “every color also paints its

    We make use of that effect and change only one thing: the background – and we
    change it into a radial gradient from red to black.

    Doesn’t that instantly look like a casino’s red velvet furnishing and make the balls on their
    rails appear like shiny pearls?


    Personal tip: radial gradients in a rectangular frame often look spectacular.

    I hope that by now you are convinced that styles are very helpful and that with only
    minimal smart changes you can totally change the user experience of an application.


    Come up with your own styles and don’t forget styling for the rails.
    When a rail is selected – as to mark the baseline for calculations – it should
    get a “selected” style class.
    JavaFX CSS support the usual selector combinations such that you can specify the style
    for the selected rail as “.rail.selected { … }”.

    If you don’t want to see the digits, you can use the “transparent” color.

    Next week with Dolphin

    There still is an important piece of functionality missing: the automatic overflow.
    Next week will address this issue with the help of a presentation model and business
    logic that controls on it. We will use OpenDolphin to that end.


    If you are committed to learn JavaFX,
    please consider joining one of our JavaFX workshops at Canoo.

    If you plan to migrate any current application to JavaFX,
    please give us a call!

    See you next week!

    P.S. the GroovyFX version by Tim Yates.

    JavaFX Abacus Tutorial, Part V

    February 8th, 2013

    This is the fifth part of a basic tutorial on JavaFX. The other parts can be found here and the code is on github. The running example of the tutorial is to build an abacus. If you are curious how the final solution will look like, please
    have look at this 7 min video.

    Your latest homework was to think about possible solutions for pushing adjacent balls to the right or left just like a physical abacus does it mechanically.

    Now, what do you think?

    There are two typical solutions that students tend to come up with:

    • a full model with rails and balls with move actions that find out each ball that has to be moved
    • every ball listens for position changes of his neighbors

    The first approach requires quite some work while the latter keeps amount of state that has to be managed pretty small. It is also closer to what happens in the mechanical world. We will start with the listening to our neighbors.

    JavaFX provides a ChangeListener for that purpose. For the sake of simplicity we create a new one for every pair. It is cumbersome enough to define the anonymous inner classes and the final variables that Java requires.

    This code works surprisingly well. Before JavaFX I would have expected this solution to result in a recognizable jitter in the movement of the balls but they move perfectly smooth and synchronous as if we had used some elaborate cropping techniques.

    Here is the full code:

    We have now reached a state where we can really use the abacus for calculation. What is still missing is the “overflow” logic that we will add later – when we will also consider a presentation model for better structuring of the code.


    Play with the abacus!
    Do some calculations.
    Can you build the powers of 2 with your abacus?

    This abacus works but it doesn’t look nice, yet. We will explore styling options next week.


    If you are committed to learn JavaFX, please consider joining one of our JavaFX workshops at Canoo.

    See you next week!

    P.S. Tim Yates thankfully posted a GroovyFX version.

    JavaFX Abacus Tutorial, Part IV

    February 1st, 2013

    This is the fourth part of a basic tutorial on JavaFX. The other parts can be found here and the code is on github. The running example of the tutorial is to build an abacus. If you are curious how the final solution will look like, please
    have look at this 7 min video.

    Your latest homework was to add rails, which can easily be achieved with rectangles like so:

    We have now achieved a state where we can explore the powerful concept of JavaFX property binding and we will do so in two steps

    • today, we will add numbers that move together with their respective ball
    • next week, we will use property binding to push adjacent balls around.

    In an abacus, each ball represents a digit. Let’s add this digit as a text to each ball:

    The placement of the text is a bit off-center but since this is only a temporary step, we do not bother putting each ball and its text into an exactly aligned layout. (If you want, you can use StackPane for that.)

    You should now see each ball with a white label that tells the digit that it represents.

    Why is the text on top of the ball and not behind? That is because we add it to the scene graph after the ball. What is added later is printed on top. You can also use a z-position if you need more control.

    When you play with the current state of the program, you will find that the action handler that moves the ball seems to be ignored every now and then.
    The reason for this is that you have clicked on the text, not on the ball. The text node will then “consume” the event.
    The simplest way to resolve this is to give the text and the ball the same event handler:

    Ok, now the circles move reliably but the text doesn’t move together with its ball. But we would like to have a display like in the figure below:
    abacus with numbers

    JavaFX property binding comes to the rescue!
    Moving the ball by means of a TranslateTransition as we have done last week means that the translateX property of the circle will change over time.
    We want the translateX property of the text to change in the exact same way. We are binding both translateX properties.

    This finally leads us to the solution below:

    So far, so good, but one important piece of functionality is still missing: when starting and the user clicks on e.g. digit 5, all the digits 4, 3, 2, 1 should also move to the right. The equivalent needs to happen when subtracting by moving balls to the left.


    This weeks homework is a non-coding design exercise. Think about possible solutions for the pushing of adjacent balls.
    If you have followed the tutorial up to this point, you have all the knowledge to solve this task.


    If you are committed to learn JavaFX, please consider joining one of our JavaFX workshops at Canoo.

    See you next week!

    P.S. and – as it has become tradition – the GroovyFX solution by Tim Yates.

    JavaFX Abacus Tutorial, Part III

    January 21st, 2013

    This is the third part of a basic tutorial on JavaFX. The other parts can be found here and the code is on github. The running example of the tutorial is to build an abacus. If you are curious how the final solution will look like, please
    have look at this 7 min video.

    Today, we will enrich the current state of the project with animation.

    If you have done your homework – and I assume all of you have done so, right? –
    then you should have a solution like in the
    picture below where you can click on any ball and it will jump between its positions on the
    left and right hand side.

    circles with translations

    For moving the ball, we used a Translation, which as we learned is one of many possible

    Now, our current balls move in a rather weird fashion: they disappear from one location
    to reappear in a different location. Until we have star-trek like teleportation,
    this is an unrealistic behavior – and not very pleasing for the human eye.

    JavaFX allows us to let the ball move in an animated fashion with a so-called Transition.
    A Transition is an animation of a Transformation, in our case
    the animation of a Translation.

    Transitions have another interesting quality: they animate the transformation in
    a “natural” way. A physical ball would never start with zero velocity, then suddenly
    move at 10 km/h, and then stop instantly. It would accelerate and decelerate.
    Transitions mimic this behavior by animating the underlying transformation
    with an “ease-in” and “ease-out” by default.

    Setting up a transition is easy since their are first-class objects in
    JavaFX and can even be constructed with a builder:

    In order to execute the move do:

    With all that knowledge applied to our abacus implementation, the solution now becomes:


    Your homework assignment until next week is to also paint some rails where the balls can sit on.

    Next week we will start looking into JavaFX property binding.

    Have fun coding until then
    Dierk König

    P.S. the GroovyFX version by Tim Yates: here.