Module org.controlsfx.controls
Package org.controlsfx.dialog

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

  • Property Details

  • 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<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 ObjectProperty<ButtonType> resultProperty()

    • getSettings

      public final 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.

    • getDialog

      public final Dialog<ButtonType> getDialog()
      Provides access to the Dialog object used to display the Wizard.
      Returns:
      The Dialog representing this Wizard.
      This can be accessed in order to modify its properties if necessary, for example setting its window icon or its modality.

    • titleProperty

      public final StringProperty titleProperty()
      Return the titleProperty of the wizard.
      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 ObjectProperty<Wizard.Flow> flowProperty()
      The Wizard.Flow property represents the flow of pages in the wizard.
      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 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 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:

    • 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 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: