java.lang.Object
org.controlsfx.dialog.Wizard
The API for creating multi-page Wizards, based on JavaFX Dialog
API.
Wizard can be setup in following few steps:
- Design wizard pages by inheriting them from
WizardPane
- Define wizard flow by implementing
Wizard.Flow
- Create and instance of the Wizard and assign flow to it
- Execute the wizard using showAndWait method
- Values can be extracted from settings map by calling getSettings
For simple, linear wizards, the Wizard.LinearFlow
can be used.
It is a flow based on a collection of wizard pages. Here is the example:
// Create pages. Here for simplicity we just create and instance of WizardPane.
WizardPane page1 = new WizardPane();
WizardPane page2 = new WizardPane();
WizardPane page3 = new WizardPane();
// create wizard
Wizard wizard = new Wizard();
// create and assign the flow
wizard.setFlow(new LinearFlow(page1, page2, page3));
// show wizard and wait for response
wizard.showAndWait().ifPresent(result -> {
if (result == ButtonType.FINISH) {
System.out.println("Wizard finished, settings: " + wizard.getSettings());
}
});
For more complex wizard flows we suggest to create a custom ones, describing page traversal logic. Here is a simplified example:
Wizard.Flow branchingFlow = new Wizard.Flow() {
public Optional<WizardPane> advance(WizardPane currentPage) {
return Optional.of(getNext(currentPage));
}
public boolean canAdvance(WizardPane currentPage) {
return currentPage != page3;
}
private WizardPane getNext(WizardPane currentPage) {
if ( currentPage == null ) {
return page1;
} else if ( currentPage == page1) {
// skipNextPage() does not exist - this just represents that you
// can add a conditional statement here to change the page.
return page1.skipNextPage()? page3: page2;
} else {
return page3;
}
}
};
-
Property Summary
PropertiesTypePropertyDescriptionfinal javafx.beans.property.ObjectProperty
<Wizard.Flow> TheWizard.Flow
property represents the flow of pages in the wizard.final javafx.beans.property.BooleanProperty
Property for overriding the individual validation state of thisWizard
.final javafx.beans.property.BooleanProperty
Property for overriding the individual read-settings state of thisWizard
.final javafx.beans.property.ObjectProperty
<javafx.scene.control.ButtonType> final javafx.beans.property.StringProperty
Return the titleProperty of the wizard. -
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Represents the page flow of the wizard.static class
LinearFlow is an implementation of theWizard.Flow
interface, designed to support the most common type of wizard flow - namely, a linear wizard page flow (i.e. through all pages in the order that they are specified). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfinal javafx.beans.property.ObjectProperty
<Wizard.Flow> TheWizard.Flow
property represents the flow of pages in the wizard.final Wizard.Flow
getFlow()
Returns the currently setWizard.Flow
, which represents the flow of pages in the wizard.Returns an observable map of properties on this Wizard for use primarily by application developers - not to be confused with thegetSettings()
map that represents the values entered by the user into the wizard.The settings map is the place where all data from pages is kept once the user moves on from the page, assuming there is aValueExtractor
that is capable of extracting a value out of the various fields on the page.final String
getTitle()
Return the title of the wizard.Returns a previously set Object property, or null if no such property has been set using thesetUserData(Object)
method.boolean
Tests if this Wizard has properties.final javafx.beans.property.BooleanProperty
Property for overriding the individual validation state of thisWizard
.final boolean
Gets the value of the propertyinvalid
.final boolean
Gets the value of the propertyreadSettings
.final javafx.beans.property.BooleanProperty
Property for overriding the individual read-settings state of thisWizard
.final javafx.beans.property.ObjectProperty
<javafx.scene.control.ButtonType> final void
setFlow
(Wizard.Flow flow) Sets theWizard.Flow
, which represents the flow of pages in the wizard.final void
setInvalid
(boolean invalid) Sets the value of the propertyinvalid
.final void
setReadSettings
(boolean readSettings) Sets the value of the propertyreadSettings
.final void
Change the Title of the wizard.void
setUserData
(Object value) Convenience method for setting a single Object property that can be retrieved at a later date.final Optional
<javafx.scene.control.ButtonType> Shows the wizard and waits for the user response (in other words, brings up a blocking dialog, with the returned value the users input).final javafx.beans.property.StringProperty
Return the titleProperty of the wizard.
-
Property Details
-
result
public final javafx.beans.property.ObjectProperty<javafx.scene.control.ButtonType> resultProperty- See Also:
-
title
public final javafx.beans.property.StringProperty titlePropertyReturn the titleProperty of the wizard.- See Also:
-
flow
TheWizard.Flow
property represents the flow of pages in the wizard.- See Also:
-
invalid
public final javafx.beans.property.BooleanProperty invalidPropertyProperty for overriding the individual validation state of thisWizard
. Settinginvalid
to true will disable the next/finish Button and the user will not be able to advance to the next page of theWizard
. Settinginvalid
to false will enable the next/finish Button.
For example you can use theValidationSupport.invalidProperty()
of a page and bind it to theinvalid
property:
wizard.invalidProperty().bind(page.validationSupport.invalidProperty());
- See Also:
-
readSettings
public final javafx.beans.property.BooleanProperty readSettingsPropertyProperty for overriding the individual read-settings state of thisWizard
. SettingreadSettings
to true will enable the value extraction for thisWizard
. SettingreadSettings
to false will disable the value extraction for thisWizard
.- See Also:
-
-
Constructor Details
-
Wizard
public Wizard()Creates an instance of the wizard without an owner. -
Wizard
Creates an instance of the wizard with the given owner.- Parameters:
owner
- The object from which the owner window is deduced (typically this is a Node, but it may also be a Scene or a Stage).
-
Wizard
Creates an instance of the wizard with the given owner and title.- Parameters:
owner
- The object from which the owner window is deduced (typically this is a Node, but it may also be a Scene or a Stage).title
- The wizard title.
-
-
Method Details
-
showAndWait
Shows the wizard and waits for the user response (in other words, brings up a blocking dialog, with the returned value the users input).- Returns:
- An
Optional
that contains the result.
-
resultProperty
public final javafx.beans.property.ObjectProperty<javafx.scene.control.ButtonType> resultProperty()- Returns:
Dialog.resultProperty()
of theDialog
representing thisWizard
.
-
getSettings
The settings map is the place where all data from pages is kept once the user moves on from the page, assuming there is aValueExtractor
that is capable of extracting a value out of the various fields on the page. -
titleProperty
public final javafx.beans.property.StringProperty titleProperty()Return the titleProperty of the wizard.- Returns:
- the
title
property - See Also:
-
getTitle
Return the title of the wizard. -
setTitle
Change the Title of the wizard.- Parameters:
title
-
-
flowProperty
TheWizard.Flow
property represents the flow of pages in the wizard.- Returns:
- the
flow
property - See Also:
-
getFlow
Returns the currently setWizard.Flow
, which represents the flow of pages in the wizard. -
setFlow
Sets theWizard.Flow
, which represents the flow of pages in the wizard. -
getProperties
Returns an observable map of properties on this Wizard for use primarily by application developers - not to be confused with thegetSettings()
map that represents the values entered by the user into the wizard.- Returns:
- an observable map of properties on this Wizard for use primarily by application developers
-
hasProperties
public boolean hasProperties()Tests if this Wizard has properties.- Returns:
- true if this Wizard has properties.
-
setUserData
Convenience method for setting a single Object property that can be retrieved at a later date. This is functionally equivalent to calling the getProperties().put(Object key, Object value) method. This can later be retrieved by callinggetUserData()
.- Parameters:
value
- The value to be stored - this can later be retrieved by callinggetUserData()
.
-
getUserData
Returns a previously set Object property, or null if no such property has been set using thesetUserData(Object)
method.- Returns:
- The Object that was previously set, or null if no property has been set or if null was set.
-
setInvalid
public final void setInvalid(boolean invalid) Sets the value of the propertyinvalid
.- Parameters:
invalid
- The new validation stateinvalidProperty()
-
isInvalid
public final boolean isInvalid()Gets the value of the propertyinvalid
.- Returns:
- The validation state
- See Also:
-
invalidProperty
public final javafx.beans.property.BooleanProperty invalidProperty()Property for overriding the individual validation state of thisWizard
. Settinginvalid
to true will disable the next/finish Button and the user will not be able to advance to the next page of theWizard
. Settinginvalid
to false will enable the next/finish Button.
For example you can use theValidationSupport.invalidProperty()
of a page and bind it to theinvalid
property:
wizard.invalidProperty().bind(page.validationSupport.invalidProperty());
- Returns:
- The validation state property
- See Also:
-
setReadSettings
public final void setReadSettings(boolean readSettings) Sets the value of the propertyreadSettings
.- Parameters:
readSettings
- The new read-settings state- See Also:
-
isReadSettings
public final boolean isReadSettings()Gets the value of the propertyreadSettings
.- Returns:
- The read-settings state
- See Also:
-
readSettingsProperty
public final javafx.beans.property.BooleanProperty readSettingsProperty()Property for overriding the individual read-settings state of thisWizard
. SettingreadSettings
to true will enable the value extraction for thisWizard
. SettingreadSettings
to false will disable the value extraction for thisWizard
.- Returns:
- The readSettings state property
- See Also:
-