Package com.install4j.api.context

Class WizardIndex

java.lang.Object
com.install4j.api.context.WizardIndex
public class WizardIndex extends Object
A wizard index is used to configure a display of overall installation progress on the left side of the wizard. Note that you can configure the wizard index on each screen in the install4j IDE. For more complex scenarios, this API is provided.

By default, no wizard index is set. You can set a wizard index by calling WizardContext.setWizardIndex(WizardIndex) in a script. If you install the wizard context in the "Pre-activation script" property, it will be used for the current screen. When installed in any other scripts, set the wizard screen will become active once the next screen is shown.

The current wizard index is persistent, meaning that it will remain in place for all subsequent screens until the index key of the wizard is changed or the wizard index is set to null again. A simple usage scenario is given below:

  1. Install the * wizard index on the first screen by invoking 
    
 context.getWizardContext().setWizardIndex(new WizardIndex(new String[]
      {"Gather Requirements", "Installation", "Service Setup"}));
    in the "Pre-activation" script of that screen. When the wizard context is set that way, the keys for the index steps are auto-generated and set to "1", "2" and "3". If they should be mnemonic, use the 2-arg constructor where you can specify an array with keys as the second argument. When you install the wizard index, the first step is highlighted automatically.
  2. For each screen, where the highlighted index step should change, call 
    
 context.getWizardContext().setWizardIndexKey("2");
    to highlight step 2 ("Installation") and 
    
 context.getWizardContext().setWizardIndexKey("3");
    to highlight step 3 ("Service setup").

Advanced tasks:

  • To remove the wizard call 
    
 context.getWizardContext().setWizardIndex(null);
  • You can set another wizard index at any time. When the user goes back in the history, the last shown wizard index and the selected step are shown for each screen.
  • The with of the index panel depends on its contents. However, there are configurable minimum and maximum sizes, the default values are 120 and 300 pixels, respectively. To change these values, use the minWidth and maxWidth methods: 
    
 new WizardIndex(new String[] {...}.maxWidth(400).minWidth(50)
 }
  • A wizard index can be partially defined. In that case, a "..." entry will be shown at the bottom. This is useful if the user makes a selection that will determine the contents of the full wizard index. For example, on the first screen, call 
    
 context.getWizardContext().setWizardIndex(new WizardIndex(
      new String[] {"Installation type"})).partiallyDefined(true);
    In the "Validation expression" of the screen, you then skip to to two different sequences of screens, depending on the selected installation type. In the first screens of each sequence, install new wizard indices with their full respective contents, but repeat the "Installation type" entry and set the selected wizard index key to the second element immediately. In this way, # the partially defined wizard index expands to the full content on the second screen.
  • You can customize the background of the wizard index by setting
    • the foreground color used for text with foreground(Color)
    • the background color with background(Color)
    • the background image with backgroundImage(File)
    • the anchor of the background image with backgroundImageAnchor(anchor)

  • Constructor Details

    • WizardIndex

      public WizardIndex(String[] stepNames)
      Construct a wizard index with the specified step names and auto-generate the index keys to the strings "1", "2", "3", and so on.
      Parameters:
      stepNames - the displayed step names

    • WizardIndex

      public WizardIndex(String[] stepNames, String[] keys)
      Construct a wizard index with the specified step names and index keys.
      Parameters:
      stepNames - the displayed step names
      keys - the keys for the step names, to be used in WizardContext.setWizardIndexKey(String)

  • Method Details

    • getStepNames

      public String[] getStepNames()
      Returns the step names
      Returns:
      the step names

    • getKeys

      public String[] getKeys()
      Returns the index keys
      Returns:
      the index keys

    • isPartiallyDefined

      public boolean isPartiallyDefined()
      Returns if the wizard index is partially defined.
      Returns:
      if partially defined

    • partiallyDefined

      public WizardIndex partiallyDefined(boolean partiallyDefined)
      Sets if the wizard index should be partially defined. In this case, a "..." entry will be appended to the end of the wizard index. By default, this is set to false.
      Parameters:
      partiallyDefined - if partially defined
      Returns:
      this object, for use in a builder pattern

    • getMaxWidth

      public int getMaxWidth()
      Returns the maximum width of the index panel
      Returns:
      the maximum width in pixels

    • maxWidth

      public WizardIndex maxWidth(int maxWidth)
      Sets the maximum width of the index panel. By default, this is set to 300 pixels.
      Parameters:
      maxWidth - the maximum width in pixels
      Returns:
      this object, for use in a builder pattern

    • getMinWidth

      public int getMinWidth()
      Returns the minimum width of the index panel.
      Returns:
      the minimum width in pixels

    • minWidth

      public WizardIndex minWidth(int minWidth)
      Sets the minimum width of the index panel. By default, this is set to 120 pixels.
      Parameters:
      minWidth - the minimum width
      Returns:
      this object, for use in a builder pattern

    • isNumbered

      public boolean isNumbered()
      Returns if numbers should be added in front of each index step.
      Returns:
      true or false

    • numbered

      public WizardIndex numbered(boolean numbered)
      Sets if numbers should be added in front of each index step. By default, this is set to true.
      Parameters:
      numbered - true or false
      Returns:
      this object, for use in a builder pattern

    • getBackground

      public Color getBackground()
      Returns the background color of the index panel
      Returns:
      the background color or null if no background color has been set

    • background

      public WizardIndex background(Color background)
      Sets the background color of the index panel. The default background color is white.
      Parameters:
      background - the background color
      Returns:
      this object, for use in a builder pattern

    • getForeground

      public Color getForeground()
      Returns the foreground color of the index panel used for the text color
      Returns:
      the foreground color or null if no foreground color has been set

    • foreground

      public WizardIndex foreground(Color foreground)
      Sets the foreground color of the index panel. The default foreground color is the foreground colors of labels.
      Parameters:
      foreground - the foreground color
      Returns:
      this object, for use in a builder pattern

    • getBackgroundImage

      public File getBackgroundImage()
      Returns the background image file.
      Returns:
      the background image file or null if no background image file has been set.

    • backgroundImage

      public WizardIndex backgroundImage(File backgroundImage)
      Sets the background image file. A simple file name without a prefixed path like new File("image.png") is resolved to the resource directory. You can add image files on the Installer->Custom Code &Resources tab and use them that way.
      Parameters:
      backgroundImage - the image file
      Returns:
      this object, for use in a builder pattern

    • getBackgroundImageAnchor

      public Anchor getBackgroundImageAnchor()
      Returns the anchor for the background image file.
      Returns:
      the anchor

    • backgroundImageAnchor

      public WizardIndex backgroundImageAnchor(Anchor anchor)
      Sets the anchor for the background image file. The default anchor is SOUTH_WEST.
      Parameters:
      anchor - the anchor
      Returns:
      this object, for use in a builder pattern

    • getInitialKey

      public String getInitialKey()
      Returns the key of the step name that should be initially selected
      Returns:
      the key.

    • initialKey

      public WizardIndex initialKey(String initialKey)
      Sets the key of the step name that should be initially selected. By default, the first step will be selected.
      Parameters:
      initialKey - the key
      Returns:
      this object, for use in a builder pattern