Written by David Kaspar, adapted and maintained by Jeffrey Rubinoff
By using JavaFX fragments, you can create parts of your GUI design in separate files. You then embed these fragments into your Main.fx master file. JavaFX Fragments simplify the creation of complicated GUI applications, because you do not have to create and configure all UI components in a single file.
JavaFX Fragments are an advanced feature. Be certain you understand templates, states, properties, and generated source code before you attempt to use Fragments. See the basic tutorials on the JavaFX wiki.
Contents
To complete this tutorial, you need the following software and resources.
For the purposes of this tutorial, you need a JavaFX Desktop application.
To create the application and a Fragments file:
The Navigator window has no "Design File > scene [Scene]" node. Instead, there is a "Design File > Design Fragments" node. Select this node in the Navigator window or in the background of the Design view. The Design view displays "Design Fragments" as the edited scope. The viewport switches to the "Desktop Infinite" profile. The Properties window shows properties of the "Design Fragments" node. The properties of the fragments design file will be described later.
Switch to the Source tab and expand the folded code. The Fragments class currently represents an empty design.
The code generated in the guarded section (on a gray background) has neither a scene variable nor a getDesignScene function. You can generate a scene variable or a getDesignScene function in the Properties window for the Design Fragments. This converts the Design Fragments file to a Main design file. See Interconverting Fragments Design Files and Main Design Files. context menu of the Fragments file node in the Projects window or press Shift-F6 while you are in the editor.
You can delete the run function at any time. It is not necessary for your application, because the application uses the run function in the Main design file. For the purposes of this tutorial, do NOT delete the "run" function now.
Switch back to the Design view. In this section, you add and configure UI components to the Fragments file.
To design the fragments:
The Design Fragments file is now complete. The file has 3 states with an animation for transforming between states. The file also has 2 design fragments, a tile fragment with 2 buttons and a label fragment.
Click the "Run File" menu action or press Shift+F6 on your keyboard to run the fragments design file. When the application starts, you see that the "Index Buttons" and Labels fragments overlap with each other, but when you were editing them in the Design view, they were positioned properly.
Note: If you see only an empty design, you probably used the "Run Project" action or pressed F6 instead of running only the Fragments file.
This is one of the main differences between fragments design files and regular recommended, if you want to run the fragments file and see the layout you designed, do the following:
For the purposes of this tutorial, do NOT set the "Generate LayoutXY ..." property. Leave it set to "false".
In both cases, when you run the Fragments file, it is fully functional. You can press the Previous and Next buttons to control the Label's text.
In this section, you add UI components to the Main design file. Later, you embed the fragments into this file.
To design the Main file:
So far the Main and Fragments designs are still disconnected. JavaFX Composer does not yet provide support for embedding design fragments in the visual editor. Therefore, you have to embed the fragments by editing the source code.
To embed fragments in the Main design file:
//embed the Fragments design into the Main design
def fragments = Fragments {}
init {
// tile fragment into indexButtonsPlaceholder
insert fragments.tile into indexButtonsPlaceholder.content;
// label fragment into labelPlaceholder
insert fragments.label into labelPlaceholder.content;
}
Now you can run the entire application.
Run the Fragments project. (F6 or Run Main Project icon , if it is the main project.) The design file is saved and the project is compiled and started. The buttons switch the application between states.
The "Index Buttons" and "Label" components are synchronized and the animations run as you specified in the Fragments design file. This is because the same instance of the Fragments class holds the instances of the index buttons and the label. The application would work this way even if you had used each fragment in a different Scene.
In the same Main design, you can embed multiple instances of one Fragments design or instances of different Fragments designs.
Note that the Main design can control the instances/content/state of the Fragments design. For example, you can add a new button into the Main design and assign an "action" function with the fragments.currentState.next(); code.
To clean up an application, you can delete the run function from the Fragments design file because it is not needed except for testing purposes.
You can convert an existing Main design file into a Fragments file by removing its Scene. Try this on the Main file in your application.
To convert the Main file into a Fragments file:
In the Navigator window, the original Design File > scene [Scene] node is replaced with the Design File > Design Fragments node.
Now switch to the "Source" view and expand the generated code section. You can see that the Main class does not contain a definition of the scene instance or a getDesignScene function. You converted the Main design file to a Fragments design file.
Similarly, you can convert a Fragments design file to a Main design file by adding a Scene. To convert your Design Fragments file back to a Main design file, set the Generate Scene property and the Generate getDesignScene Function property to "true".
By switching the Generate Scene property and the Generate getDesignScene Function property between "true" and "false," you can easily convert files back and forth from being Design Fragments files to being Main design files.
You can create a new project from the Media View sample project included in the IDE.
Open this sample from the Samples > JavaFX category. This sample demonstrates the design-fragment
concept with a single Main.fx design containing the Scene and Stage and multiple design fragments.
The fragments are inserted into the Scene in the Main design.
For more information about using NetBeans IDE to develop JavaFX applications, see the following resources: