JavaFXComposerFragmentsTutorial

Contents

Using Multiple Design Fragments in JavaFX Composer Projects

Goal

The goal of this tutorial is to show how you can create a complex JavaFX application using multiple design files.

Prerequisites

Before reading this tutorial, read all basic tutorials to learn how to use the most essential features of JavaFX Composer, in particular, states, templates, properties, and generated source code.

Create a new project using the "JavaFX | JavaFX Desktop Bussiness Application" project template. Leave the "Create Design File" checkbox selected.

The new project contains a single design file that is created using the "JavaFX | JavaFX Desktop Design File" file template. Note that this design type contains a Scene instance, which can be edited visually in the Design view.

Using Fragments Design File Template

First, let's create a design file for later reuse. The fragments design represents a collection of components that are not placed on a scene. Therefore, this design type can be reused in other designs or custom code.

Invoke the "File | New File..." action from the main menu. In the wizard, select the "JavaFX" category and choose the "JavaFX Fragments Design File" file template. This template is used to create fragments design files.

file: javafx-composer-fragments-design-file-template.png

Click Next, enter "Fragments" as the file name, and click Finish to create the file. The new design file opens.

Note the following differences of a fragments design file from a usual design file with a scene. The Navigator window has no "Design File | scene [Scene]" node. Instead of it, there is a "Design File | Design Fragments" node. Select this node in the Navigator window or in the background of the Design view. You will see the following content:

The Design view switches to the "Desktop Infinite" profile. Similarly, the Navigator window (in the Design view) displays "Design Fragments" as the edited scope. The Properties window shows properties of the "Design Fragments" node when it is selected in the Navigator window. The properties of the fragments design file will be described later.

Source Code

Switch to the Source tab and expand the folded code. You will see this:

file: javafx-composer-fragments-design-file-code.png

Note that the code generated in the guarded section (on a gray background) does not have a "scene" variable as well as the "getDesignScene" function. Now the Fragments class represents an empty design.

The "run" script-level function is still present. This function constructs a new Stage and a new Scene and calls the "getDesignRootLevelNodes" function in the Fragments class instance.

The "run" function allows you to quickly run and see the designed fragments at runtime. To run the file, choose "Run File" from the popup menu of the "Fragments" file node in the "Projects" window or press "Shift-F6" while you are in the editor.

The "run" function can be deleted at any time since it is not necessary for your application, because you have the "Main" design file as a starting point/Scene. For the purposes of this tutorial, do NOT delete the "run" function now.

Fragments

Switch back to the Design view. Now it is the time to create our own fragments:

  1. Start with an empty fragments design file.
  2. Drag an Index Buttons template from the Palette and drop it somewhere in the Design view. In the Customizer window, select "currentState" as the indexed component.
  3. Drag a Label control from the Palette and drop it somewhere else in the Design view
  4. Open the Details window of the "text" property of the "Label" control.
  5. Press the Bind button and select "currentState" and "Actual State Name" in the lists. Close the window.
  6. Using the States view, add new states named "Init", "Shown", "Rotate".

Optionally:

  • Show the State Variables view and edit the "currentState" to use 1000ms default duration and LINEAR default interpolator.
  • Do some changes to the Label in each state.

This is going to be our design. In the Navigator window, you can see that we have two fragments in our design:

  • Index Buttons
  • Label

file: javafx-composer-fragments-design-finished.png

Running the Fragments

Click the "Run File" menu action or press Shift+F6 on your keyboard to run the fragments design file. When the application starts, you can 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 just an empty design, you have probably used the "Run Project" action or pressed F6 instead of running only the Fragments file.

file: javafx-composer-fragments-design-file-run.png

This is one of the main differences of fragments design files from regular design/mobile design files. Fragments are meant to be used as they are, without additional shifting or adjusting, in different parts of your UI, Scene, design, and custom code. Therefore, the tool ignores the layoutX and layoutY properties of the root-level components, such as the "tile" and "label" components and does not set these properties in the generated source code.

Although the following procedure is not a recommended one, but if you want to use/set these properties anyway, do the following:

  • Select the "Design File | Design Fragments" node in the Navigator window.
  • In the Properties window, set the "Generate LayoutXY for Root-level Components" property to "true".
  • If you run the file again, you will see the Scene exactly as it has been designed in the tool.

For the purposes of this tutorial, do NOT set the "Generate LayoutXY ..." property and leave it set to "false".

Note that in both cases, when the "Fragments" design is run, it is fully functional and you can press the Previous and Next buttons to control the Label's text.

Main Design

Now, we will edit our Main design file. Open the "Main" file and switch to the Design view:

  • Add a VBox container to the Design.
  • Add a Label to the VBox and change its "Text" property to "The Index Buttons Fragment:" string.
  • Add a Panel to the VBox and change its "Instance Name" to "indexButtonsPlaceHolder".
  • Add a Label to the VBox and change its "Text" property to "The Label Fragment:" string.
  • Add a Panel to the VBox and change its "Instance Name" to "labelPlaceHolder".

Note that the "indexButtonsPlaceHolder" and "labelPlaceHolder" panels are now empty. We will place the fragments from the "Fragments" design into these panels.

file: javafx-composer-fragments-main-file-designed.png

Connecting Designs

So far the Main and Fragments designs are still disconnected. The tool does not yet provide support for embedding design fragments in the visual editor. Therefore, we have to add a few lines of code.

Switch to the Source view of the "Main" design and add the following code into the "Main" class:

file: javafx-composer-fragments-embedding-code.png

Now we can finally run the whole application. Right-click the project node in the Projects window and choose Run Project or press F6 on your keyboard (if your project is set as the main one).

file: javafx-composer-fragments-final-run.png

Note that the "Index Buttons" and "Label" components are still synchronized and the animations are running as you have specified in the Fragments design file. This is due to the fact that their instances are held by the same instance of the Fragments design/class. Similarly, it would work this way even if you had used each fragment in a different Scene.

In this way you can embed multiple instances of one Fragments design as well as different Fragments designs.

Note that the Main design may even control the instances/content/state of the Fragments design. E.g. you may add a new button into the Main design and assign an "action" function with the "fragments.currentState.next();" code.

To clean up our application, we can even delete the "run" function from the Fragments design file since it is not needed anymore unless we would like to keep it for testing purposes.

Advanced Properties

Still there are two properties which we have not used yet.

Open the Fragments design file and select the "Design File | Design Fragments" node in the Navigator window.

In the Properties window, set the "Generate getDesignScene Function" property to "true". Switch to the Source tab and expand the auto-generated code section. You can see that an additional "getDesignScene" method has been generated. Its body contains code that creates a Scene similar to the one in the "run" function.

Switching Between File Types: Main and Fragments

You can also convert existing design files (with a Scene) into a Fragments file without a Scene. In our case, let’s convert the Main.fx file to a Fragments file.

To do so, open the Main design file in the Design view. In the Navigator window, select the "Design File | scene [Scene]" node.

In the Properties window, press the "Code" toggle-button to show properties in the Code category. Set the "Generate Scene" property to "false".

Note that the original "Design File | scene [Scene]" node is replaced with the "Design File | Design Fragments" node in the Navigator window.

Now switch to the "Source" tab and expand the folded guarded section. You can see that the Main class does not contain a definition of the "scene" instance as well as the "getDesignScene" function. You have actually converted your Main design file to become a Fragments design file.

Similarly, you can convert the Fragments design file back to the Main design file. Switch to the Design view and select the "Design File | Design Fragments" node in Navigator window. In the Properties window, set the "Generate Scene" property to "true".

In this way, you can change your Fragments design files to regular design files (with the Scene) at any time.

This way you can switch between main and fragments type of a design

Sample

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 fragment-designs which are inserted into the Scene in the Main design.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo