# Configuration

NatTable allows to use configuration to customize the styling and behavior of the layers and the table . Every layer typically introduces configurations for the features they add.

Configurations are registered via registries. There are two configuration registries for each NatTable instance:

## `IConfigRegistry`

This is a global object holding the configuration attributes for the following kinds of configuration:
* Styling
* Editing
* Comparators for sorting
* Any other information that should be configurable

## `IUiBindingRegistry`

This is a global object holding the following kinds of configuration:
* Key bindings
* Mouse bindings

## Configuration classes

It is recommended to create separate configuration classes to encapsulate the different configurations. It is also possible to put configurations directly into a registry which is mostly used for dynamic behavior changes at runtime. There are four types of configuration classes:

* `AbstractRegistryConfiguration`  
Used to register configuration values to the `IConfigRegistry`.

* `AbstractUiBindingConfiguration`  
Used to bind actions to UI interactions via `IUIBindingRegistry`.

* `AbstractLayerConfiguration`  
Used to configure an `ILayer`. This typically means to register `ILayerCommandHandler` and `ILayerEventHandler` on a layer.

* `AggregateConfiguration`  
Used to combine several configurations in one. Several default configurations delivered with NatTable are implementations of `AggregateConfiguration`. Using this only one configuration instance needs to be registered to add a configuration for styling and ui binding at once.

The following simplified UML diagram shows the relationship between configurations, the NatTable and layers.

![Simplified NatTable configuration UML](images/NatTable_Configuration_UML_simplified.png)

## `DisplayMode`

In NatTable a cell can have several modes in which they are displayed. These modes are called `DisplayMode`. This allows to specify different configurations for the same cell in different modes. The following table lists the currently supported display modes.

| DisplayMode                | Description                                                                                                                                                      |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DisplayMode#NORMAL`       | The normal state a cell is in if no other state applies.                                                                                                         |
| `DisplayMode#SELECT`       | The state that shows that a cell is currently selected.                                                                                                          |
| `DisplayMode#EDIT`         | The state that shows that a cell is currently edited.<br>**Note:**<br>This `DisplayMode` is never applied to a cell and is only used for configuration purposes! |
| `DisplayMode#HOVER`        | The state that shows that currently the mouse hovers over the cell.                                                                                              |
| `DisplayMode#SELECT_HOVER` | The state that shows that currently the mouse hovers over the cell that is currently selected.                                                                   |

## Cell labels

NatTable supports conditional configuration via a label mechanism. This means that it is possible to add labels to a cell and register configurations for labels.

Every cell in a NatTable has a `LabelStack`, which is a collection of Strings. Via labels it is possible to tie configurations to specific cells, for example styling a cell with a special error style or configure a checkbox editor for a cell that contains boolean values.

### Default labels

When using a `CompositeLayer` it is possible to set a region label per composition region. You can think of the region label as a default label that is applied to every cell in the corresponding region, e.g. every cell in the body region of a grid has the label `GridRegion.BODY` in its `LabelStack`.

### Labels by layer

Every layer is able to add labels to a cells label stack in the `ILayer#getConfigLabelsByPosition(int, int)` method. This way layer specific stylings are added, e.g. a sort indicator in the column header cells in case the `SortHeaderLayer` is involved.

### Custom labels

It is possible to add custom labels by using an `IConfigLabelAccumulator`. Each layer in the layer composition can take an `IConfigLabelAccumulator` which can be set by calling `AbstractLayer#setConfigLabelAccumulator(IConfigLabelAccumulator)`.

NatTable ships with several default implementations that can be used to register custom labels. Some of them implement `AbstractOverrider` and allow registering of labels for special criteria.

| Default implementation           | Description                                                                                                                                                                                                                                                                                                    |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CellOverrideLabelAccumulator`   | Registers a label that is applied in case the specified value is shown in the specified column.<br>`registerOverride(Object cellValue, int col, String configLabel)`                                                                                                                                           |
| `ColumnOverrideLabelAccumulator` | Register labels that will be added to the label stack of cells in the column of the specified index.<br>`registerColumnOverrides(int columnIndex, String…​ configLabels)`<br>`registerColumnOverridesOnTop(int columnIndex, String…​ configLabels)`                                                            |
| `RowOverrideLabelAccumulator`    | Register labels that will be added to the label stack of cells in the row of the specified index.<br>`registerOverrides(int rowIndex, String…​configLabels)`                                                                                                                                                   |
| `ColumnLabelAccumulator`         | Automatically registers column based labels to the label stack. The labels follow the pattern `COLUMN_` + \<column position\>. Via the constant `ColumnLabelAccumulator#COLUMN_LABEL_PREFIX` concatenated with the column position, it is possible to register custom configurations for those default labels. |

It is also possible tom create a custom `IConfigLabelAccumulator` to handle situations where the default implementations doesn't match. By implementing `IConfigLabelAccumulator#accumulateConfigLabels(LabelStack, int, int)` it is possible to add additional labels to the given `LabelStack`. You can simply add a custom label by calling `LabelStack#addLabel(String)` which means it will be added to the end of the stack. To ensure the newly added label gets a higher priority the `LabelStack#addLabelOnTop(String)` method can be called, which will add the new label at the first position of the label stack.

_**Note:**_  
Setting a label at the top of a label stack doesn’t ensure that no other layer or accumulator adds another label on top afterwards.