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;
             }
         }
     };
    • 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).
    • 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.
    • 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<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.
      • 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()
      • 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()
      • 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
      • 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()
      • 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