I have two objectives for today's article:
Continue teaching you how to create UI custom controls in JavaFX. This lesson is a new addition to the JFX Custom Nodes category, and it provides an infrastructure on which you can easily create "wizards".
- Show my appreciation to the JavaZone committee for inviting me to speak on JavaFX at JavaZone 2008 in Oslo, Norway, which will occur on September 17 & 18.
To accomplish both objectives, I've created a "wizard" (in the spirit of fun) in which you can discover whether you are a Viking or not. Having visited Norway in the past, I've found that Norwegians tend to be very proud of their Viking heritage. The program in this post was created out of respect for that sentiment, and I consulted one of the Norwegian JavaZone organizers for fun ideas to include in this wizard. As with the rest of the series, Mark Dingman of Malden Labs created the graphical mock-ups and assets. Here are a couple of screenshots of the wizard that I call "Are You a Viking?"
As shown in the previous screen shot, this wizard asks the user questions, The user's response to a given question determine what wizard page will be shown next. If you answer the questions as a true Viking would, then the wizard will congratulate you with the page shown in the screenshot below:
Go ahead and try out the program. You'll need JRE 6, and please note that Java SE 6 Update 10 will give you a faster deployment experience.
Creating a Wizard
In addition to using some of the classes from the JFX Custom Nodes category of the blog (namely the MenuNode, ButtonNode and DeckNode classes), this example introduces three more classes: WizardNode, WizardPoint and OptionsNode. Before showing you the code for these new classes, I’d like you to see the main program in this "Are You a Viking?" example, which is in a file named WizardNodeExampleMain.fx:
/*
* WizardNodeExampleMain.fx -
* An example of using the WizardNode custom node. It also demonstrates
* the OptionsNode, MenuNode and ButtonNode custom nodes, as well as the
* WizardPoint class.
*
* Developed 2008 by James L. Weaver (jim.weaver at lat-inc.com)
* to demonstrate how to create custom nodes in JavaFX
*/
package com.javafxpert.wizard_node_example.ui;
import javafx.application.*;
import javafx.ext.swing.*;
import javafx.scene.*;
import javafx.scene.image.*;
import javafx.scene.layout.*;
import javafx.scene.paint.*;
import javafx.scene.text.*;
import javafx.scene.transform.*;
import java.lang.System;
import com.javafxpert.custom_node.*;
var wizardRef:WizardNode;
Frame {
var stageRef:Stage;
var menuRef:MenuNode;
var pageFont =
Font {
name: "Sans serif"
size: 28
};
title: "WizardNode Example"
width: 505
height: 400
visible: true
stage:
stageRef = Stage {
fill: Color.BLACK
content: [
wizardRef = WizardNode {
flowPath:
WizardPoint {
nodeID: "Shaving" // The id attribute of the Node to be displayed
nextPoints: [
WizardPoint {
advanceState: "ElectricRazor"
nodeID: "NotViking"
},
WizardPoint {
advanceState: "SafetyRazor"
nodeID: "NotViking"
},
WizardPoint {
advanceState: "StraightRazor"
nodeID: "NotViking"
},
WizardPoint {
advanceState: "ShaveWithSword"
nodeID: "DiscoveredAmerica"
nextPoints: [
WizardPoint {
advanceState: "ChristopherColumbus"
nodeID: "NotViking"
},
WizardPoint {
advanceState: "LeifEricson"
nodeID: "WearHelmetHowOften"
nextPoints: [
WizardPoint {
advanceState: "AlwaysWearsHelmet"
nodeID: "OwnWoodenBoat"
nextPoints: [
WizardPoint {
advanceState: "FiberglassBoat"
nodeID: "NotViking"
},
WizardPoint {
advanceState: "WoodenBoat"
nodeID: "IsViking"
},
WizardPoint {
advanceState: "NoBoat"
nodeID: "NotViking"
},
]
},
WizardPoint {
advanceState: "WearsHelmetOnOccasions"
nodeID: "NotViking"
},
WizardPoint {
advanceState: "WearsHelmetOncePerWeek"
nodeID: "NotViking"
},
WizardPoint {
advanceState: "NeverWearsHelmet"
nodeID: "NotViking"
},
]
},
WizardPoint {
advanceState: "TheBeatles"
nodeID: "NotViking"
},
]
},
]
}
fadeInDur: 700ms
canCancel: true
canFinish: false
backgroundNode:
Group {
content: [
ImageView {
image:
Image {
url: "{__DIR__}images/viking_jprep_background.png"
}
},
ImageView {
image:
Image {
url: "{__DIR__}images/viking_jprep_helmet.png"
}
},
]
}
content: [
Group {
var optionsNode:OptionsNode;
transform: Translate.translate(50, 130);
id: "Shaving"
content: [
optionsNode = OptionsNode {
heading: "How Do You Shave?"
options: [
"I shave with an electric razor",
"I shave with a safety razor",
"I shave with a straight razor",
"I shave with my sword",
]
optionAdvanceStates: [
"ElectricRazor",
"SafetyRazor",
"StraightRazor",
"ShaveWithSword"
]
action:
function():Void {
wizardRef.candidateAdvanceState = optionsNode.optionAdvanceState;
}
}
]
},
Group {
var optionsNode:OptionsNode;
transform: Translate.translate(50, 130);
id: "DiscoveredAmerica"
content: [
optionsNode = OptionsNode {
heading: "Who Discovered America?"
options: [
"Christopher Columbus",
"Leif Ericson",
"The Beatles",
]
optionAdvanceStates: [
"ChristopherColumbus",
"LeifEricson",
"TheBeatles",
]
action:
function():Void {
wizardRef.candidateAdvanceState = optionsNode.optionAdvanceState;
}
}
]
},
Group {
var optionsNode:OptionsNode;
transform: Translate.translate(50, 130);
id: "WearHelmetHowOften"
content: [
optionsNode = OptionsNode {
heading: "How Often Do You Wear Your Helmet?"
options: [
"I always wear it, even in bed",
"Only on special occasions",
"Once a week",
"Never - it gives me Helmet Hair"
]
optionAdvanceStates: [
"AlwaysWearsHelmet",
"WearsHelmetOnOccasions",
"WearsHelmetOncePerWeek",
"NeverWearsHelmet",
]
action:
function():Void {
wizardRef.candidateAdvanceState = optionsNode.optionAdvanceState;
}
}
]
},
Group {
var optionsNode:OptionsNode;
transform: Translate.translate(50, 130);
id: "OwnWoodenBoat"
content: [
optionsNode = OptionsNode {
heading: "Do You Own a Wooden Boat?"
options: [
"No, mine is fiberglass",
"Of course it's made out of wood!",
"I don't own a boat",
]
optionAdvanceStates: [
"FiberglassBoat",
"WoodenBoat",
"NoBoat",
]
action:
function():Void {
wizardRef.candidateAdvanceState = optionsNode.optionAdvanceState;
}
}
]
},
HBox {
id: "IsViking"
transform: Translate.translate(50, 110);
content: [
ImageView {
image:
Image {
url: "{__DIR__}images/viking_yes.png"
}
},
VBox {
transform: Translate.translate(0, 20);
spacing: 40
content: [
Text {
textOrigin: TextOrigin.TOP
content: "Congratulations!"
fill: Color.WHITE
font: pageFont
},
Text {
textOrigin: TextOrigin.TOP
content: "You are a Viking!"
fill: Color.WHITE
font: pageFont
},
]
}
]
},
HBox {
id: "NotViking"
transform: Translate.translate(50, 110);
content: [
ImageView {
image:
Image {
url: "{__DIR__}images/viking_no.png"
}
},
VBox {
transform: Translate.translate(0, 20);
spacing: 40
content: [
Text {
textOrigin: TextOrigin.TOP
content: "Sorry! You are most"
fill: Color.WHITE
font: pageFont
},
Text {
textOrigin: TextOrigin.TOP
content: "likely not a Viking!"
fill: Color.WHITE
font: pageFont
},
]
}
]
},
]
},
menuRef = MenuNode {
translateX: bind stageRef.width / 2 - menuRef.getWidth() / 2
translateY: bind stageRef.height - menuRef.getHeight() * 0.75
buttons: [
ButtonNode {
imageURL: "{__DIR__}images/viking_jprep_btn_previous.png"
enabled: bind wizardRef.canGoBack
scale: 1.0
action:
function():Void {
wizardRef.goBack();
}
},
ButtonNode {
imageURL: "{__DIR__}images/viking_jprep_btn_next.png"
enabled: bind wizardRef.canAdvance
scale: 1.0
action:
function():Void {
wizardRef.advance();
}
},
ButtonNode {
imageURL: "{__DIR__}images/viking_jprep_btn_cancel.png"
enabled: bind wizardRef.canCancel
scale: 1.0
action:
function():Void {
wizardRef.reset();
}
},
ButtonNode {
imageURL: "{__DIR__}images/viking_jprep_btn_finish.png"
enabled: bind wizardRef.atEndpoint
scale: 1.0
action:
function():Void {
wizardRef.reset();
}
},
]
}
]
}
closeAction:
function():Void {
System.exit(0);
}
}
As shown above, one of the important features of the wizard is what I call its flow path. The flowPath attribute of the WizardNode class enables you to articulate all of the points in the wizard’s flow, as well as to articulate the navigation paths between points. Each point in a wizard’s flow path is represented by a WizardPoint instamce, and each navigation path between points is represented by an element in the nextPoints sequence attribute. The nextPoints attribute contains a sequence of WizardPoint instances, each of which holds an advanceState string attribute that enables navigation to that point. As you can see from the listing above, each WizardPoint instance also contains a nodeID attribute that matches the id attribute of a Node (held within the content sequence attribute of the WizardNode). Looking at that attribute in the listing above, you’ll notice that all of the wizard pages (Node instances) are held in that sequence. As you’ll soon see, it is the responsibility of the WizardNode class to cause the associated Node instance to show after navigating to a given wizard point.
Another important attribute in the WizardNode class is backgroundNode. This attribute enables you to create a background that will show behind each page of the wizard. Take a look at the WizardNode.fx listing below, and notice that it extends the DeckNode class, which contains the functionality of switching between Node instances by their id attributes.
/*
* WizardNode.fx -
* A custom node that functions as a "wizard", progressively displaying
* UI nodes according to a supplied "flow". Each node, typically as a result
* of user interaction, may set a state that determines which node of the flow
* will be displayed.
*
* Developed 2008 by James L. Weaver (jim.weaver at lat-inc.com)
* to demonstrate how to create custom nodes in JavaFX
*/
package com.javafxpert.custom_node;
import javafx.lang.*;
import java.lang.System;
/*
* A custom node that functions as a "wizard", progressively displaying
* UI nodes according to a supplied "flow". Each node, typically as a result
* of user interaction, may set a state that determines which node of the flow
* will be displayed.
*/
public class WizardNode extends DeckNode {
/**
* The flow of the wizard, expressed as a series of related
* WizardPoint instances
*/
public attribute flowPath:WizardPoint;
/**
* The current path that the user is taking through the wizard, expressed as
* a sequence of WizardPoint instances
*/
public attribute currentPath:WizardPoint[];
/**
* Determines whether the user can advance to the next wizard page
*/
public attribute canAdvance:Boolean = false;
/**
* Determines whether the user can go back to the previous wizard page
*/
public attribute canGoBack:Boolean = bind sizeof currentPath > 1;
/**
* Determines whether the user can cancel out of this wizard
*/
public attribute canCancel:Boolean;
/**
* Determines whether the user can finish this wizard
*/
public attribute canFinish:Boolean;
/**
* Determines whether the user is at and end point in the wizard,
* which is defined by not having any nextPoints
*/
public attribute atEndpoint:Boolean = bind
(sizeof currentPoint.nextPoints) == 0;
/**
* A reference to the WizardPoint instance that the user is currently on
*/
private attribute currentPoint:WizardPoint on replace {
if (currentPoint != null) {
visibleNodeId = currentPoint.nodeID;
canAdvance = false;
}
};
postinit {
reset();
}
/**
* Resets the wizard to its initial state
*/
public function reset():Void {
currentPoint = flowPath;
currentPath = [];
insert currentPoint into currentPath;
}
/**
* The requested advanceState to be navigated to from this point. If this is
* a valid advanceState, the canAdvance attribute is set to true, otherwise
* it is set to false
*/
public attribute candidateAdvanceState:String on replace {
if (candidateAdvanceState != "") {
var newPoint = currentPoint.getPointByAdvanceState(candidateAdvanceState);
canAdvance = newPoint != null;
}
}
/**
* Request that the current WizardPoint be changed to the candidateAdvanceState
* TODO: Consider throwing an exception if unsuccessful
*/
public function advance():Void {
var newPoint = currentPoint.getPointByAdvanceState(candidateAdvanceState);
if (newPoint != null) {
currentPoint = newPoint;
// Put this WizardPoint on the current path through the flow path
insert currentPoint into currentPath;
}
}
/**
* Request that the current WizardPoint be changed to the one that precedes
* it in the current path that the user has taken through the flow. In other
* words, go back.
* TODO: Consider throwing an exception if unsuccessful
*/
public function goBack():Void {
var idx = sizeof currentPath - 1;
if (idx > 0) {
delete currentPath[idx];
// Put this WizardPoint on the current path through the flow path
currentPoint = currentPath[idx - 1];
}
}
}
Here is the listing for the WizardPoint class mention previously:
/*
* WizardPoint.fx -
* A point in the flow of a "wizard", that is related to a given wizard page
* (graphical Node). Wizard point instances are related to each other in
* a network of points that determines the potential flows within the wizard.
*
* Developed 2008 by James L. Weaver (jim.weaver at lat-inc.com)
* to demonstrate how to create custom nodes in JavaFX
*/
package com.javafxpert.custom_node;
import java.lang.System;
/**
* A point in the flow of a "wizard", that is related to a given wizard page
* (graphical Node). Wizard point instances are related to each other in
* a network of points that determines the potential flows within the wizard.
*/
public class WizardPoint {
/**
* The id attribute of the Node (wizard page) to be displayed
*/
public attribute nodeID:String;
/**
* A String that controls the condition by which this WizardPoint may be
* landed upon. If advanceState is an empty string, then this point may be
* landed upon by default
*/
public attribute advanceState:String;
/**
* The WizardPoint instances that may be navigated to from this point.
*/
public attribute nextPoints:WizardPoint[]; //TODO make sure that this creates an empty sequence, not a null reference
/**
* Returns the WizardPoint instance that may be navigated to from this point
* for a given advanceState
* TODO: Decide whether this is needed
*/
public function getPointByAdvanceState(advanceState:String):WizardPoint {
var points =
for (point in nextPoints where point.advanceState == advanceState) point;
if (sizeof points > 0) points[0]
else null;
}
}
Notice also in the WizardNodeExampleMain.fx listing shown previously that I'm using an OptionsNode custom node in some of the wizard pages. This class makes it quick and easy to articulate a set of mutually exclusive options as well as a heading for the list of options. It was designed for use with this wizard functionality, as it is capable of holding an advanceState for each of the options and storing the advanceState for an option that the user selected. Take a look at the listing for the OptionsNode.fx class below:
/*
* OptionsNode.fx -
* A custom node that enables the user to choose
* from a list of options.
*
* Developed 2008 by James L. Weaver (jim.weaver at lat-inc.com)
* to demonstrate how to create custom nodes in JavaFX
*/
package com.javafxpert.custom_node;
import javafx.ext.swing.*;
import javafx.scene.*;
import javafx.scene.paint.*;
import java.lang.System;
public class OptionsNode extends CustomNode {
/**
* A header for the options
*/
public attribute heading:String;
/**
* A sequence containing the choice of options
*/
public attribute options:String[];
/**
* A sequence containing the WizardNode advanceState associated with the
* options.
*/
public attribute optionAdvanceStates:String[];
/**
* The font to use for the heading
*/
public attribute headingFont =
Font {
name: "Sans serif"
size: 24
};
/**
* The font to use for the options
*/
public attribute optionsFont =
Font {
name: "Sans serif"
size: 22
};
/**
* The color to use for the text
*/
public attribute textColor = Color.rgb(253, 253, 253);
/**
* The advanceState associated with a selected option
*/
public attribute optionAdvanceState:String;
/**
* The action function attribute that is executed when the
* a selection is made
*/
public attribute action:function():Void;
/**
* Reset the selected radio buttons
*/
public function reset():Void {
toggleGroup.clearSelection();
}
/**
* Called when this page is shown in the wizard. Reset the radio button
* selections
*/
public function onShow():Void {
reset();
}
/**
* A reference to the ToggleGroup associated with the RadioButton instances
*/
private attribute toggleGroup:ToggleGroup = ToggleGroup{};
/**
* Create the Node
*/
public function create():Node {
ComponentView {
component:
GridPanel {
background:
Color.rgb(255, 255, 255, 0.0) // Transparent
rows: bind sizeof options + 1
columns: 1
content: bind [
Label {
text: heading
font: headingFont
foreground: textColor
},
for (option in options)
RadioButton {
var idx:Integer = indexof option;
toggleGroup: toggleGroup
text: option
font: optionsFont
foreground: textColor
action:
function():Void {
optionAdvanceState = optionAdvanceStates[idx];
action();
}
}
]
}
}
}
}
Room for Improvement
There is at least one area of functionality in which I'd like to make an improvement: Currently, a wizard page is a subclass of Node, but it may be good to define a custom node (perhaps named WizardPageNode) that has life-cycle functions and some helper functionality. I welcome your thoughts on this, as well as any other input or questions that you have. In either case, please post a comment.
Also, if you're at JavaZone 2008, please introduce yourself as I'd like to meet you!
Thanks,
Jim Weaver
JavaFXpert.com
