Module VirtualizedFX
Package io.github.palexdev.virtualizedfx.grid

Class VirtualGrid<T,C extends GridCell<T>>

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.layout.Region
javafx.scene.control.Control
io.github.palexdev.virtualizedfx.grid.VirtualGrid<T,C>
Type Parameters:
T - the type of objects to represent
C - the type of GridCell to use
All Implemented Interfaces:
VirtualScrollPane.Wrappable, Styleable, EventTarget, Skinnable
Direct Known Subclasses:
PaginatedVirtualGrid
public class VirtualGrid<T,C extends GridCell<T>> extends Control implements VirtualScrollPane.Wrappable
Implementation of a virtual grid to virtualize the display of tabular data.

Extends Control, has its own skin implementation VirtualGridSkin and its own cell system, GridCell.

The data structure used by this control is a custom one that is specifically made to simplify operations on rows and columns, a dynamic 2D array. In reality such structure is backed by a 1D collection, a simple List, so operations are always linear, see Grid and ObservableGrid.

These are all the features:

- The items data structure is managed automatically, for all changes that may occur see GridChangeType

- The function used to generate cells, also called "cellFactory" can be changed anytime, even at runtime

- The control also manages the size of all the cells through the cellSizeProperty(), which is also settable via CSS

- You can programmatically set the position of the viewport through a series of public methods

- It is possible to retrieve the current shown/built cells as well as other information regarding the state of the viewport through the stateProperty()

- It is possible to observe for changes to the estimated size of the viewport through the estimatedSizeProperty()

- It is possible to programmatically tell the viewport to update its layout with requestViewportLayout()

Last but not least, a few notes about the backing data structure. As mentioned before the VirtualGrid uses a particular dynamic 2D structure which is ObservableGrid. About the performance: operations on rows are generally faster since the backing data structure is a linear 1D list; operations on columns on the other hand are quite expensive since it will almost always require a "complete" update of the viewport, to be precise, most of the cells will just need an index update, whereas just a few of them may require both an index and item update. Nonetheless, computing changes like a column addition or removal is always a quite complex and expensive operation.

  • Property Details

  • Constructor Details

    • VirtualGrid

      public VirtualGrid()

    • VirtualGrid

      public VirtualGrid(io.github.palexdev.mfxcore.collections.ObservableGrid<T> items, Function<T,C> cellFactory)

  • Method Details

    • requestViewportLayout

      public void requestViewportLayout()
      Basically a setter for needsViewportLayoutProperty().

      This sets the property to true causing the virtual grid skin to catch the change through a listener which then tells the viewport to recompute the layout.

    • onCellSizeChanged

      protected void onCellSizeChanged()
      This method is called every time the cellSizeProperty() changes, and is responsible for updating the viewport. Different implementations may take different approaches as how to update it.

    • init

      public io.github.palexdev.mfxcore.collections.ObservableGrid<T> init()
      Delegate for ObservableGrid.init()

    • init

      public io.github.palexdev.mfxcore.collections.ObservableGrid<T> init(int rows, int columns)
      Delegate for ObservableGrid.init(int, int)

    • init

      public io.github.palexdev.mfxcore.collections.ObservableGrid<T> init(int rows, int columns, T val)
      Delegate for ObservableGrid.init(int, int, Object)

    • init

      public io.github.palexdev.mfxcore.collections.ObservableGrid<T> init(int rows, int columns, BiFunction<Integer,Integer,T> valFunction)
      Delegate for ObservableGrid.init(int, int, BiFunction)

    • getRowsNum

      public int getRowsNum()
      Delegate for Grid.getRowsNum()

    • getColumnsNum

      public int getColumnsNum()
      Delegate for Grid.getColumnsNum()

    • clear

      public void clear()
      Delegate for ObservableGrid.clear()

    • totalSize

      public int totalSize()
      Delegate for Grid.totalSize()

    • size

      public Pair<Integer,Integer> size()
      Delegate for Grid.size()

    • isEmpty

      public boolean isEmpty()
      Delegate for Grid.isEmpty()

    • getEstimatedSize

      public io.github.palexdev.mfxcore.base.beans.Size getEstimatedSize()
      Gets the value of the estimatedSize property.
      Property description:
      Specifies the total virtual size of the viewport as a Size object.
      Returns:
      the value of the estimatedSize property
      See Also:

    • estimatedSizeProperty

      public ReadOnlyObjectProperty<io.github.palexdev.mfxcore.base.beans.Size> estimatedSizeProperty()
      Specifies the total virtual size of the viewport as a Size object.
      Returns:
      the estimatedSize property
      See Also:

    • getState

      public GridState<T,C> getState()
      Gets the value of the state property.
      Property description:
      Carries the GridState object which represents the current state of the viewport. This property is useful to catch any change happening in the viewport, and carries valuable information.
      Returns:
      the value of the state property
      See Also:

    • stateProperty

      public ReadOnlyObjectProperty<GridState<T,C>> stateProperty()
      Carries the GridState object which represents the current state of the viewport. This property is useful to catch any change happening in the viewport, and carries valuable information.
      Returns:
      the state property
      See Also:

    • getLastRowsRange

      public io.github.palexdev.mfxcore.base.beans.range.NumberRange<Integer> getLastRowsRange()
      Gets the value of the lastRowsRange property.
      Property description:
      Specifies the last range of displayed rows by the viewport as an IntegerRange.
      Returns:
      the value of the lastRowsRange property
      See Also:

    • lastRowsRangeProperty

      public io.github.palexdev.mfxcore.base.properties.range.IntegerRangeProperty lastRowsRangeProperty()
      Specifies the last range of displayed rows by the viewport as an IntegerRange.
      Returns:
      the lastRowsRange property
      See Also:

    • getLastColumnsRange

      public io.github.palexdev.mfxcore.base.beans.range.NumberRange<Integer> getLastColumnsRange()
      Gets the value of the lastColumnsRange property.
      Property description:
      Specifies the last range of displayed columns by the viewport as an IntegerRange.
      Returns:
      the value of the lastColumnsRange property
      See Also:

    • lastColumnsRangeProperty

      public io.github.palexdev.mfxcore.base.properties.range.IntegerRangeProperty lastColumnsRangeProperty()
      Specifies the last range of displayed columns by the viewport as an IntegerRange.
      Returns:
      the lastColumnsRange property
      See Also:

    • getIndexedCells

      public Map<Integer,C> getIndexedCells()
      Delegate for GridState.getIndexedCells().

    • scrollToFirstRow

      public void scrollToFirstRow()
      Scrolls to the first row.

    • scrollToLastRow

      public void scrollToLastRow()
      Scrolls to the last row.

    • scrollToRow

      public void scrollToRow(int index)
      Scrolls to the given row index.

    • scrollToFirstColumn

      public void scrollToFirstColumn()
      Scrolls to the first columns.

    • scrollToLastColumn

      public void scrollToLastColumn()
      Scrolls to the last column.

    • scrollToColumn

      public void scrollToColumn(int index)
      Scrolls to the given column index.

    • scrollBy

      public void scrollBy(double pixels, Orientation orientation)
      Scrolls by the given amount of pixels in the given direction.
      Parameters:
      orientation - the scroll direction

    • scrollTo

      public void scrollTo(double pixel, Orientation orientation)
      Scrolls to the given pixel value in the given direction.
      Parameters:
      orientation - the scroll direction

    • createDefaultSkin

      protected Skin<?> createDefaultSkin()
      Overrides:
      createDefaultSkin in class Control

    • getControlCssMetaData

      protected List<CssMetaData<? extends Styleable,?>> getControlCssMetaData()
      Overrides:
      getControlCssMetaData in class Control

    • wrap

      public VirtualScrollPane wrap()
      Description copied from interface: VirtualScrollPane.Wrappable
      Wraps this in a VirtualScrollPane
      Specified by:
      wrap in interface VirtualScrollPane.Wrappable

    • getCellSize

      public io.github.palexdev.mfxcore.base.beans.Size getCellSize()
      Gets the value of the cellSize property.
      Property description:
      Specifies the size of the cells as a Size.

      It is also possible to set this property via CSS with the "-fx-cell-size" property, check StyleableSizeProperty and StyleableSizeProperty.SizeConverter for more info.

      Returns:
      the value of the cellSize property
      See Also:

    • cellSizeProperty

      public io.github.palexdev.mfxcore.base.properties.styleable.StyleableSizeProperty cellSizeProperty()
      Specifies the size of the cells as a Size.

      It is also possible to set this property via CSS with the "-fx-cell-size" property, check StyleableSizeProperty and StyleableSizeProperty.SizeConverter for more info.

      Returns:
      the cellSize property
      See Also:

    • setCellSize

      public void setCellSize(io.github.palexdev.mfxcore.base.beans.Size cellSize)
      Sets the value of the cellSize property.
      Property description:
      Specifies the size of the cells as a Size.

      It is also possible to set this property via CSS with the "-fx-cell-size" property, check StyleableSizeProperty and StyleableSizeProperty.SizeConverter for more info.

      Parameters:
      cellSize - the value for the cellSize property
      See Also:

    • getClipBorderRadius

      public double getClipBorderRadius()
      Gets the value of the clipBorderRadius property.
      Property description:
      Used by the viewport's clip to set its border radius. This is useful when you want to make a rounded virtual grid, this prevents the content from going outside the view.

      This is mostly useful if not using the grid with VirtualScrollPane, this is the same as VirtualScrollPane.clipBorderRadiusProperty().

      Side note: the clip is a Rectangle, now for some fucking reason the rectangle's arcWidth and arcHeight values used to make it round do not act like the border-radius or background-radius properties, instead their value is usually 2 / 2.5 times the latter. So for a border radius of 5 you want this value to be at least 10/13.

      It is also possible to set this property via CSS with the "-fx-clip-border-radius" property.

      Returns:
      the value of the clipBorderRadius property
      See Also:

    • clipBorderRadiusProperty

      public io.github.palexdev.mfxcore.base.properties.styleable.StyleableDoubleProperty clipBorderRadiusProperty()
      Used by the viewport's clip to set its border radius. This is useful when you want to make a rounded virtual grid, this prevents the content from going outside the view.

      This is mostly useful if not using the grid with VirtualScrollPane, this is the same as VirtualScrollPane.clipBorderRadiusProperty().

      Side note: the clip is a Rectangle, now for some fucking reason the rectangle's arcWidth and arcHeight values used to make it round do not act like the border-radius or background-radius properties, instead their value is usually 2 / 2.5 times the latter. So for a border radius of 5 you want this value to be at least 10/13.

      It is also possible to set this property via CSS with the "-fx-clip-border-radius" property.

      Returns:
      the clipBorderRadius property
      See Also:

    • setClipBorderRadius

      public void setClipBorderRadius(double clipBorderRadius)
      Sets the value of the clipBorderRadius property.
      Property description:
      Used by the viewport's clip to set its border radius. This is useful when you want to make a rounded virtual grid, this prevents the content from going outside the view.

      This is mostly useful if not using the grid with VirtualScrollPane, this is the same as VirtualScrollPane.clipBorderRadiusProperty().

      Side note: the clip is a Rectangle, now for some fucking reason the rectangle's arcWidth and arcHeight values used to make it round do not act like the border-radius or background-radius properties, instead their value is usually 2 / 2.5 times the latter. So for a border radius of 5 you want this value to be at least 10/13.

      It is also possible to set this property via CSS with the "-fx-clip-border-radius" property.

      Parameters:
      clipBorderRadius - the value for the clipBorderRadius property
      See Also:

    • getClassCssMetaData

      public static List<CssMetaData<? extends Styleable,?>> getClassCssMetaData()

    • getViewportManager

      protected GridManager<T,C> getViewportManager()
      Returns:
      the GridManager instance for this VirtualGrid

    • getItems

      public io.github.palexdev.mfxcore.collections.ObservableGrid<T> getItems()
      Gets the value of the items property.
      Property description:
      Specifies the ObservableGrid used to store the items.

      This is an ObjectProperty so that it can also be bound to other properties.

      Returns:
      the value of the items property
      See Also:

    • itemsProperty

      public ObjectProperty<io.github.palexdev.mfxcore.collections.ObservableGrid<T>> itemsProperty()
      Specifies the ObservableGrid used to store the items.

      This is an ObjectProperty so that it can also be bound to other properties.

      Returns:
      the items property
      See Also:

    • setItems

      public void setItems(io.github.palexdev.mfxcore.collections.ObservableGrid<T> items)
      Sets the value of the items property.
      Property description:
      Specifies the ObservableGrid used to store the items.

      This is an ObjectProperty so that it can also be bound to other properties.

      Parameters:
      items - the value for the items property
      See Also:

    • getCellFactory

      public Function<T,C> getCellFactory()
      Gets the value of the cellFactory property.
      Property description:
      Specifies the function used to build the cells.
      Returns:
      the value of the cellFactory property
      See Also:

    • cellFactoryProperty

      public io.github.palexdev.mfxcore.base.properties.functional.FunctionProperty<T,C> cellFactoryProperty()
      Specifies the function used to build the cells.
      Returns:
      the cellFactory property
      See Also:

    • setCellFactory

      public void setCellFactory(Function<T,C> cellFactory)
      Sets the value of the cellFactory property.
      Property description:
      Specifies the function used to build the cells.
      Parameters:
      cellFactory - the value for the cellFactory property
      See Also:

    • setVPos

      public void setVPos(double vPos)
      Shortcut for setPosition(double, double), which uses the current hPos as the x value for the new Position object.

    • getVPos

      public double getVPos()
      Returns:
      the vertical position of the viewport

    • setHPos

      public void setHPos(double hPos)
      Shortcut for setPosition(double, double), which uses the current vPos as the y value for the new Position object.

    • getHPos

      public double getHPos()
      Returns:
      the horizontal position of the viewport

    • getPosition

      public io.github.palexdev.mfxcore.base.beans.Position getPosition()
      Gets the value of the position property.
      Property description:
      Specifies the current position of the viewport as a Position object which has both the x and y positions.
      Returns:
      the value of the position property
      See Also:

    • positionProperty

      public io.github.palexdev.mfxcore.base.properties.PositionProperty positionProperty()
      Specifies the current position of the viewport as a Position object which has both the x and y positions.
      Returns:
      the position property
      See Also:

    • setPosition

      public void setPosition(double x, double y)
      Convenience method, alternative to setPosition(Position).

    • setPosition

      public void setPosition(io.github.palexdev.mfxcore.base.beans.Position position)
      Sets the value of the position property.
      Property description:
      Specifies the current position of the viewport as a Position object which has both the x and y positions.
      Parameters:
      position - the value for the position property
      See Also:

    • getGridHelper

      public GridHelper getGridHelper()
      Gets the value of the gridHelper property.
      Property description:
      The current built helper for the grid, see GridHelper.
      Returns:
      the value of the gridHelper property
      See Also:

    • gridHelperProperty

      public ReadOnlyObjectProperty<GridHelper> gridHelperProperty()
      The current built helper for the grid, see GridHelper.
      Returns:
      the gridHelper property
      See Also:

    • setGridHelper

      protected void setGridHelper(GridHelper helper)
      Sets the value of the gridHelper property.
      Property description:
      The current built helper for the grid, see GridHelper.
      Parameters:
      helper - the value for the gridHelper property
      See Also:

    • getGridHelperSupplier

      public Supplier<GridHelper> getGridHelperSupplier()
      To allow more customization on how the cells are laid out, the virtual grid allows you to specify a supplier used to build a GridHelper which is responsible for some core actions about cells and layout. This way you could implement your own helper and set it through this factory since the gridHelperProperty() is intended to be read-only.

    • gridHelperSupplierProperty

      public io.github.palexdev.mfxcore.base.properties.functional.SupplierProperty<GridHelper> gridHelperSupplierProperty()
      Returns:
      the gridHelperSupplier property
      See Also:

    • setGridHelperSupplier

      public void setGridHelperSupplier(Supplier<GridHelper> gridHelperSupplier)
      Sets the value of the gridHelperSupplier property.
      Property description:
      Parameters:
      gridHelperSupplier - the value for the gridHelperSupplier property
      See Also:

    • isNeedsViewportLayout

      public boolean isNeedsViewportLayout()
      Gets the value of the needsViewportLayout property.
      Property description:
      Specifies whether the viewport needs to compute the layout of its content.

      Since this is read-only, layout requests must be sent by using requestViewportLayout().

      Returns:
      the value of the needsViewportLayout property
      See Also:

    • needsViewportLayoutProperty

      public ReadOnlyBooleanProperty needsViewportLayoutProperty()
      Specifies whether the viewport needs to compute the layout of its content.

      Since this is read-only, layout requests must be sent by using requestViewportLayout().

      Returns:
      the needsViewportLayout property
      See Also:

    • setNeedsViewportLayout

      protected void setNeedsViewportLayout(boolean needsViewportLayout)
      Sets the value of the needsViewportLayout property.
      Property description:
      Specifies whether the viewport needs to compute the layout of its content.

      Since this is read-only, layout requests must be sent by using requestViewportLayout().

      Parameters:
      needsViewportLayout - the value for the needsViewportLayout property
      See Also: