Class Wizard

java.lang.Object
org.controlsfx.dialog.Wizard
public class Wizard extends Object

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;
        }
    }
};

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    Wizard.Flow
    Represents the page flow of the wizard.
    static class 
    Wizard.LinearFlow
    LinearFlow is an implementation of the Wizard.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).

  • Property Summary

    Properties
    Type
    Property
    Description
    final javafx.beans.property.ObjectProperty<Wizard.Flow>
    flow
    The Wizard.Flow property represents the flow of pages in the wizard.
    final javafx.beans.property.BooleanProperty
    invalid
    Property for overriding the individual validation state of this Wizard.
    final javafx.beans.property.BooleanProperty
    readSettings
    Property for overriding the individual read-settings state of this Wizard.
    final javafx.beans.property.ObjectProperty<javafx.scene.control.ButtonType>
    result
     
    final javafx.beans.property.StringProperty
    title
    Return the titleProperty of the wizard.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Wizard()
    Creates an instance of the wizard without an owner.
    Wizard(Object owner)
    Creates an instance of the wizard with the given owner.
    Wizard(Object owner, String title)
    Creates an instance of the wizard with the given owner and title.

  • Method Summary

    Modifier and Type
    Method
    Description
    final javafx.beans.property.ObjectProperty<Wizard.Flow>
    flowProperty()
    The Wizard.Flow property represents the flow of pages in the wizard.
    final Wizard.Flow
    getFlow()
    Returns the currently set Wizard.Flow, which represents the flow of pages in the wizard.
    final javafx.collections.ObservableMap<Object,Object>
    getProperties()
    Returns an observable map of properties on this Wizard for use primarily by application developers - not to be confused with the getSettings() map that represents the values entered by the user into the wizard.
    final javafx.collections.ObservableMap<String,Object>
    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 a ValueExtractor that is capable of extracting a value out of the various fields on the page.
    final String
    getTitle()
    Return the title of the wizard.
    Object
    getUserData()
    Returns a previously set Object property, or null if no such property has been set using the setUserData(Object) method.
    boolean
    hasProperties()
    Tests if this Wizard has properties.
    final javafx.beans.property.BooleanProperty
    invalidProperty()
    Property for overriding the individual validation state of this Wizard.
    final boolean
    isInvalid()
    Gets the value of the property invalid.
    final boolean
    isReadSettings()
    Gets the value of the property readSettings.
    final javafx.beans.property.BooleanProperty
    readSettingsProperty()
    Property for overriding the individual read-settings state of this Wizard.
    final javafx.beans.property.ObjectProperty<javafx.scene.control.ButtonType>
    resultProperty()
     
    final void
    setFlow(Wizard.Flow flow)
    Sets the Wizard.Flow, which represents the flow of pages in the wizard.
    final void
    setInvalid(boolean invalid)
    Sets the value of the property invalid.
    final void
    setReadSettings(boolean readSettings)
    Sets the value of the property readSettings.
    final void
    setTitle(String title)
    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>
    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).
    final javafx.beans.property.StringProperty
    titleProperty()
    Return the titleProperty of the wizard.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Property Details

    • result

      public final javafx.beans.property.ObjectProperty<javafx.scene.control.ButtonType> resultProperty
      See Also:

    • title

      public final javafx.beans.property.StringProperty titleProperty
      Return the titleProperty of the wizard.
      See Also:

    • flow

      public final javafx.beans.property.ObjectProperty<Wizard.Flow> flowProperty
      The Wizard.Flow property represents the flow of pages in the wizard.
      See Also:

    • invalid

      public final javafx.beans.property.BooleanProperty invalidProperty
      Property for overriding the individual validation state of this Wizard. Setting invalid to true will disable the next/finish Button and the user will not be able to advance to the next page of the Wizard. Setting invalid to false will enable the next/finish Button.

      For example you can use the ValidationSupport.invalidProperty() of a page and bind it to the invalid property:
      wizard.invalidProperty().bind(page.validationSupport.invalidProperty());
      See Also:

    • readSettings

      public final javafx.beans.property.BooleanProperty readSettingsProperty
      Property for overriding the individual read-settings state of this Wizard. Setting readSettings to true will enable the value extraction for this Wizard. Setting readSettings to false will disable the value extraction for this Wizard.
      See Also:

  • Constructor Details

    • Wizard

      public Wizard()
      Creates an instance of the wizard without an owner.

    • Wizard

      public Wizard(Object owner)
      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

      public Wizard(Object owner, String title)
      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

      public final Optional<javafx.scene.control.ButtonType> 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 the Dialog representing this Wizard.

    • getSettings

      public final javafx.collections.ObservableMap<String,Object> 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 a ValueExtractor 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

      public final String getTitle()
      Return the title of the wizard.

    • setTitle

      public final void setTitle(String title)
      Change the Title of the wizard.
      Parameters:
      title -

    • flowProperty

      public final javafx.beans.property.ObjectProperty<Wizard.Flow> flowProperty()
      The Wizard.Flow property represents the flow of pages in the wizard.
      Returns:
      the flow property
      See Also:

    • getFlow

      public final Wizard.Flow getFlow()
      Returns the currently set Wizard.Flow, which represents the flow of pages in the wizard.

    • setFlow

      public final void setFlow(Wizard.Flow flow)
      Sets the Wizard.Flow, which represents the flow of pages in the wizard.

    • getProperties

      public final javafx.collections.ObservableMap<Object,Object> getProperties()
      Returns an observable map of properties on this Wizard for use primarily by application developers - not to be confused with the getSettings() 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

      public void setUserData(Object value)
      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 calling getUserData().
      Parameters:
      value - The value to be stored - this can later be retrieved by calling getUserData().

    • getUserData

      public Object getUserData()
      Returns a previously set Object property, or null if no such property has been set using the setUserData(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 property invalid.
      Parameters:
      invalid - The new validation state invalidProperty()

    • isInvalid

      public final boolean isInvalid()
      Gets the value of the property invalid.
      Returns:
      The validation state
      See Also:

    • invalidProperty

      public final javafx.beans.property.BooleanProperty invalidProperty()
      Property for overriding the individual validation state of this Wizard. Setting invalid to true will disable the next/finish Button and the user will not be able to advance to the next page of the Wizard. Setting invalid to false will enable the next/finish Button.

      For example you can use the ValidationSupport.invalidProperty() of a page and bind it to the invalid 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 property readSettings.
      Parameters:
      readSettings - The new read-settings state
      See Also:

    • isReadSettings

      public final boolean isReadSettings()
      Gets the value of the property readSettings.
      Returns:
      The read-settings state
      See Also:

    • readSettingsProperty

      public final javafx.beans.property.BooleanProperty readSettingsProperty()
      Property for overriding the individual read-settings state of this Wizard. Setting readSettings to true will enable the value extraction for this Wizard. Setting readSettings to false will disable the value extraction for this Wizard.
      Returns:
      The readSettings state property
      See Also: