# WizardIndex

Import: `import com.install4j.api.context.WizardIndex;`

```java
public class WizardIndex
```

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`](WizardContext.md#setwizardindex-wizardindex) in a script.
If you install the wizard index in the "Pre-activation script" property, it will be used for the current screen.
When installed in any other script, the set wizard index 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:
- 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 index 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.
- 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 index, 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 width 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 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)`

## Methods

| Signature | Returns | Description |
|---|---|---|
| [`getStepNames()`](#getstepnames) | `String[]` | Returns the step names |
| [`getKeys()`](#getkeys) | `String[]` | Returns the index keys |
| [`isPartiallyDefined()`](#ispartiallydefined) | `boolean` | Returns if the wizard index is partially defined. |
| [`partiallyDefined(boolean)`](#partiallydefined-boolean) | `WizardIndex` | Sets if the wizard index should be partially defined. |
| [`getMaxWidth()`](#getmaxwidth) | `int` | Returns the maximum width of the index panel |
| [`maxWidth(int)`](#maxwidth-int) | `WizardIndex` | Sets the maximum width of the index panel. |
| [`getMinWidth()`](#getminwidth) | `int` | Returns the minimum width of the index panel. |
| [`minWidth(int)`](#minwidth-int) | `WizardIndex` | Sets the minimum width of the index panel. |
| [`isNumbered()`](#isnumbered) | `boolean` | Returns if numbers should be added in front of each index step. |
| [`numbered(boolean)`](#numbered-boolean) | `WizardIndex` | Sets if numbers should be added in front of each index step. |
| [`getBackground()`](#getbackground) | `Color` | Returns the background color of the index panel |
| [`background(Color)`](#background-color) | `WizardIndex` | Sets the background color of the index panel. |
| [`getForeground()`](#getforeground) | `Color` | Returns the foreground color of the index panel used for the text color |
| [`foreground(Color)`](#foreground-color) | `WizardIndex` | Sets the foreground color of the index panel. |
| [`getBackgroundImage()`](#getbackgroundimage) | `File` | Returns the background image file. |
| [`backgroundImage(File)`](#backgroundimage-file) | `WizardIndex` | Sets the background image file. |
| [`getBackgroundImageAnchor()`](#getbackgroundimageanchor) | `Anchor` | Returns the anchor for the background image file. |
| [`backgroundImageAnchor(Anchor)`](#backgroundimageanchor-anchor) | `WizardIndex` | Sets the anchor for the background image file. |
| [`getInitialKey()`](#getinitialkey) | `String` | Returns the key of the step name that should be initially selected |
| [`initialKey(String)`](#initialkey-string) | `WizardIndex` | Sets the key of the step name that should be initially selected. |

### getStepNames()

```java
public String[] getStepNames()
```

Returns the step names


**Returns:** the step names

### getKeys()

```java
public String[] getKeys()
```

Returns the index keys


**Returns:** the index keys

### isPartiallyDefined()

```java
public boolean isPartiallyDefined()
```

Returns if the wizard index is partially defined.


**Returns:** if partially defined

### partiallyDefined(boolean)

```java
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()

```java
public int getMaxWidth()
```

Returns the maximum width of the index panel


**Returns:** the maximum width in pixels

### maxWidth(int)

```java
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()

```java
public int getMinWidth()
```

Returns the minimum width of the index panel.


**Returns:** the minimum width in pixels

### minWidth(int)

```java
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()

```java
public boolean isNumbered()
```

Returns if numbers should be added in front of each index step.


**Returns:** `true` or `false`

### numbered(boolean)

```java
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()

```java
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(Color)

```java
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()

```java
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(Color)

```java
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()

```java
public File getBackgroundImage()
```

Returns the background image file.


**Returns:** the background image file or `null` if no background image file has been set.

### backgroundImage(File)

```java
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()

```java
public Anchor getBackgroundImageAnchor()
```

Returns the anchor for the background image file.


**Returns:** the anchor

### backgroundImageAnchor(Anchor)

```java
public WizardIndex backgroundImageAnchor(Anchor anchor)
```

Sets the anchor for the background image file. The default anchor is [`Anchor.SOUTHWEST`](../beans/Anchor.md#southwest).


**Parameters:**

- `anchor` — the anchor

**Returns:** this object, for use in a builder pattern

### getInitialKey()

```java
public String getInitialKey()
```

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


**Returns:** the key.

### initialKey(String)

```java
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

## Constructors

| Signature | Description |
|---|---|
| [`WizardIndex(String[])`](#wizardindex-string) | 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(String[], String[])`](#wizardindex-string-string) | Construct a wizard index with the specified step names and index keys. |

### WizardIndex(String[])

```java
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(String[], String[])

```java
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`](WizardContext.md#setwizardindexkey-string)

