com.holonplatform.vaadin.components

## Interface ItemListing<T,P>

- Type Parameters:
    `T` - Item data type
    `P` - Item property type
  All Superinterfaces:
    com.vaadin.server.ClientConnector, com.vaadin.ui.Component, com.vaadin.shared.Connector, ItemSet, Selectable<T>, Serializable, com.vaadin.server.Sizeable
  All Known Subinterfaces:
    BeanListing<T>, PropertyListing

      public interface ItemListing<T,P>
      extends ItemSet, Selectable<T>, com.vaadin.ui.Component

  A component to display a set of items as tabular data, using item properties as column ids.
  Since:
    5.0.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `ItemListing.CellStyleGenerator<T,P>` Generator to provide the style names for a cell.
    `static class` | `ItemListing.ColumnAlignment` Enumeration of column content alignment options
    `static interface` | `ItemListing.ItemClickListener<T,P>` Listener for user click events on an item (a listing row).
    `static interface` | `ItemListing.ItemDetailsGenerator<T>` Generator for item (row) details components.
    `static class` | `ItemListing.NotBufferedException` Exception thrown when a listing operation is invoked and it is valid only in buffered mode.
    `static interface` | `ItemListing.PropertyReorderListener<P>` Listener for column reordering events.
    `static interface` | `ItemListing.PropertyResizeListener<P>` Listener for column resizing events.
    `static interface` | `ItemListing.PropertyVisibilityListener<P>` Listener for column visibility change events.
    `static interface` | `ItemListing.RowStyleGenerator<T>` Generator to provide the style names for an item row.

    - ### Nested classes/interfaces inherited from interface com.holonplatform.vaadin.components.ItemSet

      `ItemSet.ItemCaptionGenerator<ITEM>, ItemSet.ItemDescriptionGenerator<ITEM>, ItemSet.ItemIconGenerator<ITEM>`

    - ### Nested classes/interfaces inherited from interface com.holonplatform.vaadin.components.Selectable

      `Selectable.SelectionEvent<T>, Selectable.SelectionListener<T>, Selectable.SelectionMode`

    - ### Nested classes/interfaces inherited from interface com.vaadin.ui.Component

      `com.vaadin.ui.Component.ErrorEvent, com.vaadin.ui.Component.Event, com.vaadin.ui.Component.Focusable, com.vaadin.ui.Component.Listener`

    - ### Nested classes/interfaces inherited from interface com.vaadin.server.ClientConnector

      `com.vaadin.server.ClientConnector.AttachEvent, com.vaadin.server.ClientConnector.AttachListener, com.vaadin.server.ClientConnector.ConnectorErrorEvent, com.vaadin.server.ClientConnector.DetachEvent, com.vaadin.server.ClientConnector.DetachListener`

    - ### Nested classes/interfaces inherited from interface com.vaadin.server.Sizeable

      `com.vaadin.server.Sizeable.Unit`

  - ### Field Summary

    - ### Fields inherited from interface com.vaadin.server.Sizeable

      `SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `addItem(T item)` Adds an item to the data source.
    `void` | `cancelEditing()` If the listing `isEditable()` adn the item editor is open, closes the editor discarding any unsaved changes.
    `void` | `clear()` When in buffered mode, clear the buffered items in the internal cache.
    `void` | `commit()` Updates all changes since the previous commit.
    `void` | `discard()` Discards all changes since last commit.
    `void` | `editRow(int rowNumber)` Opens the editor interface for the provided row.
    `Optional<T>` | `getItem(Object itemId)` Get the item identified by given `itemId`.
    `List<P>` | `getPropertyColumns()` Gets the current displayed item properties as listing columns
    `boolean` | `isBuffered()` Get whether the listing is in buffered mode, i.e. an internal item cache is used.
    `boolean` | `isDeselectAllowed()` Gets whether it's allowed to deselect the selected row through the UI.
    `boolean` | `isEditable()` Get whether the listing is editable by the user.
    `boolean` | `isFooterVisible()` Returns whether the listing footer is visible.
    `boolean` | `isItemDetailsVisible(T item)` Gets whether the row details component for given `item` is visible.
    `void` | `refreshItem(T item)` Refresh given item in data source
    `boolean` | `removeItem(T item)` Removes given item from the data source.
    `void` | `scrollToEnd()` Scrolls to the end of the last data row.
    `void` | `scrollToIndex(int index)` Scrolls listing viewport to show the item at given index, if present.
    `void` | `scrollToItem(T item)` Scrolls listing viewport to show the given item, if present.
    `void` | `scrollToTop()` Scrolls listing rows to top (i.e. to the first row, if any)
    `void` | `selectAll()` Select all available items.
    `void` | `setDeselectAllowed(boolean deselectAllowed)` Sets whether it's allowed to deselect the selected row through the UI.
    `void` | `setEditable(boolean editable)` Set whether the listing is editable by the user.
    `void` | `setFooterVisible(boolean visible)` Sets whether the listing footer is visible.
    `void` | `setItemDetailsVisible(T item, boolean visible)` Set whether to show the row details component for given `item`.
    `void` | `setPropertyColumnVisible(P property, boolean visible)` Show or hide the column bound to given `property`.
    `void` | `setSelectionMode(Selectable.SelectionMode selectionMode)` Set the listing selection mode
    `void` | `sort(ItemDataSource.ItemSort<P>... sorts)` Sort the listing using given `ItemDataSource.ItemSort` directives.

    - ### Methods inherited from interface com.holonplatform.vaadin.components.ItemSet

      `refresh`

    - ### Methods inherited from interface com.holonplatform.vaadin.components.Selectable

      `addSelectionListener, deselect, deselectAll, getFirstSelectedItem, getSelectedItems, getSelectionMode, isSelected, select`

    - ### Methods inherited from interface com.vaadin.ui.Component

      `addListener, addStyleName, addStyleNames, attach, getCaption, getDescription, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getUI, isEnabled, isVisible, readDesign, removeListener, removeStyleName, removeStyleNames, setCaption, setEnabled, setIcon, setId, setParent, setPrimaryStyleName, setStyleName, setStyleName, setVisible, writeDesign`

    - ### Methods inherited from interface com.vaadin.server.ClientConnector

      `addAttachListener, addDetachListener, beforeClientResponse, detach, encodeState, getErrorHandler, getExtensions, getRpcManager, getStateType, handleConnectorRequest, isAttached, isConnectorEnabled, markAsDirty, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler`

    - ### Methods inherited from interface com.vaadin.shared.Connector

      `getConnectorId`

    - ### Methods inherited from interface com.vaadin.server.Sizeable

      `getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setHeightUndefined, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthUndefined`

- - ### Method Detail

    - #### getPropertyColumns

          List<P> getPropertyColumns()

      Gets the current displayed item properties as listing columns
      Returns:
        Property columns list, in the order they are displayed

    - #### setPropertyColumnVisible

          void setPropertyColumnVisible(P property,
                                        boolean visible)

      Show or hide the column bound to given `property`.
      Parameters:
        `property` - Property to show or hide (not null)
        `visible` - `true` to show the column bound to given `property`, `false` to hide it
      Throws:
        `IllegalArgumentException` - If specified property is not bound to any column

    - #### isFooterVisible

          boolean isFooterVisible()

      Returns whether the listing footer is visible.
      Returns:
        `true` if footer is visible, `false` otherwise

    - #### setFooterVisible

          void setFooterVisible(boolean visible)

      Sets whether the listing footer is visible.
      Parameters:
        `visible` - `true` to set the footer visible, `false` otherwise

    - #### isItemDetailsVisible

          boolean isItemDetailsVisible(T item)

      Gets whether the row details component for given `item` is visible.
      Parameters:
        `item` - Item to check whether the row details component is visible (not null)
      Returns:
        `true` if row details component is visible for given item, `false` otherwise

    - #### setItemDetailsVisible

          void setItemDetailsVisible(T item,
                                     boolean visible)
                              throws UnsupportedOperationException

      Set whether to show the row details component for given `item`.
      Parameters:
        `item` - Item for which to show or hide the row details (not null)
        `visible` - `true` to show the row details component, `false` to hide it
      Throws:
        `UnsupportedOperationException` - If the concrete listing component does not support a row details component

    - #### scrollToItem

          void scrollToItem(T item)

      Scrolls listing viewport to show the given item, if present.

      This operation is available only in buffered mode.

      Parameters:
        `item` - Item to scroll to (not null)
      Throws:
        `ItemListing.NotBufferedException` - If the listing is not in buffered mode
      See Also:
        `isBuffered()`

    - #### scrollToIndex

          void scrollToIndex(int index)

      Scrolls listing viewport to show the item at given index, if present.
      Parameters:
        `index` - zero based index of the item to scroll to in the current viewport.

    - #### scrollToTop

          void scrollToTop()

      Scrolls listing rows to top (i.e. to the first row, if any)

    - #### scrollToEnd

          void scrollToEnd()

      Scrolls to the end of the last data row.

    - #### sort

          void sort(ItemDataSource.ItemSort<P>... sorts)

      Sort the listing using given `ItemDataSource.ItemSort` directives.
      Parameters:
        `sorts` - Item sorts to apply

    - #### clear

          void clear()

      When in buffered mode, clear the buffered items in the internal cache.

      When not in buffered mode, simply reset the selection, if the listing is slectable.

      See Also:
        `isBuffered()`

    - #### setSelectionMode

          void setSelectionMode(Selectable.SelectionMode selectionMode)

      Set the listing selection mode
      Parameters:
        `selectionMode` - The selection mode to set (not null)

    - #### selectAll

          void selectAll()

      Select all available items.

    - #### setDeselectAllowed

          void setDeselectAllowed(boolean deselectAllowed)

      Sets whether it's allowed to deselect the selected row through the UI. Deselection is allowed by default.
      Parameters:
        `deselectAllowed` - `true` if the selected row can be deselected without selecting another row instead; otherwise `false`.

    - #### isDeselectAllowed

          boolean isDeselectAllowed()

      Gets whether it's allowed to deselect the selected row through the UI.
      Returns:
        `true` if deselection is allowed; otherwise `false`

    - #### getItem

          Optional<T> getItem(Object itemId)

      Get the item identified by given `itemId`.

      This operation is available only in buffered mode.

      Parameters:
        `itemId` - Item id (not null)
      Returns:
        Optional item identified by given `itemId`, empty if not found
      Throws:
        `ItemListing.NotBufferedException` - If the listing is not in buffered mode
      See Also:
        `isBuffered()`

    - #### addItem

          Object addItem(T item)

      Adds an item to the data source.
      Parameters:
        `item` - The item to add (not null)
      Returns:
        Id of the added item

    - #### removeItem

          boolean removeItem(T item)

      Removes given item from the data source.
      Parameters:
        `item` - Item to remove (not null)
      Returns:
        `true` if the item was successfully removed from data source

    - #### refreshItem

          void refreshItem(T item)

      Refresh given item in data source
      Parameters:
        `item` - Item to refresh (not null)
      Throws:
        `UnsupportedOperationException` - If the refresh operation is not supported by concrete data store

    - #### commit

          void commit()

      Updates all changes since the previous commit.

      This operation is available only in buffered mode.

      Throws:
        `ItemListing.NotBufferedException` - If the listing is not in buffered mode
      See Also:
        `isBuffered()`

    - #### discard

          void discard()

      Discards all changes since last commit.

      This operation is available only in buffered mode.

      Throws:
        `ItemListing.NotBufferedException` - If the listing is not in buffered mode
      See Also:
        `isBuffered()`

    - #### isBuffered

          boolean isBuffered()

      Get whether the listing is in buffered mode, i.e. an internal item cache is used.
      Returns:
        whether the listing is in buffered mode

    - #### setEditable

          void setEditable(boolean editable)

      Set whether the listing is editable by the user.
      Parameters:
        `editable` - `true` to set the listing as editable, `false` otherwise

    - #### isEditable

          boolean isEditable()

      Get whether the listing is editable by the user.
      Returns:
        `true` if the listing is editable, `false` otherwise

    - #### editRow

          void editRow(int rowNumber)

      Opens the editor interface for the provided row. Scrolls the listing to bring the row to view if it is not already visible.
      Parameters:
        `rowNumber` - the row number of the edited item
      Throws:
        `IllegalStateException` - if the editor is not enabled or already editing a different item in buffered mode
        `IllegalArgumentException` - if the `rowNumber` is not in the backing data provider

    - #### cancelEditing

          void cancelEditing()

      If the listing `isEditable()` adn the item editor is open, closes the editor discarding any unsaved changes.
      Throws:
        `IllegalStateException` - If the listing is not editable

Copyright © 2019 The Holon Platform. All rights reserved.