04_Configuration

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.

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. Note: 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. 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. registerColumnOverrides(int columnIndex, String…​ configLabels) 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. 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.