/*******************************************************************************
* Copyright (c) 2012, 2013 Original authors and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Original authors and others - initial API and implementation
******************************************************************************/
package org.eclipse.nebula.widgets.nattable.layer;
import java.util.Collection;
import java.util.Properties;
import org.eclipse.nebula.widgets.nattable.NatTable;
import org.eclipse.nebula.widgets.nattable.command.ILayerCommand;
import org.eclipse.nebula.widgets.nattable.command.ILayerCommandHandler;
import org.eclipse.nebula.widgets.nattable.config.ConfigRegistry;
import org.eclipse.nebula.widgets.nattable.config.IConfigRegistry;
import org.eclipse.nebula.widgets.nattable.coordinate.Range;
import org.eclipse.nebula.widgets.nattable.layer.cell.ILayerCell;
import org.eclipse.nebula.widgets.nattable.layer.event.ILayerEvent;
import org.eclipse.nebula.widgets.nattable.layer.event.IVisualChangeEvent;
import org.eclipse.nebula.widgets.nattable.painter.cell.ICellPainter;
import org.eclipse.nebula.widgets.nattable.painter.layer.ILayerPainter;
import org.eclipse.nebula.widgets.nattable.persistence.IPersistable;
import org.eclipse.nebula.widgets.nattable.selection.SelectionLayer;
import org.eclipse.nebula.widgets.nattable.style.DisplayMode;
import org.eclipse.nebula.widgets.nattable.ui.binding.UiBindingRegistry;
import org.eclipse.nebula.widgets.nattable.util.IClientAreaProvider;
import org.eclipse.swt.graphics.Rectangle;
/**
* <p>
* A Layer is a rectangular region of grid cells. A layer has methods to access
* its columns, rows, width and height. A layer can be stacked on top of another
* layer in order to expose a transformed view of its underlying layer's grid
* cell structure.
* </p>
* <p>
* Columns and rows in a layer are referenced either by <b>position</b> or
* <b>index</b>. The position of a column/row in a layer corresponds to the
* physical location of the column/row in the layer. The index of a column/row
* in a layer corresponds to the location of the column/row in the lowest level
* layer in the layer stack. These concepts are illustrated by the following
* example:
* </p>
*
* <pre>
* Hide Layer C
* 0 1 2 3 4 <- column positions
* 1 0 3 4 5 <- column indexes
*
* Reorder Layer B
* 0 1 2 3 4 5 <- column positions
* 2 1 0 3 4 5 <- column indexes
*
* Data Layer A
* 0 1 2 3 4 5 <- column positions
* 0 1 2 3 4 5 <- column indexes
* </pre>
* <p>
* In the above example, Hide Layer C is stacked on top of Reorder Layer B,
* which is in turn stacked on top of Data Layer A. The positions in Data Layer
* A are the same as its indexes, because it is the lowest level layer in the
* stack. Reorder Layer B reorders column 0 of its underlying layer (Data Layer
* A) after column 2 of its underlying layer. Hide Layer C hides the first
* column of its underlying layer (Reorder Layer B).
* </p>
* <p>
* Layers can also be laterally composed into larger layers. For instance, the
* standard grid layer is composed of a body layer, column header layer, row
* header layer, and corner layer:
* </p>
* <table border=1>
* <caption></caption>
* <tr>
* <td>corner</td>
* <td>column header</td>
* </tr>
* <tr>
* <td>row header</td>
* <td>body</td>
* </tr>
* </table>
*
* @see CompositeLayer
*/
public interface ILayer extends ILayerListener, IPersistable {
// Dispose
public void dispose();
// Persistence
/**
* Persistables registered with a layer will have a chance to write their
* data out to the {@link Properties} instance when the layer is persisted.
*
* @param persistable
* the persistable to be registered
*/
public void registerPersistable(IPersistable persistable);
public void unregisterPersistable(IPersistable persistable);
// Configuration
/**
* Every layer gets this call back, starting at the top of the stack. This
* is triggered by the {@link NatTable#configure()} method. This is an
* opportunity to add any key/mouse bindings and other general
* configuration.
*
* @param configRegistry
* instance owned by {@link NatTable}
* @param uiBindingRegistry
* instance owned by {@link NatTable}
*/
public void configure(ConfigRegistry configRegistry,
UiBindingRegistry uiBindingRegistry);
// Region
/**
* Layer can apply its own labels to any cell it wishes.
*
* @param x
* the x pixel coordinate
* @param y
* the y pixel coordinate
* @return a LabelStack containing the region labels for the cell at the
* given pixel position
*/
public LabelStack getRegionLabelsByXY(int x, int y);
// Commands
/**
* Opportunity to respond to a command as it flows down the stack. If the
* layer is not interested in the command it should allow the command to
* keep traveling down the stack.
*
* Note: Before the layer can process a command it <i>must</i> convert the
* command to its local co-ordinates using
* {@link ILayerCommand#convertToTargetLayer(ILayer)}
*
* @param command
* the command to perform
* @return true if the command has been handled, false otherwise
*/
public boolean doCommand(ILayerCommand command);
public void registerCommandHandler(ILayerCommandHandler<?> commandHandler);
public void unregisterCommandHandler(
Class<? extends ILayerCommand> commandClass);
// Events
/**
* Events can be fired to notify other components of the grid. Events travel
* <i>up</i> the layer stack and may cause a repaint.
* <p>
* Example: When the contents of the grid change {@link IVisualChangeEvent}
* can be fired to notify other layers to refresh their caches etc.
*
* @param event
* the event to fire
*/
public void fireLayerEvent(ILayerEvent event);
public void addLayerListener(ILayerListener listener);
public void removeLayerListener(ILayerListener listener);
/**
* @param layerListenerClass
* The type of {@link ILayerListener} to check for existence
* @return <code>true</code> if this {@link ILayer} has a
* {@link ILayerListener} registered for the specified type,
* <code>false</code> if there is no such listener registered
* already
*/
public boolean hasLayerListener(
Class<? extends ILayerListener> layerListenerClass);
public ILayerPainter getLayerPainter();
// Client area
public IClientAreaProvider getClientAreaProvider();
public void setClientAreaProvider(IClientAreaProvider clientAreaProvider);
// Horizontal features
// Columns
/**
* @return the number of columns in this coordinate model
*/
public int getColumnCount();
public int getPreferredColumnCount();
/**
* Gets the underlying non-transformed column index for the given column
* position.
*
* @param columnPosition
* a column position relative to this coordinate model
* @return an underlying non-transformed column index, or -1 if the given
* column position does not exist within this coordinate system
*/
public int getColumnIndexByPosition(int columnPosition);
/**
* Convert a column position to the coordinates of the underlying layer.
* This is possible since each layer is aware of its underlying layer.
*
* @param localColumnPosition
* column position in local (the layer's own) coordinates
* @return column position in the underlying layer's coordinates
*/
public int localToUnderlyingColumnPosition(int localColumnPosition);
public int underlyingToLocalColumnPosition(ILayer sourceUnderlyingLayer,
int underlyingColumnPosition);
public Collection<Range> underlyingToLocalColumnPositions(
ILayer sourceUnderlyingLayer,
Collection<Range> underlyingColumnPositionRanges);
// Width
/**
* Returns the total width in pixels of this layer.
*
* @return the width of this layer
*/
public int getWidth();
public int getPreferredWidth();
/**
* Returns the width in pixels of the given column.
*
* The width of invisible and non-existing columns is 0.
*
* @param columnPosition
* the column position in this layer
*
* @return the width of the column
*/
public int getColumnWidthByPosition(int columnPosition);
// Column resize
public boolean isColumnPositionResizable(int columnPosition);
// X
/**
* Returns the column position that contains the given x coordinate.
*
* @param x
* a horizontal pixel location relative to the pixel boundary of
* this layer
* @return a column position relative to the associated coordinate system,
* or -1 if there is no column that contains x
*/
public int getColumnPositionByX(int x);
/**
* Returns the x offset in pixels of the given column.
*
* @param columnPosition
* the column position in this layer
* @return the x offset of the column, or -1
*/
public int getStartXOfColumnPosition(int columnPosition);
// Underlying
public Collection<ILayer> getUnderlyingLayersByColumnPosition(
int columnPosition);
// Vertical features
// Rows
/**
* @return the number of rows in this coordinate model
*/
public int getRowCount();
public int getPreferredRowCount();
/**
* Gets the underlying non-transformed row index for the given row position.
*
* @param rowPosition
* a row position relative to this coordinate model
* @return an underlying non-transformed row index, or -1 if the given row
* position does not exist within this coordinate system
*/
public int getRowIndexByPosition(int rowPosition);
public int localToUnderlyingRowPosition(int localRowPosition);
public int underlyingToLocalRowPosition(ILayer sourceUnderlyingLayer,
int underlyingRowPosition);
public Collection<Range> underlyingToLocalRowPositions(
ILayer sourceUnderlyingLayer,
Collection<Range> underlyingRowPositionRanges);
// Height
/**
* Returns the total height in pixels of this layer.
*
* @return the height of this layer
*/
public int getHeight();
public int getPreferredHeight();
/**
* Returns the height in pixels of the given row.
*
* The height of invisible and non-existing rows is 0.
*
* @param rowPosition
* the row position in this layer
*
* @return the height of the row
*/
public int getRowHeightByPosition(int rowPosition);
// Row resize
public boolean isRowPositionResizable(int rowPosition);
// Y
/**
* Returns the row position that contains the given y coordinate.
*
* @param y
* a vertical pixel location relative to the pixel boundary of
* this layer
* @return a row position relative to the associated coordinate system, or
* -1 if there is no row that contains y
*/
public int getRowPositionByY(int y);
/**
* Returns the y offset in pixels of the given row.
*
* @param rowPosition
* the row position in this layer
*
* @return the y offset of the row, or -1
*/
public int getStartYOfRowPosition(int rowPosition);
// Underlying
public Collection<ILayer> getUnderlyingLayersByRowPosition(int rowPosition);
// Cell features
public ILayerCell getCellByPosition(int columnPosition, int rowPosition);
/**
* Calculates the bounds in pixel for the given cell position.
*
* @param columnPosition
* the column position of the cell
* @param rowPosition
* the row position of the cell
*
* @return the bounds, or <code>null</code> if there are no valid bounds
*/
public Rectangle getBoundsByPosition(int columnPosition, int rowPosition);
/**
* @param columnPosition
* the column position of the cell
* @param rowPosition
* the row position of the cell
* @return {@link DisplayMode} for the cell at the given position. The
* {@link DisplayMode} affects the settings out of the
* {@link ConfigRegistry}. Display mode is <i>NORMAL</i> by default.
* <p>
* <b>Example:</b> {@link SelectionLayer} overrides this to return
* the <i>SELECT</i> label for cells which are selected.
*/
public String getDisplayModeByPosition(int columnPosition, int rowPosition);
public LabelStack getConfigLabelsByPosition(int columnPosition,
int rowPosition);
public Object getDataValueByPosition(int columnPosition, int rowPosition);
public ILayer getUnderlyingLayerByPosition(int columnPosition,
int rowPosition);
public ICellPainter getCellPainter(int columnPosition, int rowPosition,
ILayerCell cell, IConfigRegistry configRegistry);
}