How to Get Started (FAST!) with JavaFX 2 and Scene Builder

Hit the ground running with JavaFX and Scene Builder.

A question often asked is, "How do I get started with JavaFX and Scene Builder?" Like most tools and toolsets, there are as many ways to use these implements as there are developers--but shouldn't there be an easy way to "hit the ground running"? JavaFX is a new paradigm and can seem a bit imposing when you first take a look at it. But remember, JavaFX is easy and fun. Let's give it a try.

First, you'll need to gather your tools. To do that, just visit this page to download and install all the necessary goodies. From the landing page, click the download link to go to the current downloads page, and then download and install JavaFX 2.2. (Note: If you already have a JDK installed that includes JavaFX, for example, JDK 7u6 or higher, you can omit this step.)

Then download and install JavaFX Scene Builder 1.0. Specific instructions for these steps are located on that page.

Once you've downloaded and installed the JDK/JavaFX and Scene Builder, it's a good idea to fire up the Scene Builder to verify that it loads properly. If it does not, you'll want to revisit the installation instructions on the downloads page and make the necessary adjustments.

Once Scene Builder is working, you're ready to roll—assuming you're running NetBeans 7.2 or higher, of course. If you aren't running NetBeans 7.2 or higher, you owe it to yourself to download it; it's free and, as you're about to see, it goes a long way toward making you a more productive (and happier) developer. NetBeans and Scene Builder are loosely but effectively integrated, and using both greatly simplifies things and makes your life so much easier.

Okay, here's the fun part: We're going to actually create a simple JavaFX application, create and modify a window using Scene Builder, and successfully test it all in under 15 minutes.

NetBeans

We start this adventure with NetBeans. Choose File->New Project, choose JavaFX, and then choose JavaFX FXML Application (see Figure 1). This creates a very simple JavaFX app that includes a main application class, a controller class to provide the actual backing logic for the window defined in Scene Builder, and the FX Markup Language (FXML) file containing our window definition (XML) code.

Figure 1. Creating a Simple JavaFX Application

I used "EasyJavaFX" for our project name (see Figure 2).

Figure 2. Naming the Project

Here's a quick summary of the three files (see Figure 3):

• EasyJavaFX.java contains the main application class. We won't do anything with this class for our example, because its primary purpose in life is to load the window definition code contained in the FXML file and then show the main stage/scene. You'll keep the JavaFX terms straight with ease if you relate them to a theater: a platform holds a stage, which contains scenes.
• SampleController.java is our controller class, which provides the "brains" behind the graphical interface. If you open the SampleController, you'll see that it includes a property and a method tagged with @FXML. This tag enables the integration of the visual controls and elements you define using Scene Builder, which are stored in an FXML file.
• Sample.fxml is the definition file for our sample window. You can right-click and edit the file name in the tree to view the underlying FXML—and you may need to do that if you change file names or properties by hand—or you can double-click it to open it (visually) in Scene Builder. We'll take a look at that next, but first a quick look at our little project.

Figure 3. Project Files

Scene Builder

Opening Sample.fxml in Scene Builder results in the display of a very spartan window (see Figure 4).

Figure 4. Scene Builder Window

Let's rework it a little. For a complete walkthrough of Scene Builder, see the JavaFX Scene Builder User Guide, but here's the nickel tour: stuff and navigation to the left, picture in the middle, and properties on the right. We'll make some small modifications as follows.

First, click the entry for Button in the Hierarchy panel (bottom left), which selects the button in the middle Content panel. Move it down and over a bit to make room for the second button (see Figure 5).

Figure 5. Adding a Button

Next, let's drag another button from the Library panel (top left) and drop it onto the canvas, lining it up with the first button using the red positioning lines that appear while dragging it (see Figure 6).

Figure 6. Adding a Second Button

Once the new button is positioned, we turn our attention to the Properties panel on the right. We'll assign our new button an fx:id of exitButton, change the text to Exit, and the tab out of the field to see our changes dynamically applied.

Next, we click the original button to change its fx:id to clickmeButton and change its text to "Click Me for an Important Announcement." Finally, we click the Exit button and resize it to make it a bit wider for ease of use.

We're nearly done with our first round with Scene Builder. To finish, we select the Label in the Hierarchy panel at the bottom left—that's often the quickest way to locate "hidden" visual controls—and then resize it using the sizing handles on the canvas, again using the red lines to line up with edges and buttons. Once we're done, things should look something like Figure 7.

Figure 7. Final State

Click File->Save to save our changes. Scene Builder confirms the action with a brief message at the top of the Content panel. We're done with Scene Builder for the moment, but we needn't close it. Remember the "loose integration" I mentioned earlier between NetBeans 7.2 and Scene Builder 1.0? You can leave both open while switching between them, like we're going to be doing, and both tools happily remain in sync. Isn't it wonderful when tools work together? Now, let's return to NetBeans for the next step.

Back to NetBeans

Let's make a few changes to the controller class. Opening SampleController.java, we start with the only method we (currently) have. Since we now have two buttons, we will need to keep two methods straight. Renaming handleButtonAction to something like handleClickmeButtonAction is a good start. And to add something of significance to read when the button is clicked, we'll replace the wonderfully traditional "Hello World!" with "Space... the Final Frontier. These are the voyages of the starship Enterprise. Its continuing mission: to explore strange new worlds, to seek out new life and new civilizations, to boldly go where no one has gone before." For those few reading this who don't know about Star Trek or aren't Star Trek fans, my apologies—but it is a classic.

Next, we'll create a method for our Exit button by either copying and renaming our other method or creating the method from scratch. Either way, be sure to include the @FXML tag to allow for integration with our window definition/Scene Builder. Putting the following line in our new handleExitButtonAction method will give us a quick escape hatch for our demo app:

Platform.exit();

To fix the error shown by NetBeans, click the light bulb to the left of the code line and allow it to import javafx.application.Platform. Click the Save All button, and we're good to go from the NetBeans side. Now it's back to Scene Builder to wrap things up.

And Back to Scene Builder

In order for our buttons to "connect" with our new methods, we need to provide the buttons with the names we gave those methods in our SampleController class. First, select the top button (clickmeButton) in the Hierarchy panel.

Next, we turn our attention to the Properties panel on the right. At the bottom of the right side is a collapsed section labeled "Code: Button." Clicking that section header opens the Code properties window so we can update the OnAction property. Notice it still points to the method formerly known as handleButtonAction. Click the dropdown, select handleClickmeButtonAction, tab out of the field, and we're done with that button.

We repeat some of the same steps with the other (Exit) button, although since we already have the Code properties panel open, selecting the button takes us directly there. Choose handleExitButtonAction from its OnAction dropdown and tab out of the field to conclude our work with the Exit button.

There is one more cosmetic step. Since we added a lot of text to our label (see the handleClickmeButton method in the SampleController class), we might want to change the default behavior of our display label. Labels default to using an ellipsis when the length of their text exceeds the width of the control (see Figure 8), but we want to see the text in its entirety. Click the Wrap Text checkbox in the label's Properties panel to fix that and conclude our work in Scene Builder. Click File->Save, and then let's go back to NetBeans for our maiden voyage!

Figure 8. Text Overrun Setting

And Now Back to NetBeans for the Big Finale!

Right-clicking the project in the Projects window to the left and clicking Run provides the satisfying results shown in Figure 9.

Figure 9. Outcome of Running the Project

Clicking the Click Me button displays the text shown in Figure 10.

Figure 10. Outcome of Clicking the Click Me Button

And clicking the Exit button closes the application.

Start to finish, you just developed a JavaFX application using Scene Builder in less time than it takes to drink a cup of coffee, while learning your way around in the process. Fast, fun, and productive: THAT is JavaFX.

Extra Credit

You might ask, "How do I show a second window? How do I present different content groups? Where are the dialogs?" There are several ways to address these needs, but here are a few suggestions.

If you need to visually group related content or controls within a single display, consider one of the various layouts available. See the Pane class in the JavaFX API documentation for more information.

For further segmenting content and controls, the TabPane control might be a useful option. TabPane allows you to show only a subset of content at any given time.

If you need an easy-to-implement dialog box solution with customizable buttons and flexible handling of user selections, check out DialogFX, currently in the JFXtras Labs library (available via jfxtras.org or available directly from GitHub).

If none of these options satisfies your needs, you'll want to consider becoming your own "stage manager"—handling one or more stages, multiple scenes, and interactions between them.

See Also

• Mark Heckler's blog
• JavaFX
• NetBeans

About the Author

Mark Heckler is an Oracle Corporation Java/Middleware/Core Tech Engineer with development experience in numerous environments. He has worked for and with key players in the manufacturing, emerging markets, retail, medical, telecom, and financial industries to develop and deliver critical capabilities on time and on budget. Currently, he works primarily with large government customers using Java throughout the stack and across the enterprise.

Mark lives with his very understanding wife, three kids, and dog in the St. Louis, Missouri area.

Join the Conversation

Join the Java community conversation on Facebook, Twitter, and the Oracle Java Blog!