The GroovyFX Guide

1. Introduction

Please note that this documentation is still under construction. There are a lot of missing pieces.

Client-side Java development took a major step forward with the introduction of Oracle’s JavaFX library. JavaFX is a modern, rich client technology stack that enables Java developers to quickly and easily create desktop clients with functionality and richness that rival, and even surpass, that of native clients and web applications.

GroovyFX is a library that makes working with JavaFX much simpler and more natural. GroovyFX is focused on exploiting the power of the Groovy language to make JavaFX development easier and more concise than what is possible in Java. GroovyFX also leverages Groovy’s powerful DSL features and AST transformations to eliminate boilerplate, making GroovyFX code easier to write and, just as importantly, easier to read.

GroovyFX provides the SceneGraphBuilder object, which offers support for:

All of the JavaFX core controls
All of the core JavaFX layout containers
Shapes, colors, and gradients
Video and audio (including H.264 support)
Bar charts, line charts, pie charts, and the rest of core JavaFX charts
Full property and binding support
The @FXBindable annotation, which eliminates the boilerplate required to define JavaFX properties

All of these are made easy to use through the power of the language and the extensive use of Domain Specific Languages (DSLs). This documentation will take you from getting started with GroovyFX all the way to building full applications with the power of JavaFX and Groovy.

1.1. The GroovyFX Committers

The GroovyFX team is made up of the following core committers.

Jim Clarke
Dean Iverson
Dierk König
Andres Almiray
Russel Winder
Danno Ferrin

1.1.1. Other Contributions

We would also like to thank and recognize the following people who have contributed pull requests to GroovyFX.

Tobias Schulte, nested tableColumn support

2. Getting Started

2.1. What’s New in Version 8.0.0

GroovyFX version 8.0.0 includes support for Groovy 2.4, Java 8, and JavaFX 8 only. This version does not work with JavaFX 2. It's strongly recommended to use Java8u60 as a minimum.

2.1. What’s New in Version 0.4.0

GroovyFX version 0.4 includes support for Groovy 2.3, Java 8, and JavaFX 8.

2.2. What’s New in Version 0.2.0

GroovyFX version 0.2 has a number of fixes, new functionality, and other enhancements. This includes some changes that are incompatible with version 0.1. See the Breaking Changes section below for details on these changes.

2.2.1. Improvements

The following JavaFX 2.1 and 2.2 features have been added:

DirectoryChooser
ComboBox
StackedBarChart and StackedAreaChart
Canvas

Other improvements:

Usage of Node IDs
Actions
Nested Table Column Support
onSelect Pseudo-Property Added to ListView, TreeView, ComboBox, ChoiceBox, and TabPane
Cell Factory Support

2.2.2. Breaking Changes

The following changes are not backwards compatible with previous versions.

New usage of GroovyFX and SceneGraphBuilder classes
New Binding
TimelineBuilder went away

2.3. Installation Requirements

Before installing GroovyFX you will need to install the Java Development Kit (JDK) version 1.6 or above.

Download the appropriate JDK for your operating system, run the installer, and then set up an environment variable named JAVA_HOME pointing to the location of this installation.

2.4. Using the GroovyFX Library

There are several ways in which you can include GroovyFx in your projects.

2.4.1. Maven Central

Having GroovyFX in Maven Central (thanks to Sonatype’s OSS hosting!) makes it simple to use GroovyFX in everything from simple test scripts to larger projects. The Maven coordinates are as follows

groupId: org.groovyfx
artifactId: groovyfx
version: 8.0.0

GroovyFX is simple to inlude in Groovy scripts thanks to Groovy’s Grab annotation, a part of the Grape system. Just include the following line at the top of your script

Testing.groovy
@Grab('org.groovyfx:groovyfx:8.0.0')

2.4.2. Creating a GroovyFX-Based Project with Gradle

It is also simple to set up your own GroovyFX-based project using Gradle as the build system. This sample build.gradle script will get you started.

apply plugin:'groovy'

project.ext.set('javafxHome', System.env['JAVAFX_HOME']

repositories { mavenCentral() }

dependencies {
    groovy 'org.codehaus.groovy:groovy-all:2.4.6'
    compile 'org.groovyfx:groovyfx:8.0.0'
    compile files("${javafxHome}/rt/lib/jfxrt.jar")
}

task run(type: JavaExec) {
    main = 'helloGroovyFX'
    classpath sourceSets.main.runtimeClasspath
}

task makeDirs(description:'make all dirs for project setup') << {
    def sources = [sourceSets.main, sourceSets.test]
    sources*.allSource*.srcDirs.flatten().each { File srcDir ->
        println "making $srcDir"
        srcDir.mkdirs()
    }
}

task wrap(type:Wrapper, description:"create a gradlew") {
    gradleVersion = '2.12'
}

Just create a new directory for your project and place the gradle script into it. Then simply call

gradle makeDirs

to set up the rest of your project’s directory structure. You will automatically have a dependency on both Groovy and GroovyFX.

2.5. Building from Source

The project’s source code is located on GitHub. You can clone the GroovyFX repository using the following Git command

git clone git://github.com/groovyfx-project/groovyfx.git

2.5.1. Installation Requirements

JDK8u60 is the minimum version recommended to build a working version of GroovyFX.

2.5.2. Building with Gradle

GroovyFX uses Gradle as its primary build system. Building the project with Gradle requires only the following simple steps

cd groovyfx
gradlew build

The Gradle build script is also capable of running any of the project’s demo. To run any specific demo, e.g.the AccordionDemo, you can just use

gradlew AccordionDemo

To see an executable overview of all build tasks including all demos

gradlew --gui

2.5.3. Building with Intellij IDEA

GroovyFX’s build script is capable of generating all of the project files neccessary to build the project with Intellij IDEA. Just run the following command from the project’s root directory

gradlew idea

This will generate a groovyfx.ipr file. From IDEA, select File → Open Project and navigate to the directory containing the groovyfx.ipr file and open it. You should now be able to build the library and run the demos with IDEA.

2.5.4. Building with NetBeans

The NetBeans project files are included in the code repository. You may have to set up a Java Platform that includes the JavaFX SDK directory, if one does not already exist. Please see Setting Up NetBeans IDE With JavaFX 2.1 for more information.

Once you have created the JavaFX enabled Java platform, then choose the GroovyFX project, right click and pick "Properties". Choose the "Libraries" entry, then choose the JavaFX enabled Java Platform. You should now be able to build the library and run the demos with NetBeans. Also, you may have to fix the location for the groovy-all jar file.

2.6. Hello GroovyFX: Your First GroovyFX Program

Once you have everything set up, try the following Groovy script to test that your setup is functioning as it should.

@Grab('org.groovyfx:groovyfx:8.0.0')

import static groovyx.javafx.GroovyFX.start

start {
    stage(title: 'GroovyFX Hello World', visible: true) {
        scene(fill: BLACK, width: 500, height: 250) {
            hbox(padding: 60) {
                text(text: 'Groovy', font: '80pt sanserif') {
                    fill linearGradient(endX: 0, stops: [PALEGREEN, SEAGREEN])
                }
                text(text: 'FX', font: '80pt sanserif') {
                    fill linearGradient(endX: 0, stops: [CYAN, DODGERBLUE])
                    effect dropShadow(color: DODGERBLUE, radius: 25, spread: 0.25)
                }
            }
        }
    }
}

If everything runs correctly you should see the following screen appear.

helloWorld

3. Basic Concepts

In JavaFX, you display graphics and controls on the screen by constructing a scene graph that consists of various types of nodes - perhaps a circle or a button control. The scene graph is put into a Scene, which defines the area in which your scene graph will be displayed. The Scene can then be shown on a Stage. You can think of a Stage as the application container. If your applicaiton is running on the user’s desktop, the Stage corresponds to a desktop window that typically has a title bar and resizing controls. If your application is embedded into a browser, then the Stage corresponds to the applet’s display area.

This arrangement of Stage → Scene → Scene Graph is a hierarchy of nodes that can be described nicely using a declarative format:

stage(title: 'GroovyFX', show: true) {
    scene {
        rectangle(width: 300, height: 100, fill: GREEN)
    }
}

Except for one other minor detail which we’ll cover in the next section, this is a complete GroovyFX program that, when run, will produce the output below.

firstapp

You can see that we declare a stage with a title attribute of GroovyFX and a show attribute set to true. The title of the stage appears as the text in the application window’s title bar (since this was run as a desktop application). The value of the show attribute controls whether the Stage (the window) will initially be visible. If you leave out the show attribute, its default value will remain false and your applicaiton will be invisible!

The scene node is declared as a child of the stage node - that is, it appears within the stage’s curly braces. Those curly braces actually define the stage’s closure, and any node declared within that closure will become a child node. A rectangle declaration appears within the scene’s closure, making the rectangle a child of the scene and the one and only node that makes up the entire scene graph in this application.

Those are the only two basic concepts you need to know in order to build rich user interfaces with GroovyFX. You describe the structure of your scene declaratively using closures to indicate the hierarchy of your nodes. You pass attributes to those nodes using Groovy’s key: value syntax (the same syntax used to declare key/value pairs in Maps literals - in fact, under the covers you are really passing a Map as an argument to each node).

This sort of syntax is generally usefull for declaring any kind of hierarchical data such as HTML or XML. It is so common that Groovy has built-in support for easily creating classes, called Builders, that allow you to write code using this syntax. Groovy’s MarkupBuilder, for example, allows you to easily create HTML documents using a very similar syntax.

It is probably not surprising, then, that the class we have created to allow you to declare JavaFX scene graphs using Groovy’s builder syntax is called SceneGraphBuilder.

A Note on Terminology

The nodes in a scene graph are generally referred to as, well… nodes. When you create a Groovy Builder, the elements that you can declare with the builder are also referred to as nodes. In most cases, this won’t cause us any confusion because the JavaFX scene graph nodes all have a corresponding GroovyFX SceneGraphBuilder node, and therefore the term node can be used interchangabely.

In those rare cases where we need to make a distinction, we will explicitly refer to builder nodes rather than simply scene graph nodes.

3.1. Using SceneGraphBuilder

Although SceneGraphBuilder provides all of the builder nodes you will use when creating your GroovyFX graphics and UIs, you will rarely use it directly. This is because you will typically begin your applications by calling the static start method of the GroovyFX class as shown here.

import static groovyx.javafx.GroovyFX.start

start {
    stage(title: 'GroovyFX', show: true) {
        scene {
            rectangle(width: 300, height: 100, fill: GREEN)
        }
    }
}

The GroovyFX.start method takes a closure as its only parameter and, behind the scenes, it initiates JavaFX’s startup sequence. The start method also ensures that the closure you pass will be executed at the appropriate time during the JavaFX startup sequence. Just before your closure is executed, the start method creates a new SceneGraphBuilder object and sets it as the closure’s delegate. This is the reason that you can call SceneGraphBuilder methods like stage, scene, and rectangle within your closure. Those calls will be automatically forwarded on to the closure’s delegate SceneGraphBuilder object when they are not found within the closure’s current scope.

Calling the GroovyFX.start method is the missing piece of the puzzle we referred to in the previous section when we first presented this code.

The following sections describe some of the generalized behavior supported in the SceneGraphBuilder on all nodes and attributes defined in the User Guide.

3.2. Node and Property Names

The following table contains a list of all the GroovyFX node names and their corresponding JavaFX class names.

GroovyFX Node

JavaFX Class

Parameter List

stage

javafx.scene.Stage

(args, scene)

popup

javafx.stage.Popup

(args)

fileChooser

javafx.stage.FileChooser

(args)

filter

javafx.stage.FilterChooser.ExtensionFilter

(args)

scene

javafx.scene.Scene

(args, body)

stylesheets

java.util.List

(args)

group

javafx.scene.Group

(args, body)

pane

javafx.scene.layout.Pane

(args, body)

stackPane

javafx.scene.layout.StackPane

(args, body)

anchorPane

javafx.scene.layout.AnchorPane

(args, body)

borderPane

javafx.scene.layout.BorderPane

(args, body)

flowPane

javafx.scene.layout.FlowPane

(args, body)

hbox

javafx.scene.layout.HBox

(args, body)

vbox

javafx.scene.layout.VBox

(args, body)

tilePane

javafx.scene.layout.TilePane

(args, body)

gridPane

javafx.scene.layout.GridPane

(args, body)

row

groovyx.javafx.factory.GridRowColumn

(args, body)

column

groovyx.javafx.factory.GridRowColumn

(args, body)

constraint

groovyx.javafx.factory.GridConstraint

(args)

top

groovyx.javafx.factory.BorderPanePosition

(args, body)

bottom

groovyx.javafx.factory.BorderPanePosition

(args, body)

left

groovyx.javafx.factory.BorderPanePosition

(args, body)

right

groovyx.javafx.factory.BorderPanePosition

(args, body)

center

groovyx.javafx.factory.BorderPanePosition

(args, body)

node

javafx.scene.Node

(args, body)

nodes

java.util.List

(list)

container

javafx.scene.Parent

(args, body)

fxml

javafx.scene.Node

(args, body)

mediaView

javafx.scene.media.MediaView

()

mediaPlayer

javafx.scene.media.MediaPlayer

()

imageView

javafx.scene.image.ImageView

()

image

javafx.scene.image.Image

()

menuBar

javafx.scene.control.MenuBar

(args, body)

contextMenu

javafx.scene.control.ContextMenu

(args, body)

menuButton

javafx.scene.control.MenuBar

(args, body)

splitMenuButton

javafx.scene.control.MenuBar

(args, body)

javafx.scene.control.MenuBar

(args, body)

menuItem

javafx.scene.control.MenuBar

(args, body)

checkMenuItem

javafx.scene.control.MenuBar

(args, body)

customMenuItem

javafx.scene.control.MenuBar

(args, body)

separatorMenuItem

javafx.scene.control.MenuBar

(args, body)

radioMenuItem

javafx.scene.control.MenuBar

(args, body)

button

javafx.scene.control.Button

(value)

checkBox

javafx.scene.control.CheckBox

(args, body)

label

javafx.scene.control.Label

(value)

choiceBox

javafx.scene.control.ChoiceBox

(args, body)

hyperlink

javafx.scene.control.Hyperlink

(args, body)

tooltip

javafx.scene.control.Tooltip

(args, body)

radioButton

javafx.scene.control.RadioButton

(args, body)

toggleButton

javafx.scene.control.ToggleButton

(args, body)

scrollBar

javafx.scene.control.ScrollBar

(args, body)

scrollPane

javafx.scene.control.ScrollPane

(args, body)

slider

javafx.scene.control.Slider

(args, body)

separator

javafx.scene.control.Separator

(args, body)

textArea

javafx.scene.control.TextArea

(args, body)

textField

javafx.scene.control.TextField

(args, body)

progressBar

javafx.scene.control.ProgressBar

(args, body)

progressIndicator

javafx.scene.control.ProgressIndicator

(args, body)

listView

javafx.scene.control.ListView

(args, body)

tableView

javafx.scene.control.TableView

(args, body)

tableColumn

javafx.scene.control.TableColumn

(args)

tableRow

javafx.scene.control.TableRow

(args)

treeView

javafx.scene.control.TreeView

(args, body)

treeItem

javafx.scene.control.TreeItem

(args, body)

accordion

javafx.scene.control.Accordion

(value)

titledPane

javafx.scene.control.TitledPane

(args, body)

splitPane

javafx.scene.control.SplitPane

(args, body)

dividerPosition

javafx.scene.control.DividerPosition

(args, body)

tabPane

javafx.scene.control.TabPane

(args, body)

tab

javafx.scene.control.Tab

(args, body)

toolBar

javafx.scene.control.ToolBar

(args, body)

title

groovyx.javafx.factory.Titled

(body)

content

groovyx.javafx.factory.Titled

(body)

graphic

groovyx.javafx.factory.Graphic

(body)

onBranchCollapse