com.vaadin.v7.client.widget.escalator.RowContainer Maven / Gradle / Ivy
Show all versions of vaadin-compatibility-client Show documentation
/*
* Copyright (C) 2000-2023 Vaadin Ltd
*
* This program is available under Vaadin Commercial License and Service Terms.
*
* See for the full
* license.
*/
package com.vaadin.v7.client.widget.escalator;
import com.google.gwt.dom.client.Element;
import com.google.gwt.dom.client.TableRowElement;
import com.google.gwt.dom.client.TableSectionElement;
import com.vaadin.v7.client.widgets.Escalator;
/**
* A representation of the rows in each of the sections (header, body and
* footer) in an {@link Escalator}.
*
* @since 7.4
* @author Vaadin Ltd
* @see Escalator#getHeader()
* @see Escalator#getBody()
* @see Escalator#getFooter()
* @see SpacerContainer
*/
public interface RowContainer {
/**
* The row container for the body section in an {@link Escalator}.
*
* The body section can contain both rows and spacers.
*
* @since 7.5.0
* @author Vaadin Ltd
* @see Escalator#getBody()
*/
public interface BodyRowContainer extends RowContainer {
/**
* Marks a spacer and its height.
*
* If a spacer is already registered with the given row index, that
* spacer will be updated with the given height.
*
* Note: The row index for a spacer will change if rows are
* inserted or removed above the current position. Spacers will also be
* removed alongside their associated rows
*
* @param rowIndex
* the row index for the spacer to modify. The affected
* spacer is underneath the given index. Use -1 to insert a
* spacer before the first row
* @param height
* the pixel height of the spacer. If {@code height} is
* negative, the affected spacer (if exists) will be removed
* @throws IllegalArgumentException
* if {@code rowIndex} is not a valid row index
* @see #insertRows(int, int)
* @see #removeRows(int, int)
*/
void setSpacer(int rowIndex, double height)
throws IllegalArgumentException;
/**
* Sets a new spacer updater.
*
* Spacers that are currently visible will be updated, i.e.
* {@link SpacerUpdater#destroy(Spacer) destroyed} with the previous
* one, and {@link SpacerUpdater#init(Spacer) initialized} with the new
* one.
*
* @param spacerUpdater
* the new spacer updater
* @throws IllegalArgumentException
* if {@code spacerUpdater} is {@code null}
*/
void setSpacerUpdater(SpacerUpdater spacerUpdater)
throws IllegalArgumentException;
/**
* Gets the spacer updater currently in use.
*
* {@link SpacerUpdater#NULL} is the default.
*
* @return the spacer updater currently in use. Never null
*/
SpacerUpdater getSpacerUpdater();
/**
* {@inheritDoc}
*
* Any spacers underneath {@code index} will be offset and "pushed"
* down. This also modifies the row index they are associated with.
*/
@Override
public void insertRows(int index, int numberOfRows)
throws IndexOutOfBoundsException, IllegalArgumentException;
/**
* {@inheritDoc}
*
* Any spacers underneath {@code index} will be offset and "pulled" up.
* This also modifies the row index they are associated with. Any
* spacers in the removed range will also be closed and removed.
*/
@Override
public void removeRows(int index, int numberOfRows)
throws IndexOutOfBoundsException, IllegalArgumentException;
}
/**
* An arbitrary pixel height of a row, before any autodetection for the row
* height has been made.
*/
public static final double INITIAL_DEFAULT_ROW_HEIGHT = 20;
/**
* Returns the current {@link EscalatorUpdater} used to render cells.
*
* @return the current escalator updater
*/
public EscalatorUpdater getEscalatorUpdater();
/**
* Sets the {@link EscalatorUpdater} to use when displaying data in the
* escalator.
*
* @param escalatorUpdater
* the escalator updater to use to render cells. May not be
* null
* @throws IllegalArgumentException
* if {@code cellRenderer} is null
* @see EscalatorUpdater#NULL
*/
public void setEscalatorUpdater(EscalatorUpdater escalatorUpdater)
throws IllegalArgumentException;
/**
* Removes rows at a certain index in the current row container.
*
* @param index
* the index of the first row to be removed
* @param numberOfRows
* the number of rows to remove, starting from the index
* @throws IndexOutOfBoundsException
* if any integer number in the range
* [index..(index+numberOfRows)] is not an existing
* row index
* @throws IllegalArgumentException
* if {@code numberOfRows} is less than 1.
*/
public void removeRows(int index, int numberOfRows)
throws IndexOutOfBoundsException, IllegalArgumentException;
/**
* Adds rows at a certain index in this row container.
*
* The new rows will be inserted between the row at the index, and the row
* before (an index of 0 means that the rows are inserted at the beginning).
* Therefore, the rows currently at the index and afterwards will be moved
* downwards.
*
* The contents of the inserted rows will subsequently be queried from the
* escalator updater.
*
* Note: Only the contents of the inserted rows will be rendered.
* If inserting new rows affects the contents of existing rows,
* {@link #refreshRows(int, int)} needs to be called for those rows
* separately.
*
* @param index
* the index of the row before which new rows are inserted, or
* {@link #getRowCount()} to add rows at the end
* @param numberOfRows
* the number of rows to insert after the index
* @see #setEscalatorUpdater(EscalatorUpdater)
* @throws IndexOutOfBoundsException
* if index is not an integer in the range
* [0..{@link #getRowCount()}]
* @throws IllegalArgumentException
* if {@code numberOfRows} is less than 1.
*/
public void insertRows(int index, int numberOfRows)
throws IndexOutOfBoundsException, IllegalArgumentException;
/**
* Refreshes a range of rows in the current row container.
*
* The data for the refreshed rows is queried from the current cell
* renderer.
*
* @param index
* the index of the first row that will be updated
* @param numberOfRows
* the number of rows to update, starting from the index
* @see #setEscalatorUpdater(EscalatorUpdater)
* @throws IndexOutOfBoundsException
* if any integer number in the range
* [index..(index+numberOfColumns)] is not an
* existing column index.
* @throws IllegalArgumentException
* if {@code numberOfRows} is less than 1.
*/
public void refreshRows(int index, int numberOfRows)
throws IndexOutOfBoundsException, IllegalArgumentException;
/**
* Gets the number of rows in the current row container.
*
* @return the number of rows in the current row container
*/
public int getRowCount();
/**
* This method calculates the current row count directly from the DOM.
*
* While the container is stable, this value should equal to
* {@link #getRowCount()}, but while row counts are being updated, these two
* values might differ for a short while.
*
* Any extra content, such as spacers for the body, should not be included
* in this count.
*
* @since 8.7
*
* @return the actual DOM count of rows
*/
public int getDomRowCount();
/**
* The default height of the rows in this RowContainer.
*
* @param px
* the default height in pixels of the rows in this RowContainer
* @throws IllegalArgumentException
* if px < 1
* @see #getDefaultRowHeight()
*/
public void setDefaultRowHeight(double px) throws IllegalArgumentException;
/**
* Returns the default height of the rows in this RowContainer.
*
* This value will be equal to {@link #INITIAL_DEFAULT_ROW_HEIGHT} if the
* {@link Escalator} has not yet had a chance to autodetect the row height,
* or no explicit value has yet given via {@link #setDefaultRowHeight(int)}
*
* @return the default height of the rows in this RowContainer, in pixels
* @see #setDefaultRowHeight(int)
*/
public double getDefaultRowHeight();
/**
* Returns the cell object which contains information about the cell the
* element is in.
*
* @param element
* The element to get the cell for. If element is not present in
* row container then null is returned.
*
* @return the cell of the element, or null if element is not
* present in the {@link RowContainer}.
*/
public Cell getCell(Element element);
/**
* Gets the row element with given logical index. For lazy loaded containers
* such as Escalators BodyRowContainer visibility should be checked before
* calling this function. See {@link Escalator#getVisibleRowRange()}.
*
* @param index
* the logical index of the element to retrieve
* @return the element at position {@code index}
* @throws IndexOutOfBoundsException
* if {@code index} is not valid within container
* @throws IllegalStateException
* if {@code index} is currently not available in the DOM
*/
public TableRowElement getRowElement(int index)
throws IndexOutOfBoundsException, IllegalStateException;
/**
* Returns the root element of RowContainer.
*
* @return RowContainer root element
*/
public TableSectionElement getElement();
}