WizardIndex (install4j API)
Date: 2010-09-29

Overview | Package | Class | Tree | Deprecated | Index | Help
| install4j API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.install4j.api.context
Class WizardIndex

    java.lang.Object
      com.install4j.api.context.WizardIndex

    public class WizardIndex

extends java.lang.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)`

Author:
  ej-technologies GmbH

Constructor Summary
`WizardIndex(java.lang.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.
`WizardIndex(java.lang.String[] stepNames, java.lang.String[] keys)` Construct a wizard index with the specified step names and index keys.

Method Summary
`WizardIndex` | `background(java.awt.Color background)` Sets the background color of the index panel.
`WizardIndex` | `backgroundImage(java.io.File backgroundImage)` Sets the background image file.
`WizardIndex` | `backgroundImageAnchor(Anchor anchor)` Sets the anchor for the background image file.
`WizardIndex` | `foreground(java.awt.Color foreground)` Sets the foreground color of the index panel.
`java.awt.Color` | `getBackground()` Returns the background color of the index panel
`java.io.File` | `getBackgroundImage()` Returns the background image file.
`Anchor` | `getBackgroundImageAnchor()` Returns the anchor for the background image file.
`java.awt.Color` | `getForeground()` Returns the foreground color of the index panel used for the text color
`java.lang.String` | `getInitialKey()` Returns the key of the step name that should be initially selected
`java.lang.String[]` | `getKeys()` Returns the index keys
`int` | `getMaxWidth()` Returns the maximum width of the index panel
`int` | `getMinWidth()` Returns the minimum width of the index panel.
`java.lang.String[]` | `getStepNames()` Returns the step names
`WizardIndex` | `initialKey(java.lang.String initialKey)` Sets the key of the step name that should be initially selected.
`boolean` | `isNumbered()` Returns if numbers should be added in front of each index step.
`boolean` | `isPartiallyDefined()` Returns of the wizard index is partially defined.
`WizardIndex` | `maxWidth(int maxWidth)` Sets the maximum width of the index panel.
`WizardIndex` | `minWidth(int minWidth)` Sets the minimum width of the index panel.
`WizardIndex` | `numbered(boolean numbered)` Sets if numbers should be added in front of each index step.
`WizardIndex` | `partiallyDefined(boolean partiallyDefined)` Sets if the wizard index should be partially defined.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### WizardIndex

    public WizardIndex(java.lang.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(java.lang.String[] stepNames,
                       java.lang.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 Detail

### getStepNames

    public java.lang.String[] getStepNames()

  Returns the step names

  Returns:
    the step names

### getKeys

    public java.lang.String[] getKeys()

  Returns the index keys

  Returns:
    the index keys

### isPartiallyDefined

    public boolean isPartiallyDefined()

  Returns of 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 java.awt.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(java.awt.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 java.awt.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(java.awt.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 java.io.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(java.io.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 java.lang.String getInitialKey()

  Returns the key of the step name that should be initially selected

  Returns:
    the key.

### initialKey

    public WizardIndex initialKey(java.lang.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

Overview | Package | Class | Tree | Deprecated | Index | Help
| install4j API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD