Class WTableView


public class WTableView
extends WAbstractItemView
An MVC View widget for tabular data.

The view displays data from a WAbstractItemModel in a table. It provides incremental rendering, without excessive use of client- or serverside resources.

The rendering (and editing) of items is handled by a WAbstractItemDelegate, by default it uses WItemDelegate which renders data of all predefined roles (see also ItemDataRole), including text, icons, checkboxes, and tooltips.

The view provides virtual scrolling in both horizontal and vertical directions, and can therefore be used to display large data models (with large number of columns and rows).

When the view is updated, it will read the data from the model row per row, starting at the top visible row. If (r1,c1) and (r2,c2) are two model indexes of visible table cells, and r1 < r2 or r1 == r2 and c1 < c2, then the data for the first model index is read before the second. Keep this into account when implementing a custom WAbstractItemModel if you want to optimize performance.

The view may support editing of items, if the model indicates support (see the ItemFlag.Editable flag). You can define triggers that initiate editing of an item using WAbstractItemView#setEditTriggers(). The actual editing is provided by the item delegate (you can set an appropriate delegate for one column using WAbstractItemView#setItemDelegateForColumn()). Using WAbstractItemView#setEditOptions() you can customize if and how the view deals with multiple editors.

By default, all columns are given a width of 150px. Column widths of all columns can be set through the API method setColumnWidth(), and also by the user using handles provided in the header.

If the model supports sorting (WAbstractItemModel#sort()), such as the WStandardItemModel, then you can enable sorting buttons in the header, using WAbstractItemView#setSortingEnabled().

You can allow selection on row or item level (using WAbstractItemView#setSelectionBehavior()), and selection of single or multiple items (using WAbstractItemView#setSelectionMode()), and listen for changes in the selection using the WAbstractItemView.selectionChanged() signal.

You may enable drag & drop support for this view, with awareness of the items in the model. When enabling dragging (see WAbstractItemView#setDragEnabled()), the current selection may be dragged, but only when all items in the selection indicate support for dragging (controlled by the ItemFlag.DragEnabled flag), and if the model indicates a mime-type (controlled by WAbstractItemModel.getMimeType()). Likewise, by enabling support for dropping (see WAbstractItemView#setDropsEnabled()), the view may receive a drop event on a particular item, at least if the item indicates support for drops (controlled by the ItemFlag.DropEnabled flag).

You may also react to mouse click events on any item, by connecting to one of the WAbstractItemView.clicked() or WAbstractItemView.doubleClicked() signals.

If a WTableView is not constrained in height (either by a layout manager or by WWidget#setHeight()), then it will grow according to the size of the model.

  • Constructor Details

  • Method Details

    • remove

      public void remove()
      Description copied from class: WWidget
      Destructor.

      Deletes a widget and all contained contents.

      Overrides:
      remove in class WAbstractItemView
      See Also:
      WWidget.removeWidget(WWidget widget)
    • itemWidget

      public WWidget itemWidget​(WModelIndex index)
      Description copied from class: WAbstractItemView
      Returns the widget that renders an item.

      This returns the widget that renders the given item. This may return 0 if the item is currently not rendered.

      This widget has been created by an item delegate, and usually an item delegate is involved when updating it.

      Specified by:
      itemWidget in class WAbstractItemView
    • setModel

      public void setModel​(WAbstractItemModel model)
      Description copied from class: WAbstractItemView
      Sets the model.

      The View will display data of the given model and changes in the model are reflected by the View.

      The initial model is null.

      Overrides:
      setModel in class WAbstractItemView
      See Also:
      WAbstractItemView.setRootIndex(WModelIndex rootIndex)
    • setColumnWidth

      public void setColumnWidth​(int column, WLength width)
      Description copied from class: WAbstractItemView
      Sets the column width.

      The default column width is 150 pixels.

      Note: The width must be specified in LengthUnit.Pixel units.

      Note: The actual space occupied by each column is the column width augmented by 7 pixels for internal padding and a border.

      Specified by:
      setColumnWidth in class WAbstractItemView
    • setAlternatingRowColors

      public void setAlternatingRowColors​(boolean enable)
      Description copied from class: WAbstractItemView
      Sets if alternating row colors are to be used.

      Configure whether rows get alternating background colors, defined by the current CSS theme.

      The default value is false.

      Overrides:
      setAlternatingRowColors in class WAbstractItemView
    • setRowHeight

      public void setRowHeight​(WLength rowHeight)
      Description copied from class: WAbstractItemView
      Sets the row height.

      The view renders all rows with a same height. This method configures this row height.

      The default value is 20 pixels.

      Note: The height must be specified in LengthUnit.Pixel units.

      Overrides:
      setRowHeight in class WAbstractItemView
      See Also:
      WAbstractItemView.setColumnWidth(int column, WLength width)
    • setHeaderHeight

      public void setHeaderHeight​(WLength height)
      Description copied from class: WAbstractItemView
      Sets the header height.

      The default value is 20 pixels.

      Note: The height must be specified in LengthUnit.Pixel units.

      Overrides:
      setHeaderHeight in class WAbstractItemView
    • resize

      public void resize​(WLength width, WLength height)
      Description copied from class: WWidget
      Resizes the widget.

      Specifies a fixed size for this widget, setting CSS width and height properties. By default a widget has automatic width and height, which sets a size for the widget following CSS rules.

      When the widget is not managed by a layout manager, the automatic (natural) size of a widget depends on whether they widget is a block or inline widget:

      • a block widget takes by default the width of the parent, and the height that it needs based on its contents
      • an inline widget takes the width and height that it needs based on its contents (possibly wrapping over multiple lines). The width and height of an inline widget cannot be changed (by the letter of CSS, although most browsers will react to it in varying ways).

      When inserted in a layout manager, the size set will be used as a widget's preferred size, but the widget may be given a different size by the layout manager based on available space and stretch factors. The actual size given by a layout manager may be retrieved by making the widget "layout size aware", using setLayoutSizeAware(). If you have defined a "wtResize()" JavaScript method for the widget, then this method will also be called.

      The default width and height of a widget is WLength.Auto.

      Overrides:
      resize in class WCompositeWidget
      See Also:
      WWidget.getWidth(), WWidget.getHeight()
    • setColumnHidden

      public void setColumnHidden​(int column, boolean hidden)
      Description copied from class: WAbstractItemView
      Changes the visibility of a column.

      Overrides:
      setColumnHidden in class WAbstractItemView
      See Also:
      WAbstractItemView.isColumnHidden(int column)
    • setRowHeaderCount

      public void setRowHeaderCount​(int count)
      Description copied from class: WAbstractItemView
      Configures the number of columns that are used as row headers.

      An item view does not use the vertical header data from the model in any way, but instead you can configure data in the first column(s) to be used as a row headers.

      These columns will not scroll horizontally together with the rest of the model.

      The default value is 0.

      Note: Currently, this property must be set before any other settings of the view and only a value of 0 or 1 is supported.

      Overrides:
      setRowHeaderCount in class WAbstractItemView
    • getPageCount

      public int getPageCount()
      Description copied from class: WAbstractItemView
      Returns the number of pages.

      When Ajax/JavaScript is not available, the view will use a paging navigation bar to allow scrolling through the data. This returns the number of pages currently shown.

      Specified by:
      getPageCount in class WAbstractItemView
      See Also:
      WAbstractItemView.getCreatePageNavigationBar(), WAbstractItemView.pageChanged()
    • getPageSize

      public int getPageSize()
      Description copied from class: WAbstractItemView
      Returns the page size.

      When Ajax/JavaScript is not available, the view will use a paging navigation bar to allow scrolling through the data. This returns the number of items per page.

      Specified by:
      getPageSize in class WAbstractItemView
      See Also:
      WAbstractItemView.getCreatePageNavigationBar(), WAbstractItemView.pageChanged()
    • getCurrentPage

      public int getCurrentPage()
      Description copied from class: WAbstractItemView
      Returns the current page.

      When Ajax/JavaScript is not available, the view will use a paging navigation bar to allow scrolling through the data. This returns the current page (between 0 and getPageCount() - 1).

      Specified by:
      getCurrentPage in class WAbstractItemView
      See Also:
      WAbstractItemView.getCreatePageNavigationBar(), WAbstractItemView.pageChanged()
    • setCurrentPage

      public void setCurrentPage​(int page)
      Description copied from class: WAbstractItemView
      Sets the current page.

      When Ajax/JavaScript is not available, the view will use a paging navigation bar to allow scrolling through the data. This method can be used to change the current page.

      Specified by:
      setCurrentPage in class WAbstractItemView
      See Also:
      WAbstractItemView.getCreatePageNavigationBar(), WAbstractItemView.pageChanged()
    • scrollTo

      public void scrollTo​(WModelIndex index, ScrollHint hint)
      Description copied from class: WAbstractItemView
      Scrolls the view to an item.

      Scrolls the view to ensure that the item which represents the provided index is visible. A hint may indicate how the item should appear in the viewport (if possible).

      Note: Currently only implemented to scroll to the correct row, not taking into account the column.

      Specified by:
      scrollTo in class WAbstractItemView
    • scrollTo

      public void scrollTo​(int x, int y)
      Scrolls the view x px left and y px top.
    • setOverflow

      public void setOverflow​(Overflow overflow, java.util.EnumSet<Orientation> orientation)
      set css overflow
    • setOverflow

      public final void setOverflow​(Overflow overflow, Orientation orientatio, Orientation... orientation)
    • setOverflow

      public final void setOverflow​(Overflow overflow)
    • setPreloadMargin

      public void setPreloadMargin​(WLength margin, java.util.EnumSet<Side> side)
      Sets preloading margin.

      By default the table view loads in an area equal to 3 times its height and 3 times its width. This makes it so that the user can scroll a full page in each direction without the delay caused when the table view dynamically needs to load more data.

      setPreloadMargin() allows to customize this margin.

      e.g. if the table view is H pixels high, and C is the preload margin in pixels set on the top and bottom, then enough rows are loaded to fill the area that is H + 2C pixels high. H pixels visible, C pixels above, and C pixels below.

      Set to 0 pixels if you don't want to load more rows or columns than are currently visible.

      Set to a default-constructed WLength (auto) if you want to keep default behaviour.

    • setPreloadMargin

      public final void setPreloadMargin​(WLength margin, Side sid, Side... side)
    • setPreloadMargin

      public final void setPreloadMargin​(WLength margin)
      Sets preloading margin.

      Calls setPreloadMargin(margin, Side.AllSides)

    • getPreloadMargin

      public WLength getPreloadMargin​(Side side)
      Retrieves the preloading margin.

      See Also:
      setPreloadMargin(WLength margin, EnumSet side)
    • setHidden

      public void setHidden​(boolean hidden, WAnimation animation)
      Description copied from class: WWidget
      Hides or shows the widget.

      Hides or show the widget (including all its descendant widgets). When setting hidden = false, this widget and all descendant widgets that are not hidden will be shown. A widget is only visible if it and all its ancestors in the widget tree are visible, which may be checked using isVisible().

      Overrides:
      setHidden in class WCompositeWidget
    • getModelIndexAt

      public WModelIndex getModelIndexAt​(WWidget widget)
      Returns the model index corresponding to a widget.

      This returns the model index for the item that is or contains the given widget.

    • scrolled

      public EventSignal1<WScrollEvent> scrolled()
      Description copied from class: WAbstractItemView
      Signal emitted when scrolling.

      Note: Works only if ajax is available.

      Specified by:
      scrolled in class WAbstractItemView
    • render

      protected void render​(java.util.EnumSet<RenderFlag> flags)
      Description copied from class: WWidget
      Renders the widget.

      This function renders the widget (or an update for the widget), after this has been scheduled using scheduleRender().

      The default implementation will render the widget by serializing changes to JavaScript and HTML. You may want to reimplement this widget if you have been postponing some of the layout / rendering implementation until the latest moment possible. In that case you should make sure you call the base implementation however.

      Overrides:
      render in class WCompositeWidget
    • adjustSize

      protected void adjustSize()
      Called when rows or columns are inserted/removed.

      Override this method when you want to adjust the table's size when columns or rows are inserted or removed. The method is also called when the model is reset. The default implementation does nothing.

    • enableAjax

      protected void enableAjax()
      Description copied from class: WWidget
      Progresses to an Ajax-enabled widget.

      This method is called when the progressive bootstrap method is used, and support for AJAX has been detected. The default behavior will upgrade the widget's event handling to use AJAX instead of full page reloads, and propagate the call to its children.

      You may want to reimplement this method if you want to make changes to widget when AJAX is enabled. You should always call the base implementation.

      Overrides:
      enableAjax in class WAbstractItemView
      See Also:
      WApplication.enableAjax()