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

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

    • Constructor Detail

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

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

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

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

      • 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()

      • 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:
        isInvalid(), setInvalid(boolean)

      • setReadSettings

        public final void setReadSettings​(boolean readSettings)
        Sets the value of the property readSettings.
        Parameters:
        readSettings - The new read-settings state
        See Also:
        readSettingsProperty()

      • isReadSettings

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