Package com.vaadin.client.widgets

Class Escalator.AbstractRowContainer

  • All Implemented Interfaces:
    RowContainer
    Enclosing class:
    Escalator
    public abstract class Escalator.AbstractRowContainer
extends Object
implements RowContainer
    A representation of the rows within a section (header, body, or footer).

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected com.google.gwt.dom.client.TableSectionElement root
      The table section element (<thead>, <tbody> or <tfoot>) the rows (i.e.

    • Constructor Summary

      Constructors 
      Constructor Description
      AbstractRowContainer​(com.google.gwt.dom.client.TableSectionElement rowContainerElement)
      Constructs a row container that uses the given table section element as the root element for the rows.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected void assertArgumentsAreValidAndWithinRange​(int index, int numberOfRows)
      Checks validity of the given arguments for a row range that needs handling.
      void autodetectRowHeightLater()
      Triggers delayed auto-detection of default row height if it hasn't been set by that point and the Escalator is both attached and displayed.
      void autodetectRowHeightNow()
      Auto-detect row height immediately, if possible.
      double calculateMaxColWidth​(int index)
      Iterates through all the cells in a column and returns the width of the widest element in this RowContainer.
      protected double calculateTotalRowHeight()
      Returns the height of all rows in the row container.
      com.google.gwt.dom.client.TableCellElement createCellElement​(double width)
      Create and setup an empty cell element.
      Cell getCell​(com.google.gwt.dom.client.Element element)
      Returns the cell object which contains information about the cell the element is in.
      protected Escalator.AriaGridRole getCellElementRole()
      Gets the role attribute of an element to represent a cell in a row.
      protected abstract String getCellElementTagName()
      Gets the tag name of an element to represent a cell in a row.
      double getDefaultRowHeight()
      Returns the default height of the rows in this RowContainer.
      abstract int getDomRowCount()
      This method calculates the current row count directly from the DOM.
      com.google.gwt.dom.client.TableSectionElement getElement()
      Returns the root element of RowContainer.
      EscalatorUpdater getEscalatorUpdater()
      Returns the current EscalatorUpdater used to render cells.
      protected abstract double getHeightOfSection()
      The height of this table section.
      int getLogicalRowIndex​(com.google.gwt.dom.client.TableRowElement tr)
      Gets the logical row index for the given table row element.
      int getRowCount()
      Gets the number of rows in the current row container.
      com.google.gwt.dom.client.TableRowElement getRowElement​(int index)
      Gets the row element with given logical index.
      protected Escalator.AriaGridRole getRowElementRole()
      Gets the role attribute of an element to represent a row in a grid.
      protected double getRowTop​(com.google.gwt.dom.client.TableRowElement tr)
      Returns the assigned top position for the given element.
      protected String getStylePrimaryName()
      Returns the primary style name of the container.
      protected abstract com.google.gwt.dom.client.TableRowElement getTrByVisualIndex​(int index)
      Gets the child element that is visually at a certain index.
      void insertRows​(int index, int numberOfRows)
      Adds rows at a certain index in this row container.
      boolean isAutodetectingRowHeightLater()
      For internal use only.
      protected void paintInsertColumns​(int offset, int numberOfColumns, boolean frozen)
      Add the given number of columns starting from the given index.
      protected com.google.gwt.dom.client.Node paintInsertRow​(com.google.gwt.dom.client.Node referenceRow, com.google.gwt.dom.client.TableRowElement tr, int logicalRowIndex)
      Inserts a single row into the DOM, invoking getEscalatorUpdater() preAttach and postAttach before and after inserting the row, respectively.
      protected abstract void paintInsertRows​(int visualIndex, int numberOfRows)
      Actually add rows into the DOM, now that everything can be calculated.
      protected List<com.google.gwt.dom.client.TableRowElement> paintInsertStaticRows​(int visualIndex, int numberOfRows)
      Add static rows into the DOM.
      protected void paintRemoveColumns​(int offset, int numberOfColumns)
      Remove the given number of columns starting from the given index.
      protected void paintRemoveRow​(com.google.gwt.dom.client.TableRowElement tr, int logicalRowIndex)
      Removes a row element from the DOM, invoking getEscalatorUpdater() preDetach and postDetach before and after removing the row, respectively.
      protected abstract void paintRemoveRows​(int index, int numberOfRows)
      Removes those row elements from the DOM that correspond to the given range of logical indices.
      void reapplyColumnWidths()
      Reapplies all the cells' widths according to the calculated widths in the column configuration.
      protected abstract void reapplyDefaultRowHeights()
      The default height of rows has (most probably) changed.
      protected void reapplyRowHeight​(com.google.gwt.dom.client.TableRowElement tr, double heightPx)
      Updates the cells within the row to the given height.
      protected void reapplyRowWidths()
      Applies the total length of the columns to each row element.
      protected abstract void recalculateSectionHeight()
      Triggers section height calculation.
      protected abstract void refreshCells​(Range logicalRowRange, Range colRange)
      Refresh cells within the given row and column ranges.
      void refreshRows​(int index, int numberOfRows)
      Refreshes a range of rows in the current row container.
      protected void removeRowPosition​(com.google.gwt.dom.client.TableRowElement tr)
      Removes the given row from the position bookkeeping.
      void removeRows​(int index, int numberOfRows)
      Removes rows at a certain index in the current row container.
      protected abstract boolean rowCanBeFrozen​(com.google.gwt.dom.client.TableRowElement tr)
      Checks whether a row is an element, or contains such elements, that can be frozen.
      void setColumnFrozen​(int column, boolean frozen)
      Sets a column's frozen status.
      void setColumnLastFrozen​(int column, boolean lastFrozen)
      Sets the last frozen state of the given column.
      void setDefaultRowHeight​(double px)
      The default height of the rows in this RowContainer.
      void setEscalatorUpdater​(EscalatorUpdater escalatorUpdater)
      Sets the EscalatorUpdater to use when displaying data in the escalator.
      protected void setRowPosition​(com.google.gwt.dom.client.TableRowElement tr, int x, double y)
      Updates the position of the given row to the given coordinates.
      protected void setStylePrimaryName​(String primaryStyleName)
      The primary style name for the container.
      void updateFreezePosition​(int column, double scrollLeft)
      Updates the freeze position for the given column.

    • Field Detail

      • root

        protected final com.google.gwt.dom.client.TableSectionElement root
        The table section element (<thead>, <tbody> or <tfoot>) the rows (i.e. <tr> tags) are contained in.

    • Constructor Detail

      • AbstractRowContainer

        public AbstractRowContainer​(com.google.gwt.dom.client.TableSectionElement rowContainerElement)
        Constructs a row container that uses the given table section element as the root element for the rows.
        Parameters:
        rowContainerElement - the table section element

    • Method Detail

      • getElement

        public com.google.gwt.dom.client.TableSectionElement getElement()
        Description copied from interface: RowContainer
        Returns the root element of RowContainer.
        Specified by:
        getElement in interface RowContainer
        Returns:
        RowContainer root element

      • getCellElementTagName

        protected abstract String getCellElementTagName()
        Gets the tag name of an element to represent a cell in a row.

        Usually "th" or "td".

        Note: To actually create such an element, use createCellElement(double) instead.

        Returns:
        the tag name for the element to represent cells as
        See Also:
        createCellElement(double)

      • getCellElementRole

        protected Escalator.AriaGridRole getCellElementRole()
        Gets the role attribute of an element to represent a cell in a row.

        Usually Escalator.AriaGridRole.GRIDCELL except for a cell in the header.

        Returns:
        the role attribute for the element to represent cells
        Since:
        8.2

      • getRowElementRole

        protected Escalator.AriaGridRole getRowElementRole()
        Gets the role attribute of an element to represent a row in a grid.

        Usually Escalator.AriaGridRole.ROW except for a row in the header.

        Returns:
        the role attribute for the element to represent rows
        Since:
        8.2

      • setEscalatorUpdater

        public void setEscalatorUpdater​(EscalatorUpdater escalatorUpdater)
        Sets the EscalatorUpdater to use when displaying data in the escalator.

        Implementation detail: This method does no DOM modifications (i.e. is very cheap to call) if there is no data for rows or columns when this method is called.

        Specified by:
        setEscalatorUpdater in interface RowContainer
        Parameters:
        escalatorUpdater - the escalator updater to use to render cells. May not be null
        See Also:
        Escalator.hasColumnAndRowData()

      • removeRows

        public void removeRows​(int index,
                       int numberOfRows)
        Removes rows at a certain index in the current row container.

        Implementation detail: This method does no DOM modifications (i.e. is very cheap to call) if there are no rows in the DOM when this method is called.

        Specified by:
        removeRows in interface RowContainer
        Parameters:
        index - the index of the first row to be removed
        numberOfRows - the number of rows to remove, starting from the index
        See Also:
        Escalator.hasSomethingInDom()

      • paintRemoveRows

        protected abstract void paintRemoveRows​(int index,
                                        int numberOfRows)
        Removes those row elements from the DOM that correspond to the given range of logical indices. This may be fewer than numberOfRows , even zero, if not all the removed rows are actually visible.

        The implementation must call paintRemoveRow(TableRowElement, int) for each row that is removed from the DOM.

        Parameters:
        index - the logical index of the first removed row
        numberOfRows - number of logical rows to remove

      • paintRemoveRow

        protected void paintRemoveRow​(com.google.gwt.dom.client.TableRowElement tr,
                              int logicalRowIndex)
        Removes a row element from the DOM, invoking getEscalatorUpdater() preDetach and postDetach before and after removing the row, respectively.

        This method must be called for each removed DOM row by any paintRemoveRows(int, int) implementation.

        Parameters:
        tr - the row element to remove.
        logicalRowIndex - logical index of the row that is to be removed

      • assertArgumentsAreValidAndWithinRange

        protected void assertArgumentsAreValidAndWithinRange​(int index,
                                                     int numberOfRows)
                                              throws IllegalArgumentException,
                                                     IndexOutOfBoundsException
        Checks validity of the given arguments for a row range that needs handling. Throws an exception if the arguments are not valid.
        Parameters:
        index - the start index of the range
        numberOfRows - the number of rows within the range
        Throws:
        IllegalArgumentException - if the range doesn't have a positive length
        IndexOutOfBoundsException - if the entire range doesn't fit within the existing rows

      • getRowCount

        public int getRowCount()
        Description copied from interface: RowContainer
        Gets the number of rows in the current row container.
        Specified by:
        getRowCount in interface RowContainer
        Returns:
        the number of rows in the current row container

      • getDomRowCount

        public abstract int getDomRowCount()
        This method calculates the current row count directly from the DOM.

        While Escalator is stable, this value should equal to 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.

        Returns:
        the actual DOM count of rows
        Since:
        7.5.0

      • insertRows

        public void insertRows​(int index,
                       int numberOfRows)
        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, RowContainer.refreshRows(int, int) needs to be called for those rows separately.

        Implementation detail: This method does no DOM modifications (i.e. is very cheap to call) if there is no data for columns when this method is called.

        Specified by:
        insertRows in interface RowContainer
        Parameters:
        index - the index of the row before which new rows are inserted, or RowContainer.getRowCount() to add rows at the end
        numberOfRows - the number of rows to insert after the index
        See Also:
        Escalator.hasColumnAndRowData()

      • paintInsertRows

        protected abstract void paintInsertRows​(int visualIndex,
                                        int numberOfRows)
        Actually add rows into the DOM, now that everything can be calculated.
        Parameters:
        visualIndex - the DOM index to add rows into
        numberOfRows - the number of rows to insert

      • paintInsertStaticRows

        protected List<com.google.gwt.dom.client.TableRowElement> paintInsertStaticRows​(int visualIndex,
                                                                                int numberOfRows)
        Add static rows into the DOM. Usually this would be considered to mean only header or footer rows, but the body row container implementation also uses this method to get a starting point for further modifications.
        Parameters:
        visualIndex - the DOM index to add rows into
        numberOfRows - the number of rows to insert
        Returns:
        a list of added row elements

      • paintInsertRow

        protected com.google.gwt.dom.client.Node paintInsertRow​(com.google.gwt.dom.client.Node referenceRow,
                                                        com.google.gwt.dom.client.TableRowElement tr,
                                                        int logicalRowIndex)
        Inserts a single row into the DOM, invoking getEscalatorUpdater() preAttach and postAttach before and after inserting the row, respectively. The row should have its cells already inserted.
        Parameters:
        referenceRow - the row after which to insert or null if insert as first
        tr - the row to be inserted
        logicalRowIndex - the logical index of the inserted row
        Returns:
        the inserted row to be used as the new reference

      • recalculateSectionHeight

        protected abstract void recalculateSectionHeight()
        Triggers section height calculation. Does nothing by default if called for the body row section, because body section height handling has more complicated logic. Note that updating header or footer height triggers a check that the body has correct amount of rows and their spacers.

      • calculateTotalRowHeight

        protected double calculateTotalRowHeight()
        Returns the height of all rows in the row container.
        Returns:
        total height of container's rows

      • refreshRows

        public void refreshRows​(int index,
                        int numberOfRows)
        Refreshes a range of rows in the current row container.

        The data for the refreshed rows is queried from the current cell renderer.

        Implementation detail: This method does no DOM modifications (i.e. is very cheap to call) if there is no data for columns when this method is called.

        Specified by:
        refreshRows in interface RowContainer
        Parameters:
        index - the index of the first row that will be updated
        numberOfRows - the number of rows to update, starting from the index
        See Also:
        Escalator.hasColumnAndRowData()

      • refreshCells

        protected abstract void refreshCells​(Range logicalRowRange,
                                     Range colRange)
        Refresh cells within the given row and column ranges.
        Parameters:
        logicalRowRange - the range within the logical row indexes
        colRange - the range within the column indexes

      • createCellElement

        public com.google.gwt.dom.client.TableCellElement createCellElement​(double width)
        Create and setup an empty cell element.
        Parameters:
        width - the width of the cell, in pixels
        Returns:
        a set-up empty cell element

      • getRowElement

        public com.google.gwt.dom.client.TableRowElement getRowElement​(int index)
        Description copied from interface: RowContainer
        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 Escalator.getVisibleRowRange().
        Specified by:
        getRowElement in interface RowContainer
        Parameters:
        index - the logical index of the element to retrieve
        Returns:
        the element at position index

      • getTrByVisualIndex

        protected abstract com.google.gwt.dom.client.TableRowElement getTrByVisualIndex​(int index)
                                                                         throws IndexOutOfBoundsException
        Gets the child element that is visually at a certain index.
        Parameters:
        index - the index of the element to retrieve
        Returns:
        the element at position index
        Throws:
        IndexOutOfBoundsException - if index is not valid within root

      • paintRemoveColumns

        protected void paintRemoveColumns​(int offset,
                                  int numberOfColumns)
        Remove the given number of columns starting from the given index.
        Parameters:
        offset - the index of the first column to remove
        numberOfColumns - the number of columns to remove

      • paintInsertColumns

        protected void paintInsertColumns​(int offset,
                                  int numberOfColumns,
                                  boolean frozen)
        Add the given number of columns starting from the given index. Frozen columns shouldn't be added after non-frozen columns.
        Parameters:
        offset - the index of the first column to add
        numberOfColumns - the number of columns to add
        frozen - true if the added columns should be frozen, false otherwise

      • setColumnFrozen

        public void setColumnFrozen​(int column,
                            boolean frozen)
        Sets a column's frozen status. Frozen columns shouldn't be added after non-frozen columns.
        Parameters:
        column - the index of the column
        frozen - true if the column should be frozen, false otherwise

      • setColumnLastFrozen

        public void setColumnLastFrozen​(int column,
                                boolean lastFrozen)
        Sets the last frozen state of the given column.
        Parameters:
        column - the index of the column
        lastFrozen - true if the column is the last frozen one, false otherwise

      • updateFreezePosition

        public void updateFreezePosition​(int column,
                                 double scrollLeft)
        Updates the freeze position for the given column.
        Parameters:
        column - the index of the column
        scrollLeft - the x coordinate, in pixels

      • rowCanBeFrozen

        protected abstract boolean rowCanBeFrozen​(com.google.gwt.dom.client.TableRowElement tr)
        Checks whether a row is an element, or contains such elements, that can be frozen.

        In practice, this applies for all header and footer rows. For body rows, it applies for all rows except spacer rows.

        Parameters:
        tr - the row element to check whether it, or any of its its descendants can be frozen
        Returns:
        true if the given element, or any of its descendants, can be frozen
        Since:
        7.5.0

      • calculateMaxColWidth

        public double calculateMaxColWidth​(int index)
        Iterates through all the cells in a column and returns the width of the widest element in this RowContainer.
        Parameters:
        index - the index of the column to inspect
        Returns:
        the pixel width of the widest element in the indicated column

      • reapplyColumnWidths

        public void reapplyColumnWidths()
        Reapplies all the cells' widths according to the calculated widths in the column configuration.

      • reapplyRowWidths

        protected void reapplyRowWidths()
        Applies the total length of the columns to each row element.

        Note: In contrast to reapplyColumnWidths(), this method only modifies the width of the <tr> element, not the cells within.

      • setStylePrimaryName

        protected void setStylePrimaryName​(String primaryStyleName)
        The primary style name for the container.
        Parameters:
        primaryStyleName - the style name to use as prefix for all row and cell style names.

      • getStylePrimaryName

        protected String getStylePrimaryName()
        Returns the primary style name of the container.
        Returns:
        The primary style name or null if not set.

      • getDefaultRowHeight

        public double getDefaultRowHeight()
        Description copied from interface: RowContainer
        Returns the default height of the rows in this RowContainer.

        This value will be equal to RowContainer.INITIAL_DEFAULT_ROW_HEIGHT if the Escalator has not yet had a chance to autodetect the row height, or no explicit value has yet given via #setDefaultRowHeight(int)

        Specified by:
        getDefaultRowHeight in interface RowContainer
        Returns:
        the default height of the rows in this RowContainer, in pixels
        See Also:
        #setDefaultRowHeight(int)

      • reapplyDefaultRowHeights

        protected abstract void reapplyDefaultRowHeights()
        The default height of rows has (most probably) changed.

        Make sure that the displayed rows with a default height are updated in height and top position.

        Note:This implementation should not call Escalator.recalculateElementSizes() - it is done by the discretion of the caller of this method.

      • reapplyRowHeight

        protected void reapplyRowHeight​(com.google.gwt.dom.client.TableRowElement tr,
                                double heightPx)
        Updates the cells within the row to the given height.
        Parameters:
        tr - the row to update
        heightPx - the height to set, in pixels

      • setRowPosition

        protected void setRowPosition​(com.google.gwt.dom.client.TableRowElement tr,
                              int x,
                              double y)
        Updates the position of the given row to the given coordinates.
        Parameters:
        tr - the row to update
        x - the x coordinate, in pixels
        y - the y coordinate, in pixels

      • getRowTop

        protected double getRowTop​(com.google.gwt.dom.client.TableRowElement tr)
        Returns the assigned top position for the given element.

        Note: This method does not calculate what a row's top position should be. It just returns an assigned value, correct or not.

        Parameters:
        tr - the table row element to measure
        Returns:
        the current top position for tr
        See Also:
        Escalator.BodyRowContainerImpl.getRowTop(int)

      • removeRowPosition

        protected void removeRowPosition​(com.google.gwt.dom.client.TableRowElement tr)
        Removes the given row from the position bookkeeping.
        Parameters:
        tr - the row to remove

      • autodetectRowHeightLater

        public void autodetectRowHeightLater()
        Triggers delayed auto-detection of default row height if it hasn't been set by that point and the Escalator is both attached and displayed.

      • isAutodetectingRowHeightLater

        public boolean isAutodetectingRowHeightLater()
        Description copied from interface: RowContainer
        For internal use only. May be removed or replaced in the future.
        Specified by:
        isAutodetectingRowHeightLater in interface RowContainer
        Returns:
        true if row height calculations have been scheduled

      • autodetectRowHeightNow

        public void autodetectRowHeightNow()
        Auto-detect row height immediately, if possible. If Escalator isn't attached and displayed yet, auto-detecting cannot be performed correctly. In such cases auto-detecting is left to wait for these conditions to change, and will be performed when they do.

      • getCell

        public Cell getCell​(com.google.gwt.dom.client.Element element)
        Description copied from interface: RowContainer
        Returns the cell object which contains information about the cell the element is in.
        Specified by:
        getCell in interface RowContainer
        Parameters:
        element - The element to get the cell for. If element is not present in row container then null is returned.
        Returns:
        the cell of the element, or null if element is not present in the RowContainer.

      • getHeightOfSection

        protected abstract double getHeightOfSection()
        The height of this table section.

        Note that the body will calculate its height, while the others will return a precomputed value.

        Returns:
        the height of this table section
        Since:
        7.5.0

      • getLogicalRowIndex

        public int getLogicalRowIndex​(com.google.gwt.dom.client.TableRowElement tr)
        Gets the logical row index for the given table row element.
        Parameters:
        tr - the table row element inside this container.
        Returns:
        the logical index of the given element