Start here: how every recipe fits together

IA tooling, not an exam topic. This page explains the FXML layout, controller and event-handler structure that every recipe in the cookbook uses, so read it before the recipes. Your IA must be your own work: adapt the examples to your project and acknowledge any code you reuse.

Every recipe in this cookbook touches the same two places. Once you know what they are and how they connect, every recipe reads the same way.

The two places you edit

The layout, in SceneBuilder. This is the .fxml file: the windows, buttons, text fields, tables, and labels the user sees. You arrange them by dragging in SceneBuilder, and SceneBuilder saves your screen as FXML.

The controller, in the .java file. This is the code that runs when the user does something: the logic behind a button, the checking of input, the saving of data. One controller class goes with one screen.

A recipe tells you what to do in each place, in that order: first the layout, then the controller.

How the two places connect

There are only two links you need to understand, and every recipe relies on them.

An fx:id connects a component to a field. When you give a component an fx:id in SceneBuilder, your controller can reach it through an @FXML field of the same name. The name must match exactly.

<!-- in the layout -->
<TextField fx:id="txtName" />

// in the controller
@FXML private TextField txtName;   // same name as the fx:id

An onAction connects a button to a method. When you set a button’s onAction in SceneBuilder, you name a method in the controller that runs when the button is clicked. The # is part of the FXML syntax.

<!-- in the layout -->
<Button text="Save" onAction="#handleSave" />

// in the controller
@FXML
private void handleSave() {
    // runs when the button is clicked
}

If a handler name in the FXML does not match a method in the controller, the screen will not load. If a field in the controller has no matching fx:id, that field stays null, and calling a method on it throws an error: if that code is in initialize(), the screen fails to load, and if it is in a handler, that click fails while the window stays open. An fx:id does not need a matching field, and one without a field causes no error. These are common mistakes, so the recipes remind you of them: check each FXML name against the controller.

The usual order when you add anything

Every recipe follows the same steps, so you always know where you are:

  1. Add the component in SceneBuilder.
  2. Give it an fx:id.
  3. If it is a button, set its onAction.
  4. Set any other properties it needs.
  5. Write the logic in the controller.

Where your work actually is

The recipes hand you the wiring: the layout, the field declarations, the handler methods, the standard JavaFX calls. That part is the same for everyone, so the cookbook gives it to you.

Your own work is the algorithms and design decisions of your product: how you process the data, the decisions your app makes, the logic that is yours. In the recipes that logic is marked inside the controller; in a larger program, the controller can call methods on your Model classes, where the rules about the data belong (see MVC Architecture). Every recipe marks the exact spot with a comment:

// your IA logic here

That line is the boundary between the reusable code around it and your own work. Replace it with the processing your application needs: that part is yours to design and write. Adapt the surrounding example as needed and acknowledge reused code in your documentation.

How to read a recipe

Each recipe is laid out the same way:

  • What this does and When you would use it in your IA: the goal and the plug-in point.
  • In SceneBuilder (the layout): what to add to the screen, and the fx:id or onAction to give it. If a recipe needs nothing in the layout, it says so.
  • In the controller (the .java file): the imports, the @FXML fields, and the handler code.
  • Where your own logic goes: the exact spot marked // your IA logic here.
  • Make it your own: which names and values to change.
  • Watch out for: the common mistakes, including the two wiring errors above.
  • Mix with: the recipes this one commonly combines with.

When you are ready, start with Controlling UI state, or jump straight to the recipe whose title names what you want to do from the cookbook overview.