Package io.github.palexdev.virtualizedfx.flow.simple

Class CellsManager<T,​C extends Cell<T>>

java.lang.Object
io.github.palexdev.virtualizedfx.flow.simple.CellsManager<T,​C>
Type Parameters:
T - the type of object to represent
C - the type of Cell to use
public class CellsManager<T,​C extends Cell<T>> extends Object
Helper class to properly keep track of the needed cells, add them to the container, update them on scroll, and update the cells layout.

The 'system' is quite simple yet super efficient: it keeps a List called cellsPool that contains a number of cells (this number is the maximum number of cells that can be shown into the viewport). During initialization the cellPool is populated by initCells(int) and then added to the container, they are also updated to be sure they are showing the right content. On scroll updateCells(int, int) is called, this method processes the needed updates to do (CellsManager.CellUpdate), then updates the cells, the layout by calling processLayout(List) and finally updates the indexes range of shown items.

The important part to understand is that rather than creating new cells everytime the flow scrolls we update the already created cells so the scroll is very smooth, and it's also efficient in terms of memory usage. This allows the flow to handle huge amounts of items (depending on cells' complexity of course).

  • Constructor Summary

    Constructors
    Constructor
    Description
    CellsManager​(SimpleVirtualFlowContainer<T,​C> container)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected C
    cellForIndex​(int index)
    Exchanges an index for a Cell.
    protected C
    cellForItem​(T item)
    Exchanges an item for a Cell.
    protected void
    clear()
    Resets the CellsManager by clearing the cellsPool, clearing the updates list and resetting the stored indexes range to [-1, -1].
    protected Map<Integer,​C>
    getCells()
     
    protected void
    initCells​(int num)
    Populates the cellsPool, adds them to the container and then calls updateCells(int, int) (indexes from 0 to num) to ensure the cells are displaying the right content (should not be needed though)
    void
    itemsChanged()
    Called when the items list changes, if the list has been cleared removes all the cells from the container then calls clear() and then exits.
    protected void
    processLayout​(List<io.github.palexdev.virtualizedfx.flow.simple.CellsManager.CellUpdate> updates)
    Responsible for laying out the cells from a list of CellsManager.CellUpdates.
    protected void
    supplyCells​(int start, int end)
    Creates new cells from the given 'start' index to the given 'end' index, the new cells are added to the cellsPool and to the container.
    protected void
    updateCells​(int start, int end)
    Responsible for updating the cells in the viewport.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

  • Method Details

    • initCells

      protected void initCells​(int num)
      Populates the cellsPool, adds them to the container and then calls updateCells(int, int) (indexes from 0 to num) to ensure the cells are displaying the right content (should not be needed though)
      Parameters:
      num - the number of cells to create

    • updateCells

      protected void updateCells​(int start, int end)
      Responsible for updating the cells in the viewport.

      If the items list is empty returns immediately.

      If the list was cleared, so start and end are invalid, computes the maximum number of cells the viewport can show and calls initCells(int), then exits as that method will then call this with valid indexes.

      If the new indexes range (start-end) is equal to the previous stored range it's not necessary to update the cells therefore exits. This check is ignored if the items list was changed (items replaced, added or removed), int this case it's needed to update.

      The next check is to verify there are enough cells to show all the items from 'start' to 'end', the number of cells to show is computed in "optimal" conditions, but at some point it's possible for example that the first visible cell is only shown partially, this means that the last visible cell should be a new cell that the cellsPool can't offer, in cases like this it's needed to create new cells by calling supplyCells(int, int)

      A similar check is made if there are too many cells, in this case cells are removed.

      The next step is a bit tricky. The cellsPool indexes go from 0 to size() of course, but the start and end parameters do not start from 0, let's say I have to show items from 10 to 20, so it's needed to use an "external" counter to get the cells from 0 to size(), while the items are retrieved from the list from 'start' to 'end', in this loop we create CellsManager.CellUpdate beans to make the code cleaner, after the loop CellsManager.CellUpdate.update() is called for each bean, then the layout is updated with processLayout(List) and finally the range of shown items is updated.
      Parameters:
      start - the start index from which retrieve the items from the items list
      end - the final index up to which retrieve items from the items list

    • itemsChanged

      public void itemsChanged()
      Called when the items list changes, if the list has been cleared removes all the cells from the container then calls clear() and then exits.

      Otherwise calls updateCells(int, int), the indexes used are the ones stored by the CellsManager.

    • processLayout

      protected void processLayout​(List<io.github.palexdev.virtualizedfx.flow.simple.CellsManager.CellUpdate> updates)
      Responsible for laying out the cells from a list of CellsManager.CellUpdates.

      Since the layoutX/layoutY properties of the container are updated according to the ScrollBars' value, the cells are positioned according to the item's index in the items list.

      To avoid if/else statements as much as possible the actual layout is computed by OrientationHelper.layout(Node, int, double, double).

    • clear

      protected void clear()
      Resets the CellsManager by clearing the cellsPool, clearing the updates list and resetting the stored indexes range to [-1, -1].

    • supplyCells

      protected void supplyCells​(int start, int end)
      Creates new cells from the given 'start' index to the given 'end' index, the new cells are added to the cellsPool and to the container.

    • cellForIndex

      protected C cellForIndex​(int index)
      Exchanges an index for a Cell.

      Gets the item at the given index in the items list then calls cellForItem(Object).

    • cellForItem

      protected C cellForItem​(T item)
      Exchanges an item for a Cell.

      Simply applies the VirtualFlow's cell factory to the given item.

    • getCells

      protected Map<Integer,​C> getCells()
      Returns:
      a map of the currently shown cells by the item's index