Application States In JavaFX Composer
Written by David Kaspar, adapted and maintained by Jeffrey Rubinoff
A JavaFX application's workflow can make use of states. A state represents a set of component property values that apply at the same point of time. Each state represents a snapshot of the application. The application is in one state when the application starts. The application switches to other states after the user clicks a button, chooses a radio button, or performs a similar action. A component's visibility, animations, and other properties can differ in different states. (Note that the component exists in all states.)
The States window lets you define states and switch between them. The Design view and the Properties and Navigator windows change their displays as you move between states.
In this tutorial, you design a simple UI with a label and a button. Press the button, and the application's state changes. The text in the label differs in different states.
Contents
To complete this tutorial, you need the following software and resources.
Designing the UI
For the purposes of this tutorial, you need a JavaFX Desktop application with some UI components. In this section you design the application.
To design the application:
- Choose File > New Project. The New Project wizard opens. Under Categories, select JavaFX.
Under Projects, select JavaFX Desktop Business Application and click Next.
- The Name and Location page opens. Name the project States. Select a location for the project. Accept the default options and click Finish.
- The project is created and an empty design file opens in the Editor. Look for a Palette window and a Properties window on the right. If either window is missing, open it by going to Window > Palette (Ctrl+Shift+8) or Window > JavaFX Composer Properties, respectively.
- In the Palette window, expand the JavaFX Controls section and drag the following components into the Design:
- Label (label)
- Button (button)
- Select the label. Go to the Properties window and change the label's Text property value to "Master State".
- Select the button. Go to the Properties window and change its Text property value to "Next State".
- Still in the Properties for the button, click the Generate button next to the Action property.
- A list of action generation options opens. Choose "Generate: Go to next state". This generates a button action for going to the next state. The editor changes to the Source view, showing the buttonAction function that you generated. Change currentState.next() to currentState.nextWrapped(). Your design is now complete.
Master State and Created States
All JavaFX applications have a default "master" state. You can see this in the States window of your application's Design view.
Everything you design in an application's master state is created and set up when you start the application. You can work with components and set their properties as usual.
The value of a property is either its default value or is a value associated with a state. If a property is initiated after its creation or changed by a user in the master state, then the property's value is associated with the master state. The state associated with a property's value is indicated by the appearance of the button for opening its Details dialog. Default values are indicated by blank Detail dialog buttons, while master state values have the label '101'.
It is best practice to minimize the load of property changes that occur during a state change. Therefore edit properties in the master state as much as possible. Only the values that are changed in a particular state should be edited in a non-master state.
It is best practice to set one of the non-master states as the start state and never display the master state itself.
Creating a state
You can create multiple states for your design. You can create a state based on the master state or you can create a state as a duplicate of a non-master state.
When you create a state, the new state inherits all its property values from its parent state. A state based on the master state inherits all property values from the master state.
A state that is a duplicate of a non-master state inherits all the property values of the original non-master state. (The master state is the ultimate ancestor of all states.
If a property value is not set in an ancestral non-master state, that property value is inherited from the master state.) After you create a state, you can edit that state's property values.
In the rest of this section, you create a state based on the master state and edit that state's property values.
To create a state based on the master state:
- In the States window in the Design view, click the Add State
button.
-
The Add State dialog opens. In this dialog, you can set the following properties:
- The name of the new state.
- Whether to inherit components and property values from the master state or duplicate another existing state.
- Whether this new state is the starting state. In other words, whether this is the state of the application when it launches.
Name the new state "Red" and accept all other default settings. Your application will now start in the Red state.
- Click OK. The Red state is created and selected in the States window.
- Select the label and change its Text property to "Red state".
- Click the Add button for the Text Fill property and select Color from the menu that appears.
-
The Choose Color dialog opens. Select a shade of red that you like and click OK.
You have now completed the Red state. The text of the label appears red in the Design view. The field for the Text Fill property of the label now says "color" and the Open Details button is enabled. The icon for the Open Details button has a small pencil 
to show that the values for this property are specific for the currently chosen state. The toolbar of the Properties window contains the identifier of the component (label) and the name of the currently chosen state (red).
Duplicating a created state
You can create additional states by duplicating an existing created state. In this section, you duplicate the Red state to create the Blue state.
To duplicate a state:
- In the States window, click the Add State button.
- Name the state "Blue" and select the "Duplicate of" radio button. Select "Red" as the state to duplicate.
Click OK.
- Select the label component. Look at the Properties window. Note that the label has inherited all the property settings from the Red state. Change the label's Text property to "Blue state".
- Click the Add button for the Text Fill property and select Color from the menu that appears.
- The Choose Color dialog appears. Select a shade of blue that you like and click OK. In the Design view, the text in the label changes to this color. The field for the Text Fill property of the label now says "color2".
You now have another state, Blue, that started as a duplicate of the Red state. In the States window, switch between Blue, Red, and master states. Note the change in appearance of the components in the Design view.
Transitioning Between States
You can set effects in your application that affect the transition of the application between states. In this tutorial, you add an animation to the application. The animation runs when the application changes state.
To add an animation that runs when the application changes state:
- Select the label component.
- In the Properties window, click the Transform button. The Transform properties display.
- In the Transform properties, click the Open Details button for the Scale X property.
- The Scale X property Details dialog opens. In this dialog, you set animations and values for the property in one or more states. Select the Blue state and type 1.5 in the specified value field. Note that the currentState box shows you that the value remains 1.0 in the master and Red states.
Note: Instead of using a specified value, you can set the value using a custom code or generated function call. Select "Use value resolved from function:" and enter the custom code or the function call. Click the Generate button to create the specified function in the source code.
Tip: If you set a property's values in a non-master state and realize that these should be the master values, click Set As Master. This button pushes the values as the new master values. On the other hand, if you want to discard your edited non-master state values, click the Reset As Master button. This button replaces all values in the selected states with the master values.
- Click the Select All button. This button selects all non-master states. You see that both Red and Blue states are selected. In the Animate drop-down box, select Linear. In the ms field, type 500.
- Click Close. Your application is complete.
In the States window, switch between Red, Blue, and master states. You see the appearance of the components in different states, but not the animation. The animation will run in the running application when a user clicks the Next State button.
Running the Project
Run the States 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. Click the Next State button and watch the size of the label text change through a 500ms animation.
More Exercises
Here are some more exercises you can run to explore the use of states:
- Add an animation to the application's Text Fill property. The color passes through all intermediate shades of blue and red when you click Next State!
- Add another component to the Design in the Red state. The component is only visible in that state.
Create a Panel with two labels, all of which are visible only in the Blue state. To minimize the load of property changes that occur during a state change, design as much as possible in the master state.
- Select the Blue state. Drag and drop a Panel container into the Design. The Panel is visible only in the Blue state.
- Right-click the Panel in the Design or Navigator and select "Design selected container" in the context menu. The Design editor changes from designing the Scene to designing the Panel.
- In the States window, select the master state.
- Drag and drop two Labels into the Design. The Panel and the two Labels are visible only in the Blue state, but you can design the Labels in the master state. This reduces code execution when the states are changed.
- Add parallel states to the application. See Parallel Application States and State Variables in JavaFX Composer.
See Also
For more information about using NetBeans IDE to develop JavaFX applications, see the following resources:
