com.vaadin.client.widgets
Class Escalator

java.lang.Object
  Widget
      com.vaadin.client.widgets.Escalator

All Implemented Interfaces:

DeferredWorker, SubPartAware

public class Escalator
extends Widget
implements DeferredWorker, SubPartAware

A low-level table-like widget that features a scrolling virtual viewport and lazily generated rows.

Since:

7.4

Author:

Vaadin Ltd

Nested Class Summary

protected class	Escalator.AbstractRowContainer
static class	Escalator.SubPartArguments Utility class for parsing and storing SubPart request string attributes for Grid and Escalator.

Constructor Summary

Escalator()
Creates a new Escalator widget instance.

Method Summary

com.google.gwt.event.shared.HandlerRegistration	addRowVisibilityChangeHandler(RowVisibilityChangeHandler rowVisibilityChangeHandler) Adds an event handler that gets notified when the range of visible rows changes e.g.
com.google.gwt.event.shared.HandlerRegistration	addScrollHandler(ScrollHandler handler) Adds a scroll handler to this escalator
RowContainer	findRowContainer(Element element) Returns the Escalator.AbstractRowContainer which contains the element.
RowContainer.BodyRowContainer	getBody() Returns the row container for the body in this Escalator.
ColumnConfiguration	getColumnConfiguration() Returns the configuration object for the columns in this Escalator.
RowContainer	getFooter() Returns the row container for the footer in this Escalator.
RowContainer	getHeader() Returns the row container for the header in this Escalator.
double	getHeightByRows() Gets the amount of rows in Escalator's body that are shown, while getHeightMode() is HeightMode.ROW.
com.vaadin.shared.ui.grid.HeightMode	getHeightMode() Returns the current HeightMode the Escalator is in.
double	getInnerWidth() Gets the escalator's inner width.
int	getMaxVisibleRowCount() Gets the maximum number of body rows that can be visible on the screen at once.
double	getScrollHeight() Returns the scroll height for the escalator.
double	getScrollLeft() Returns the logical horizontal scroll offset.
double	getScrollTop() Returns the vertical scroll offset.
double	getScrollWidth() Returns the scroll width for the escalator.
com.google.gwt.user.client.Element	getSubPartElement(java.lang.String subPart) Locates an element inside a component using the identifier provided in subPart.
java.lang.String	getSubPartName(com.google.gwt.user.client.Element subElement) Provides an identifier that identifies the element within the component.
com.vaadin.shared.ui.grid.Range	getVisibleRowRange() Gets the logical index range of currently visible rows.
boolean	isScrollLocked(ScrollbarBundle.Direction direction) Checks whether or not an direction is locked for scrolling.
boolean	isWorkPending() Checks whether there are operations pending for this widget or connector that must be executed before reaching a steady state.
protected void	onLoad()
void	onResize()
protected void	onUnload()
void	resetSizesFromDom() Resets all cached pixel sizes and reads new values from the DOM.
void	scrollToColumn(int columnIndex, com.vaadin.shared.ui.grid.ScrollDestination destination, int padding) Scrolls the body horizontally so that the column at the given index is visible and there is at least padding pixels in the direction of the given scroll destination.
void	scrollToRow(int rowIndex, com.vaadin.shared.ui.grid.ScrollDestination destination, int padding) Scrolls the body vertically so that the row at the given index is visible and there is at least padding pixels to the given scroll destination.
void	scrollToRowAndSpacer(int rowIndex, com.vaadin.shared.ui.grid.ScrollDestination destination, int padding) Scrolls vertically to a row and the spacer below it.
void	scrollToSpacer(int spacerIndex, com.vaadin.shared.ui.grid.ScrollDestination destination, int padding) Scrolls the body vertically so that the spacer at the given row index is visible and there is at least padding pixesl to the given scroll destination.
void	setHeight(java.lang.String height)
void	setHeightByRows(double rows) Sets the number of rows that should be visible in Escalator's body, while getHeightMode() is HeightMode.ROW.
void	setHeightMode(com.vaadin.shared.ui.grid.HeightMode heightMode) Defines the mode in which the Escalator widget's height is calculated.
void	setScrollLeft(double scrollLeft) Sets the logical horizontal scroll offset.
void	setScrollLocked(ScrollbarBundle.Direction direction, boolean locked) Sets whether a scroll direction is locked or not.
void	setScrollTop(double scrollTop) Sets the vertical scroll offset.
void	setStylePrimaryName(java.lang.String style)
void	setWidth(java.lang.String width)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Escalator

public Escalator()

Creates a new Escalator widget instance.

Method Detail

onLoad

protected void onLoad()

onUnload

protected void onUnload()

getHeader

public RowContainer getHeader()

Returns the row container for the header in this Escalator.

Returns:

the header. Never null

getBody

public RowContainer.BodyRowContainer getBody()

Returns the row container for the body in this Escalator.

Returns:

the body. Never null

getFooter

public RowContainer getFooter()

Returns the row container for the footer in this Escalator.

Returns:

the footer. Never null

getColumnConfiguration

public ColumnConfiguration getColumnConfiguration()

Returns the configuration object for the columns in this Escalator.

Returns:

the configuration object for the columns in this Escalator. Never null

setWidth

public void setWidth(java.lang.String width)

setHeight

public void setHeight(java.lang.String height)

If Escalator is currently not in HeightMode.CSS, the given value is remembered, and applied once the mode is applied.

See Also:

setHeightMode(HeightMode)

getScrollTop

public double getScrollTop()

Returns the vertical scroll offset. Note that this is not necessarily the same as the scrollTop attribute in the DOM.

Returns:

the logical vertical scroll offset

setScrollTop

public void setScrollTop(double scrollTop)

Sets the vertical scroll offset. Note that this will not necessarily become the same as the scrollTop attribute in the DOM.

Parameters:

scrollTop - the number of pixels to scroll vertically

getScrollLeft

public double getScrollLeft()

Returns the logical horizontal scroll offset. Note that this is not necessarily the same as the scrollLeft attribute in the DOM.

Returns:

the logical horizontal scroll offset

setScrollLeft

public void setScrollLeft(double scrollLeft)

Sets the logical horizontal scroll offset. Note that will not necessarily become the same as the scrollLeft attribute in the DOM.

Parameters:

scrollLeft - the number of pixels to scroll horizontally

getScrollWidth

public double getScrollWidth()

Returns the scroll width for the escalator. Note that this is not necessary the same as Element.scrollWidth in the DOM.

Returns:

the scroll width in pixels

Since:

7.5.0

getScrollHeight

public double getScrollHeight()

Returns the scroll height for the escalator. Note that this is not necessary the same as Element.scrollHeight in the DOM.

Returns:

the scroll height in pixels

Since:

7.5.0

scrollToColumn

public void scrollToColumn(int columnIndex,
                           com.vaadin.shared.ui.grid.ScrollDestination destination,
                           int padding)
                    throws java.lang.IndexOutOfBoundsException,
                           java.lang.IllegalArgumentException

Scrolls the body horizontally so that the column at the given index is visible and there is at least padding pixels in the direction of the given scroll destination.

Parameters:

columnIndex - the index of the column to scroll to

destination - where the column should be aligned visually after scrolling

padding - the number pixels to place between the scrolled-to column and the viewport edge.

Throws:

java.lang.IndexOutOfBoundsException - if columnIndex is not a valid index for an existing column

java.lang.IllegalArgumentException - if destination is ScrollDestination.MIDDLE and padding is nonzero; or if the indicated column is frozen; or if destination == null

scrollToRow

public void scrollToRow(int rowIndex,
                        com.vaadin.shared.ui.grid.ScrollDestination destination,
                        int padding)
                 throws java.lang.IndexOutOfBoundsException,
                        java.lang.IllegalArgumentException

Scrolls the body vertically so that the row at the given index is visible and there is at least padding pixels to the given scroll destination.

Parameters:

rowIndex - the index of the logical row to scroll to

destination - where the row should be aligned visually after scrolling

padding - the number pixels to place between the scrolled-to row and the viewport edge.

Throws:

java.lang.IndexOutOfBoundsException - if rowIndex is not a valid index for an existing row

java.lang.IllegalArgumentException - if destination is ScrollDestination.MIDDLE and padding is nonzero; or if destination == null

See Also:

scrollToRowAndSpacer(int, ScrollDestination, int), scrollToSpacer(int, ScrollDestination, int)

scrollToSpacer

public void scrollToSpacer(int spacerIndex,
                           com.vaadin.shared.ui.grid.ScrollDestination destination,
                           int padding)
                    throws java.lang.IllegalArgumentException

Scrolls the body vertically so that the spacer at the given row index is visible and there is at least padding pixesl to the given scroll destination.

Parameters:

spacerIndex - the row index of the spacer to scroll to

destination - where the spacer should be aligned visually after scrolling

padding - the number of pixels to place between the scrolled-to spacer and the viewport edge

Throws:

java.lang.IllegalArgumentException - if spacerIndex is not an opened spacer; or if destination is ScrollDestination.MIDDLE and padding is nonzero; or if destination == null

Since:

7.5.0

See Also:

scrollToRow(int, ScrollDestination, int), scrollToRowAndSpacer(int, ScrollDestination, int)

scrollToRowAndSpacer

public void scrollToRowAndSpacer(int rowIndex,
                                 com.vaadin.shared.ui.grid.ScrollDestination destination,
                                 int padding)
                          throws java.lang.IllegalArgumentException

Scrolls vertically to a row and the spacer below it.

If a spacer is not open at that index, this method behaves like scrollToRow(int, ScrollDestination, int)

Parameters:

rowIndex - the index of the logical row to scroll to. -1 takes the topmost spacer into account as well.

destination - where the row should be aligned visually after scrolling

padding - the number pixels to place between the scrolled-to row and the viewport edge.

Throws:

java.lang.IllegalArgumentException - if destination is ScrollDestination.MIDDLE and padding is not zero; or if rowIndex is not a valid row index, or -1; or if destination == null; or if rowIndex == -1 and there is no spacer open at that index.

Since:

7.5.0

See Also:

scrollToRow(int, ScrollDestination, int), scrollToSpacer(int, ScrollDestination, int)

addRowVisibilityChangeHandler

public com.google.gwt.event.shared.HandlerRegistration addRowVisibilityChangeHandler(RowVisibilityChangeHandler rowVisibilityChangeHandler)

Adds an event handler that gets notified when the range of visible rows changes e.g. because of scrolling, row resizing or spacers appearing/disappearing.

Parameters:

rowVisibilityChangeHandler - the event handler

Returns:

a handler registration for the added handler

getVisibleRowRange

public com.vaadin.shared.ui.grid.Range getVisibleRowRange()

Gets the logical index range of currently visible rows.

Returns:

logical index range of visible rows

setStylePrimaryName

public void setStylePrimaryName(java.lang.String style)

setHeightByRows

public void setHeightByRows(double rows)
                     throws java.lang.IllegalArgumentException

Sets the number of rows that should be visible in Escalator's body, while getHeightMode() is HeightMode.ROW.

If Escalator is currently not in HeightMode.ROW, the given value is remembered, and applied once the mode is applied.

Parameters:

rows - the number of rows that should be visible in Escalator's body

Throws:

java.lang.IllegalArgumentException - if rows is ≤ 0, infinite or NaN.

See Also:

setHeightMode(HeightMode)

getHeightByRows

public double getHeightByRows()

Gets the amount of rows in Escalator's body that are shown, while getHeightMode() is HeightMode.ROW.

By default, it is 10.

Returns:

the amount of rows that are being shown in Escalator's body

See Also:

setHeightByRows(double)

setHeightMode

public void setHeightMode(com.vaadin.shared.ui.grid.HeightMode heightMode)

Defines the mode in which the Escalator widget's height is calculated.

If HeightMode.CSS is given, Escalator will respect the values given via setHeight(String), and behave as a traditional Widget.

If HeightMode.ROW is given, Escalator will make sure that the body will display as many rows as getHeightByRows() defines. Note: If headers/footers are inserted or removed, the widget will resize itself to still display the required amount of rows in its body. It also takes the horizontal scrollbar into account.

Parameters:

heightMode - the mode in to which Escalator should be set

getHeightMode

public com.vaadin.shared.ui.grid.HeightMode getHeightMode()

Returns the current HeightMode the Escalator is in.

Defaults to HeightMode.CSS.

Returns:

the current HeightMode

findRowContainer

public RowContainer findRowContainer(Element element)

Returns the Escalator.AbstractRowContainer which contains the element.

Parameters:

element - the element to check for

Returns:

the container the element is in or null if element is not present in any container.

setScrollLocked

public void setScrollLocked(ScrollbarBundle.Direction direction,
                            boolean locked)

Sets whether a scroll direction is locked or not.

If a direction is locked, the escalator will refuse to scroll in that direction.

Parameters:

direction - the orientation of the scroll to set the lock status

locked - true to lock, false to unlock

isScrollLocked

public boolean isScrollLocked(ScrollbarBundle.Direction direction)

Checks whether or not an direction is locked for scrolling.

Parameters:

direction - the direction of the scroll of which to check the lock status

Returns:

true iff the direction is locked

addScrollHandler

public com.google.gwt.event.shared.HandlerRegistration addScrollHandler(ScrollHandler handler)

Adds a scroll handler to this escalator

Parameters:

handler - the scroll handler to add

Returns:

a handler registration for the registered scroll handler

isWorkPending

public boolean isWorkPending()

Description copied from interface: DeferredWorker

Checks whether there are operations pending for this widget or connector that must be executed before reaching a steady state.

Specified by:

isWorkPending in interface DeferredWorker

onResize

public void onResize()

getMaxVisibleRowCount

public int getMaxVisibleRowCount()

Gets the maximum number of body rows that can be visible on the screen at once.

Returns:

the maximum capacity

getInnerWidth

public double getInnerWidth()

Gets the escalator's inner width. This is the entire width in pixels, without the vertical scrollbar.

Returns:

escalator's inner width

resetSizesFromDom

public void resetSizesFromDom()

Resets all cached pixel sizes and reads new values from the DOM. This methods should be used e.g. when styles affecting the dimensions of elements in this escalator have been changed.

getSubPartElement

public com.google.gwt.user.client.Element getSubPartElement(java.lang.String subPart)

Description copied from interface: SubPartAware

Locates an element inside a component using the identifier provided in subPart. The subPart identifier is component specific and may be any string of characters, numbers, space characters and brackets.

Specified by:

getSubPartElement in interface SubPartAware

Parameters:

subPart - The identifier for the element inside the component

Returns:

The element identified by subPart or null if the element could not be found.

getSubPartName

public java.lang.String getSubPartName(com.google.gwt.user.client.Element subElement)

Description copied from interface: SubPartAware

Provides an identifier that identifies the element within the component. The subElement is a part of the component and must never be null.

Note! getSubPartElement(getSubPartName(element)) == element is not always true. A component can choose to provide a more generic identifier for any given element if the results of all interactions with subElement are the same as interactions with the element identified by the return value. For example a button can return an identifier for the root element even though a DIV inside the button was passed as subElement because interactions with the DIV and the root button element produce the same result.

Specified by:

getSubPartName in interface SubPartAware

Parameters:

subElement - The element the identifier string should uniquely identify

Returns:

An identifier that uniquely identifies subElement or null if no identifier could be provided.