Class VFXList<T, C extends VFXCell<T>>

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.layout.Region
javafx.scene.control.Control
io.github.palexdev.mfxcore.controls.MFXControl
io.github.palexdev.virtualizedfx.list.VFXList<T,C>
Type Parameters:
T - the type of items in the list
C - the type of cells used by the container to visualize the items
All Implemented Interfaces:
io.github.palexdev.mfxcore.behavior.WithBehavior, io.github.palexdev.mfxcore.controls.MFXSkinnable, io.github.palexdev.mfxcore.controls.MFXStyleable, VFXContainer<T>, VFXScrollable, WithCellFactory<T,C>, javafx.css.Styleable, javafx.event.EventTarget, javafx.scene.control.Skinnable
Direct Known Subclasses:
VFXPaginatedList
public class VFXList<T, C extends VFXCell<T>> extends io.github.palexdev.mfxcore.controls.MFXControl implements VFXContainer<T>, WithCellFactory<T,C>, VFXScrollable

Implementation of a virtualized container to show a list of items either vertically or horizontally. The default style class is: '.vfx-list'.

Extends MFXControl, implements VFXContainer, has its own skin implementation VFXListSkin and behavior VFXListManager. Uses cells of type VFXCell.

This is a stateful component, meaning that every meaningful variable (position, size, cell size, etc.) will produce a new VFXListState when changing. The state determines which and how items are displayed in the container.

Features & Implementation Details

  • The default behavior implementation, VFXListManager, can be considered as the name suggests more like a 'manager' than an actual behavior. It is responsible for reacting to core changes in the functionalities defined here to produce a new state. The state can be considered like a 'picture' of the container at a certain time. Each combination of the variables that influence the way items are shown (how many, start, end, changes in the list, etc.) will produce a specific state. This is an important concept as some of the features I'm going to mention below are due to the combination of default skin + default behavior. You are allowed to change/customize the skin and the behavior as you please. BUT, beware, VFX * components are no joke, they are complex, make sure to read the documentation before!

  • The items list is managed automatically (permutations, insertions, removals, updates). Compared to previous algorithms, the VFXListManager adopts a much simpler strategy while still trying to keep the cell updates count as low as possible to improve performance. See VFXListManager.onItemsChanged().

  • The function used to generate the cells, called "cellFactory", can be changed anytime, even at runtime, see VFXListManager.onCellFactoryChanged().

  • The component is around the concept of a fixed cell size for all cells, this parameter can be controlled through the cellSizeProperty(), and can also be changed anytime, see VFXListManager.onCellSizeChanged().

  • Similar to the VBox pane, this container allows you to evenly space the cells in the viewport by setting the spacingProperty(). See VFXListManager.onSpacingChanged().

  • The container can be oriented either vertically or horizontally through the orientationProperty(). Depending on the orientation, the layout and other computations change. Thanks to polymorphism, it's possible to define a public API for such computations and implement two separate classes for each orientation, this is the VFXListHelper. You are allowed to change the helper through the helperFactoryProperty().

  • The vertical and horizontal positions are available through the properties vPosProperty() and hPosProperty(). It was indeed possible to use a single property for the position, but they are split for performance reasons.

  • The virtual bounds of the container are given by two properties:

a) the virtualMaxXProperty() which specifies the total number of pixels on the x-axis

b) the virtualMaxYProperty() which specifies the total number of pixels on the y-axis

The value of such properties depends on the container's orientation. The virtualized axis will have its value given by   the total number of items in the list multiplied by the cell size, the spacing is included too. The other axis will have   its value given by the biggest (in height or width) cell in the viewport.

  • You can access the current state through the stateProperty(). The state gives crucial information about the container such as the range of displayed items and the visible cells (by index and by item). If you'd like to observe for changes in the displayed cells, then you want to add a listener on this property.

  • It is possible to programmatically tell the viewport to update its layout with requestViewportLayout(), although this should never be necessary as it is handled automatically when the state changes.

  • Additionally, this container makes use of a simple cache implementation, VFXCellsCache, which avoids creating new cells when needed if some are already present in it. The most crucial aspect for this kind of virtualization is to avoid creating nodes, as this is the most expensive operation. Not only nodes need to be created but also added to the container and then laid out. Instead, it's much more likely that the VFXCell.updateItem(Object) will be simple and faster. Note that to make the cache more generic, thus allowing its usage in more cases, a recent refactor, removed the dependency on the container itself and replaced it with the cell factory. Since the cache can also populate itself with "empty" cells, it must know how to create them. The cache's cell factory is automatically synchronized with the container's one.

  • Property Summary

    Properties
    Type
    Property
    Description
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableObjectProperty<BufferSize>
    bufferSize
    Specifies the number of extra cells to add to the container; they act as a buffer, allowing scroll to be smoother.
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableIntegerProperty
    cacheCapacity
    Specifies the maximum number of cells the cache can contain at any time.
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableDoubleProperty
    cellSize
    Specifies the cells' size:
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableDoubleProperty
    clipBorderRadius
    Used by the viewport's clip to set its border radius.
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableBooleanProperty
    fitToViewport
    Specifies whether cells should be resized to be the same size of the viewport in the opposite direction of the current orientationProperty().
    io.github.palexdev.mfxcore.base.properties.functional.FunctionProperty<javafx.geometry.Orientation, VFXListHelper<T,C>>
    helperFactory
    Specifies the function used to build a VFXListHelper instance depending on the container's orientation.
    javafx.beans.property.ReadOnlyObjectProperty<VFXListHelper<T,C>>
    helper
    Specifies the instance of the VFXListHelper built by the helperFactoryProperty().
    javafx.beans.property.DoubleProperty
    hPos
    Specifies the container's horizontal position.
    javafx.beans.property.ListProperty<T>
    items
    Specifies the ObservableList used to store the items.
    javafx.beans.property.ReadOnlyDoubleProperty
    maxHScroll
    Delegate for VFXContainerHelper.maxHScrollProperty().
    javafx.beans.property.ReadOnlyDoubleProperty
    maxVScroll
    Delegate for VFXContainerHelper.maxVScrollProperty().
    javafx.beans.property.ReadOnlyBooleanProperty
    needsViewportLayout
    Specifies whether the viewport needs to compute the layout of its content.
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableObjectProperty<javafx.geometry.Orientation>
    orientation
    Specifies the orientation of the container.
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableDoubleProperty
    spacing
    Specifies the number of pixels between each cell.
    javafx.beans.property.ReadOnlyObjectProperty<VFXListState<T,C>>
    state
    Specifies the container's current state.
    javafx.beans.property.ReadOnlyDoubleProperty
    virtualMaxX
    Delegate for VFXContainerHelper.virtualMaxXProperty()
    javafx.beans.property.ReadOnlyDoubleProperty
    virtualMaxY
    Delegate for VFXContainerHelper.virtualMaxYProperty()
    javafx.beans.property.DoubleProperty
    vPos
    Specifies the container's vertical position.

    Properties inherited from class io.github.palexdev.mfxcore.controls.MFXControl

    behaviorFactory, skinFactory

    Properties inherited from class javafx.scene.control.Control

    contextMenu, skin, tooltip

    Properties inherited from class javafx.scene.layout.Region

    background, border, cacheShape, centerShape, height, insets, maxHeight, maxWidth, minHeight, minWidth, opaqueInsets, padding, prefHeight, prefWidth, scaleShape, shape, snapToPixel, width

    Properties inherited from class javafx.scene.Parent

    needsLayout

    Properties inherited from class javafx.scene.Node

    accessibleHelp, accessibleRoleDescription, accessibleRole, accessibleText, blendMode, boundsInLocal, boundsInParent, cacheHint, cache, clip, cursor, depthTest, disabled, disable, effectiveNodeOrientation, effect, eventDispatcher, focused, focusTraversable, focusVisible, focusWithin, hover, id, inputMethodRequests, layoutBounds, layoutX, layoutY, localToParentTransform, localToSceneTransform, managed, mouseTransparent, nodeOrientation, onContextMenuRequested, onDragDetected, onDragDone, onDragDropped, onDragEntered, onDragExited, onDragOver, onInputMethodTextChanged, onKeyPressed, onKeyReleased, onKeyTyped, onMouseClicked, onMouseDragDone, onMouseDragEntered, onMouseDragExited, onMouseDragged, onMouseDragOver, onMouseDragReleased, onMouseEntered, onMouseExited, onMouseMoved, onMousePressed, onMouseReleased, onRotate, onRotationFinished, onRotationStarted, onScrollFinished, onScroll, onScrollStarted, onSwipeDown, onSwipeLeft, onSwipeRight, onSwipeUp, onTouchMoved, onTouchPressed, onTouchReleased, onTouchStationary, onZoomFinished, onZoom, onZoomStarted, opacity, parent, pickOnBounds, pressed, rotate, rotationAxis, scaleX, scaleY, scaleZ, scene, style, translateX, translateY, translateZ, viewOrder, visible

    Properties inherited from interface javafx.scene.control.Skinnable

    skin

    Properties inherited from interface VFXContainer

    empty, size

  • Field Summary

    Fields inherited from class javafx.scene.layout.Region

    USE_COMPUTED_SIZE, USE_PREF_SIZE

    Fields inherited from class javafx.scene.Node

    BASELINE_OFFSET_SAME_AS_HEIGHT

  • Constructor Summary

    Constructors
    Constructor
    Description
    VFXList()
     
    VFXList(javafx.collections.ObservableList<T> items, Function<T,C> cellFactory)
     
    VFXList(javafx.collections.ObservableList<T> items, Function<T,C> cellFactory, javafx.geometry.Orientation orientation)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableObjectProperty<BufferSize>
    bufferSizeProperty()
    Specifies the number of extra cells to add to the container; they act as a buffer, allowing scroll to be smoother.
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableIntegerProperty
    cacheCapacityProperty()
    Specifies the maximum number of cells the cache can contain at any time.
    int
    cacheSize()
    Delegate for VFXCellsCache.size().
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableDoubleProperty
    cellSizeProperty()
    Specifies the cells' size:
    void
    clip(boolean enable)
    Clips this virtualized container to avoid content from overflowing by using a Rectangle node with:
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableDoubleProperty
    clipBorderRadiusProperty()
    Used by the viewport's clip to set its border radius.
    VFXContext<T>
    context()
     
    protected VFXCellsCache<T,C>
    createCache()
    Responsible for creating the cache instance used by this container.
    Supplier<io.github.palexdev.mfxcore.behavior.MFXBehavior<? extends javafx.scene.Node>>
    defaultBehaviorFactory()
     
    protected Function<javafx.geometry.Orientation, VFXListHelper<T,C>>
    defaultHelperFactory()
     
    Supplier<io.github.palexdev.mfxcore.controls.MFXSkinBase<? extends javafx.scene.Node>>
    defaultSkinFactory()
     
    List<String>
    defaultStyleClasses()
     
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableBooleanProperty
    fitToViewportProperty()
    Specifies whether cells should be resized to be the same size of the viewport in the opposite direction of the current orientationProperty().
    protected VFXCellsCache<T,C>
    getCache()
     
    int
    getCacheCapacity()
    Gets the value of the cacheCapacity property.
    CellFactory<T,C>
    getCellFactory()
    Specifies the wrapper class CellFactory for the cell factory function
    SequencedMap<Integer,C>
    getCellsByIndexUnmodifiable()
    Delegate for VFXListState.getCellsByIndexUnmodifiable()
    List<Map.Entry<T,C>>
    getCellsByItemUnmodifiable()
    Delegate for VFXListState.getCellsByItemUnmodifiable()
    double
    getCellSize()
    Gets the value of the cellSize property.
    static List<javafx.css.CssMetaData<? extends javafx.css.Styleable, ?>>
    getClassCssMetaData()
     
    double
    getClipBorderRadius()
    Gets the value of the clipBorderRadius property.
    protected List<javafx.css.CssMetaData<? extends javafx.css.Styleable, ?>>
    getControlCssMetaData()
     
    VFXListHelper<T,C>
    getHelper()
    Gets the value of the helper property.
    Function<javafx.geometry.Orientation, VFXListHelper<T,C>>
    getHelperFactory()
    Gets the value of the helperFactory property.
    javafx.geometry.Orientation
    getOrientation()
    Gets the value of the orientation property.
    io.github.palexdev.mfxcore.base.beans.range.IntegerRange
    getRange()
    Delegate for VFXListState.getRange()
    double
    getSpacing()
    Gets the value of the spacing property.
    VFXListState<T,C>
    getState()
    Gets the value of the state property.
    io.github.palexdev.mfxcore.base.properties.functional.FunctionProperty<javafx.geometry.Orientation, VFXListHelper<T,C>>
    helperFactoryProperty()
    Specifies the function used to build a VFXListHelper instance depending on the container's orientation.
    javafx.beans.property.ReadOnlyObjectProperty<VFXListHelper<T,C>>
    helperProperty()
    Specifies the instance of the VFXListHelper built by the helperFactoryProperty().
    javafx.beans.property.DoubleProperty
    hPosProperty()
    Specifies the container's horizontal position.
    boolean
    isFitToViewport()
    Gets the value of the fitToViewport property.
    boolean
    isNeedsViewportLayout()
    Gets the value of the needsViewportLayout property.
    javafx.beans.property.ListProperty<T>
    itemsProperty()
    Specifies the ObservableList used to store the items.
    VFXScrollPane
    makeScrollable()
    Wraps this in a VFXScrollPane to enable scrolling.
    javafx.beans.property.ReadOnlyDoubleProperty
    maxHScrollProperty()
    Delegate for VFXContainerHelper.maxHScrollProperty().
    javafx.beans.property.ReadOnlyDoubleProperty
    maxVScrollProperty()
    Delegate for VFXContainerHelper.maxVScrollProperty().
    javafx.beans.property.ReadOnlyBooleanProperty
    needsViewportLayoutProperty()
    Specifies whether the viewport needs to compute the layout of its content.
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableObjectProperty<javafx.geometry.Orientation>
    orientationProperty()
    Specifies the orientation of the container.
    VFXList<T,C>
    populateCache()
    Delegate for VFXCellsCache.populate().
    void
    requestViewportLayout()
    Setter for the needsViewportLayoutProperty().
    void
    scrollBy(double pixels)
    Delegate for VFXListHelper.scrollBy(double).
    void
    scrollToFirst()
    Shortcut for scrollToIndex(0).
    void
    scrollToIndex(int index)
    Delegate for VFXListHelper.scrollToIndex(int).
    void
    scrollToLast()
    Shortcut for scrollToIndex(size() - 1).
    void
    scrollToPixel(double pixel)
    Delegate for VFXListHelper.scrollToPixel(double).
    void
    setCacheCapacity(int cacheCapacity)
    Sets the value of the cacheCapacity property.
    void
    setCellSize(double cellSize)
    Sets the value of the cellSize property.
    void
    setClipBorderRadius(double clipBorderRadius)
    Sets the value of the clipBorderRadius property.
    void
    setFitToViewport(boolean fitToViewport)
    Sets the value of the fitToViewport property.
    protected void
    setHelper(VFXListHelper<T,C> helper)
    Sets the value of the helper property.
    void
    setHelperFactory(Function<javafx.geometry.Orientation, VFXListHelper<T,C>> helperFactory)
    Sets the value of the helperFactory property.
    protected void
    setNeedsViewportLayout(boolean needsViewportLayout)
    Sets the value of the needsViewportLayout property.
    void
    setOrientation(javafx.geometry.Orientation orientation)
    Sets the value of the orientation property.
    void
    setSpacing(double spacing)
    Sets the value of the spacing property.
    protected void
    setState(VFXListState<T,C> state)
    Sets the value of the state property.
    io.github.palexdev.mfxcore.base.properties.styleable.StyleableDoubleProperty
    spacingProperty()
    Specifies the number of pixels between each cell.
    javafx.beans.property.ReadOnlyObjectProperty<VFXListState<T,C>>
    stateProperty()
    Specifies the container's current state.
    void
    update(int... indexes)
    This method should be used by implementations to "manually" update the container.
    protected void
    update(VFXListState<T,C> state)
    Setter for the stateProperty().
    javafx.beans.property.ReadOnlyDoubleProperty
    virtualMaxXProperty()
    Delegate for VFXContainerHelper.virtualMaxXProperty()
    javafx.beans.property.ReadOnlyDoubleProperty
    virtualMaxYProperty()
    Delegate for VFXContainerHelper.virtualMaxYProperty()
    javafx.beans.property.DoubleProperty
    vPosProperty()
    Specifies the container's vertical position.

    Methods inherited from class io.github.palexdev.mfxcore.controls.MFXControl

    behaviorFactoryProperty, buildSkin, createDefaultSkin, getBehavior, preloadSkin, skinFactoryProperty

    Methods inherited from class javafx.scene.control.Control

    computeMaxHeight, computeMaxWidth, computeMinHeight, computeMinWidth, computePrefHeight, computePrefWidth, contextMenuProperty, executeAccessibleAction, getBaselineOffset, getContextMenu, getCssMetaData, getInitialFocusTraversable, getSkin, getTooltip, isResizable, layoutChildren, queryAccessibleAttribute, setContextMenu, setSkin, setTooltip, skinProperty, tooltipProperty

    Methods inherited from class javafx.scene.layout.Region

    backgroundProperty, borderProperty, cacheShapeProperty, centerShapeProperty, getBackground, getBorder, getHeight, getInsets, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpaqueInsets, getPadding, getPrefHeight, getPrefWidth, getShape, getUserAgentStylesheet, getWidth, heightProperty, insetsProperty, isCacheShape, isCenterShape, isScaleShape, isSnapToPixel, layoutInArea, layoutInArea, layoutInArea, layoutInArea, maxHeight, maxHeightProperty, maxWidth, maxWidthProperty, minHeight, minHeightProperty, minWidth, minWidthProperty, opaqueInsetsProperty, paddingProperty, positionInArea, positionInArea, prefHeight, prefHeightProperty, prefWidth, prefWidthProperty, resize, scaleShapeProperty, setBackground, setBorder, setCacheShape, setCenterShape, setHeight, setMaxHeight, setMaxSize, setMaxWidth, setMinHeight, setMinSize, setMinWidth, setOpaqueInsets, setPadding, setPrefHeight, setPrefSize, setPrefWidth, setScaleShape, setShape, setSnapToPixel, setWidth, shapeProperty, snappedBottomInset, snappedLeftInset, snappedRightInset, snappedTopInset, snapPosition, snapPositionX, snapPositionY, snapSize, snapSizeX, snapSizeY, snapSpace, snapSpaceX, snapSpaceY, snapToPixelProperty, widthProperty

    Methods inherited from class javafx.scene.Parent

    getChildren, getChildrenUnmodifiable, getManagedChildren, getStylesheets, isNeedsLayout, layout, lookup, needsLayoutProperty, requestLayout, requestParentLayout, setNeedsLayout, updateBounds

    Methods inherited from class javafx.scene.Node

    accessibleHelpProperty, accessibleRoleDescriptionProperty, accessibleRoleProperty, accessibleTextProperty, addEventFilter, addEventHandler, applyCss, autosize, blendModeProperty, boundsInLocalProperty, boundsInParentProperty, buildEventDispatchChain, cacheHintProperty, cacheProperty, clipProperty, computeAreaInScreen, contains, contains, cursorProperty, depthTestProperty, disabledProperty, disableProperty, effectiveNodeOrientationProperty, effectProperty, eventDispatcherProperty, fireEvent, focusedProperty, focusTraversableProperty, focusVisibleProperty, focusWithinProperty, getAccessibleHelp, getAccessibleRole, getAccessibleRoleDescription, getAccessibleText, getBlendMode, getBoundsInLocal, getBoundsInParent, getCacheHint, getClip, getContentBias, getCursor, getDepthTest, getEffect, getEffectiveNodeOrientation, getEventDispatcher, getId, getInitialCursor, getInputMethodRequests, getLayoutBounds, getLayoutX, getLayoutY, getLocalToParentTransform, getLocalToSceneTransform, getNodeOrientation, getOnContextMenuRequested, getOnDragDetected, getOnDragDone, getOnDragDropped, getOnDragEntered, getOnDragExited, getOnDragOver, getOnInputMethodTextChanged, getOnKeyPressed, getOnKeyReleased, getOnKeyTyped, getOnMouseClicked, getOnMouseDragDone, getOnMouseDragEntered, getOnMouseDragExited, getOnMouseDragged, getOnMouseDragOver, getOnMouseDragReleased, getOnMouseEntered, getOnMouseExited, getOnMouseMoved, getOnMousePressed, getOnMouseReleased, getOnRotate, getOnRotationFinished, getOnRotationStarted, getOnScroll, getOnScrollFinished, getOnScrollStarted, getOnSwipeDown, getOnSwipeLeft, getOnSwipeRight, getOnSwipeUp, getOnTouchMoved, getOnTouchPressed, getOnTouchReleased, getOnTouchStationary, getOnZoom, getOnZoomFinished, getOnZoomStarted, getOpacity, getParent, getProperties, getPseudoClassStates, getRotate, getRotationAxis, getScaleX, getScaleY, getScaleZ, getScene, getStyle, getStyleableParent, getStyleClass, getTransforms, getTranslateX, getTranslateY, getTranslateZ, getTypeSelector, getUserData, getViewOrder, hasProperties, hoverProperty, idProperty, inputMethodRequestsProperty, intersects, intersects, isCache, isDisable, isDisabled, isFocused, isFocusTraversable, isFocusVisible, isFocusWithin, isHover, isManaged, isMouseTransparent, isPickOnBounds, isPressed, isVisible, layoutBoundsProperty, layoutXProperty, layoutYProperty, localToParent, localToParent, localToParent, localToParent, localToParent, localToParentTransformProperty, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToSceneTransformProperty, localToScreen, localToScreen, localToScreen, localToScreen, localToScreen, lookupAll, managedProperty, mouseTransparentProperty, nodeOrientationProperty, notifyAccessibleAttributeChanged, onContextMenuRequestedProperty, onDragDetectedProperty, onDragDoneProperty, onDragDroppedProperty, onDragEnteredProperty, onDragExitedProperty, onDragOverProperty, onInputMethodTextChangedProperty, onKeyPressedProperty, onKeyReleasedProperty, onKeyTypedProperty, onMouseClickedProperty, onMouseDragDoneProperty, onMouseDragEnteredProperty, onMouseDragExitedProperty, onMouseDraggedProperty, onMouseDragOverProperty, onMouseDragReleasedProperty, onMouseEnteredProperty, onMouseExitedProperty, onMouseMovedProperty, onMousePressedProperty, onMouseReleasedProperty, onRotateProperty, onRotationFinishedProperty, onRotationStartedProperty, onScrollFinishedProperty, onScrollProperty, onScrollStartedProperty, onSwipeDownProperty, onSwipeLeftProperty, onSwipeRightProperty, onSwipeUpProperty, onTouchMovedProperty, onTouchPressedProperty, onTouchReleasedProperty, onTouchStationaryProperty, onZoomFinishedProperty, onZoomProperty, onZoomStartedProperty, opacityProperty, parentProperty, parentToLocal, parentToLocal, parentToLocal, parentToLocal, parentToLocal, pickOnBoundsProperty, pressedProperty, pseudoClassStateChanged, relocate, removeEventFilter, removeEventHandler, requestFocus, requestFocusTraversal, resizeRelocate, rotateProperty, rotationAxisProperty, scaleXProperty, scaleYProperty, scaleZProperty, sceneProperty, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, screenToLocal, screenToLocal, screenToLocal, setAccessibleHelp, setAccessibleRole, setAccessibleRoleDescription, setAccessibleText, setBlendMode, setCache, setCacheHint, setClip, setCursor, setDepthTest, setDisable, setDisabled, setEffect, setEventDispatcher, setEventHandler, setFocused, setFocusTraversable, setHover, setId, setInputMethodRequests, setLayoutX, setLayoutY, setManaged, setMouseTransparent, setNodeOrientation, setOnContextMenuRequested, setOnDragDetected, setOnDragDone, setOnDragDropped, setOnDragEntered, setOnDragExited, setOnDragOver, setOnInputMethodTextChanged, setOnKeyPressed, setOnKeyReleased, setOnKeyTyped, setOnMouseClicked, setOnMouseDragDone, setOnMouseDragEntered, setOnMouseDragExited, setOnMouseDragged, setOnMouseDragOver, setOnMouseDragReleased, setOnMouseEntered, setOnMouseExited, setOnMouseMoved, setOnMousePressed, setOnMouseReleased, setOnRotate, setOnRotationFinished, setOnRotationStarted, setOnScroll, setOnScrollFinished, setOnScrollStarted, setOnSwipeDown, setOnSwipeLeft, setOnSwipeRight, setOnSwipeUp, setOnTouchMoved, setOnTouchPressed, setOnTouchReleased, setOnTouchStationary, setOnZoom, setOnZoomFinished, setOnZoomStarted, setOpacity, setPickOnBounds, setPressed, setRotate, setRotationAxis, setScaleX, setScaleY, setScaleZ, setStyle, setTranslateX, setTranslateY, setTranslateZ, setUserData, setViewOrder, setVisible, snapshot, snapshot, startDragAndDrop, startFullDrag, styleProperty, toBack, toFront, toString, translateXProperty, translateYProperty, translateZProperty, usesMirroring, viewOrderProperty, visibleProperty

    Methods inherited from class Object

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

    Methods inherited from interface io.github.palexdev.mfxcore.controls.MFXSkinnable

    getSkinFactory, setDefaultSkinFactory, setSkinFactory

    Methods inherited from interface io.github.palexdev.mfxcore.controls.MFXStyleable

    setDefaultStyleClasses

    Methods inherited from interface javafx.scene.control.Skinnable

    getSkin, setSkin, skinProperty

    Methods inherited from interface javafx.css.Styleable

    getCssMetaData, getId, getPseudoClassStates, getStyle, getStyleableNode, getStyleableParent, getStyleClass, getTypeSelector

    Methods inherited from interface VFXContainer

    emptyProperty, getBufferSize, getHPos, getItems, getMaxHScroll, getMaxVScroll, getVirtualMaxX, getVirtualMaxY, getVPos, isEmpty, setBufferSize, setHPos, setItems, setVPos, size, sizeProperty

    Methods inherited from interface io.github.palexdev.mfxcore.behavior.WithBehavior

    getBehaviorFactory, setBehaviorFactory, setDefaultBehaviorFactory

    Methods inherited from interface WithCellFactory

    create, setCellFactory

  • Property Details

  • Constructor Details

    • VFXList

      public VFXList()

    • VFXList

      public VFXList(javafx.collections.ObservableList<T> items, Function<T,C> cellFactory)

    • VFXList

      public VFXList(javafx.collections.ObservableList<T> items, Function<T,C> cellFactory, javafx.geometry.Orientation orientation)

  • Method Details

    • createCache

      protected VFXCellsCache<T,C> createCache()
      Responsible for creating the cache instance used by this container.
      See Also:

    • update

      protected void update(VFXListState<T,C> state)
      Setter for the stateProperty().

    • defaultHelperFactory

      protected Function<javafx.geometry.Orientation, VFXListHelper<T,C>> defaultHelperFactory()
      Returns:
      the default function used to produce a VFXListHelper according to the container's orientation.

    • requestViewportLayout

      public void requestViewportLayout()
      Setter for the needsViewportLayoutProperty(). This sets the property to true, causing the default skin to recompute the cells' layout.

    • clip

      public void clip(boolean enable)

      Clips this virtualized container to avoid content from overflowing by using a Rectangle node with:

      By default, the clip is disabled because virtualized containers are meant to be used in combination with a scoll pane which already clips its viewport. Fewer nodes, more performance.

      Parameters:
      enable - whether to enable or disable the clip

    • update

      public void update(int... indexes)
      Description copied from interface: VFXContainer

      This method should be used by implementations to "manually" update the container.

      This can be useful when working with models that do not use JavaFX properties.

      Note: the indexes vararg parameter can be used to specify which cells need to be updated. An empty array should update all of them.

      More details: some cells may use an update mechanism which relies on property invalidation. Follow this example to better understand what I mean:

      // Let's say I have a User class with 'firstName' and 'lastName' fields (we also have both getters and setters)
// Now, let's assume I have a UserCell class used by the VFXContainer to display User objects (in a label for example)
// This is a part of its implementation...
public class UserCell extends Label implements VFXCell<User> {
    private final ObjectProperty<User> item = new SimpleObjectProperty<>(){
                 void invalidated(){
            update();
}
};
    protected void update(){
// This will update the cell's text based on the current item
}
}
// Remember, the 'invalidated()' method is called only when the reference changes, because internally it does not
// check for equality but for identity
// Now let's say I want to change a User's 'lastName' field like this...
container.getItems().get(i).setLastName("NewLastName");
// Question: how can we tell the cell to force the update?
// There are two possible ways...
// 1) For the invalidation to occur, we first set the item property to 'null', and then back to the old value
// 2) We use an event-based mechanism to tell cells to force update themselves. This solution requires cells to
// subscribe to such events to support "manual" updates
// Solution 2 is more flexible, see VFXContainerEvent class
      Specified by:
      update in interface VFXContainer<T>
      See Also:

    • defaultBehaviorFactory

      public Supplier<io.github.palexdev.mfxcore.behavior.MFXBehavior<? extends javafx.scene.Node>> defaultBehaviorFactory()
      Specified by:
      defaultBehaviorFactory in interface io.github.palexdev.mfxcore.behavior.WithBehavior

    • defaultSkinFactory

      public Supplier<io.github.palexdev.mfxcore.controls.MFXSkinBase<? extends javafx.scene.Node>> defaultSkinFactory()
      Specified by:
      defaultSkinFactory in interface io.github.palexdev.mfxcore.controls.MFXSkinnable

    • defaultStyleClasses

      public List<String> defaultStyleClasses()
      Specified by:
      defaultStyleClasses in interface io.github.palexdev.mfxcore.controls.MFXStyleable

    • makeScrollable

      public VFXScrollPane makeScrollable()
      Description copied from interface: VFXScrollable
      Wraps this in a VFXScrollPane to enable scrolling.
      Specified by:
      makeScrollable in interface VFXScrollable

    • populateCache

      public VFXList<T,C> populateCache()
      Delegate for VFXCellsCache.populate().

    • getRange

      public io.github.palexdev.mfxcore.base.beans.range.IntegerRange getRange()
      Delegate for VFXListState.getRange()

    • getCellsByIndexUnmodifiable

      public SequencedMap<Integer,C> getCellsByIndexUnmodifiable()
      Delegate for VFXListState.getCellsByIndexUnmodifiable()

    • getCellsByItemUnmodifiable

      public List<Map.Entry<T,C>> getCellsByItemUnmodifiable()
      Delegate for VFXListState.getCellsByItemUnmodifiable()

    • virtualMaxXProperty

      public javafx.beans.property.ReadOnlyDoubleProperty virtualMaxXProperty()
      Delegate for VFXContainerHelper.virtualMaxXProperty()
      Specified by:
      virtualMaxXProperty in interface VFXContainer<T>
      Returns:
      the virtualMaxX property
      See Also:

    • virtualMaxYProperty

      public javafx.beans.property.ReadOnlyDoubleProperty virtualMaxYProperty()
      Delegate for VFXContainerHelper.virtualMaxYProperty()
      Specified by:
      virtualMaxYProperty in interface VFXContainer<T>
      Returns:
      the virtualMaxY property
      See Also:

    • maxVScrollProperty

      public javafx.beans.property.ReadOnlyDoubleProperty maxVScrollProperty()
      Delegate for VFXContainerHelper.maxVScrollProperty().
      Specified by:
      maxVScrollProperty in interface VFXContainer<T>
      Returns:
      the maxVScroll property
      See Also:

    • maxHScrollProperty

      public javafx.beans.property.ReadOnlyDoubleProperty maxHScrollProperty()
      Delegate for VFXContainerHelper.maxHScrollProperty().
      Specified by:
      maxHScrollProperty in interface VFXContainer<T>
      Returns:
      the maxHScroll property
      See Also:

    • scrollBy

      public void scrollBy(double pixels)
      Delegate for VFXListHelper.scrollBy(double).

    • scrollToPixel

      public void scrollToPixel(double pixel)
      Delegate for VFXListHelper.scrollToPixel(double).

    • scrollToIndex

      public void scrollToIndex(int index)
      Delegate for VFXListHelper.scrollToIndex(int).

    • scrollToFirst

      public void scrollToFirst()
      Shortcut for scrollToIndex(0).

    • scrollToLast

      public void scrollToLast()
      Shortcut for scrollToIndex(size() - 1).

    • getCellSize

      public double getCellSize()
      Gets the value of the cellSize property.
      Property description:

      Specifies the cells' size:

      • Orientation.VERTICAL: size -> height

      • Orientation.HORIZONTAL: size -> width

      Can be set in CSS via the property: '-vfx-cell-size'.

      Returns:
      the value of the cellSize property
      See Also:

    • cellSizeProperty

      public io.github.palexdev.mfxcore.base.properties.styleable.StyleableDoubleProperty cellSizeProperty()

      Specifies the cells' size:

      • Orientation.VERTICAL: size -> height

      • Orientation.HORIZONTAL: size -> width

      Can be set in CSS via the property: '-vfx-cell-size'.

      Returns:
      the cellSize property
      See Also:

    • setCellSize

      public void setCellSize(double cellSize)
      Sets the value of the cellSize property.
      Property description:

      Specifies the cells' size:

      • Orientation.VERTICAL: size -> height

      • Orientation.HORIZONTAL: size -> width

      Can be set in CSS via the property: '-vfx-cell-size'.

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

    • getSpacing

      public double getSpacing()
      Gets the value of the spacing property.
      Property description:

      Specifies the number of pixels between each cell.

      Can be set in CSS via the property: '-vfx-spacing'

      Returns:
      the value of the spacing property
      See Also:

    • spacingProperty

      public io.github.palexdev.mfxcore.base.properties.styleable.StyleableDoubleProperty spacingProperty()

      Specifies the number of pixels between each cell.

      Can be set in CSS via the property: '-vfx-spacing'

      Returns:
      the spacing property
      See Also:

    • setSpacing

      public void setSpacing(double spacing)
      Sets the value of the spacing property.
      Property description:

      Specifies the number of pixels between each cell.

      Can be set in CSS via the property: '-vfx-spacing'

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

    • bufferSizeProperty

      public io.github.palexdev.mfxcore.base.properties.styleable.StyleableObjectProperty<BufferSize> bufferSizeProperty()

      Specifies the number of extra cells to add to the container; they act as a buffer, allowing scroll to be smoother. To avoid edge cases due to the users abusing the system, this is done by using an enumerator which allows up to three buffer cells.

      Also, the default implementation (see VFXListHelper.VerticalHelper or VFXListHelper.HorizontalHelper), adds double the number specified by the enum constant, because these buffer cells are added both at the top and at the bottom of the container. The default value is BufferSize.MEDIUM.

      Can be set in CSS via the property: '-vfx-buffer-size'.

      Specified by:
      bufferSizeProperty in interface VFXContainer<T>
      Returns:
      the bufferSize property
      See Also:

    • getOrientation

      public javafx.geometry.Orientation getOrientation()
      Gets the value of the orientation property.
      Property description:

      Specifies the orientation of the container.

      Can be set in CSS via the property: '-vfx-orientation'.

      Returns:
      the value of the orientation property
      See Also:

    • orientationProperty

      public io.github.palexdev.mfxcore.base.properties.styleable.StyleableObjectProperty<javafx.geometry.Orientation> orientationProperty()

      Specifies the orientation of the container.

      Can be set in CSS via the property: '-vfx-orientation'.

      Returns:
      the orientation property
      See Also:

    • setOrientation

      public void setOrientation(javafx.geometry.Orientation orientation)
      Sets the value of the orientation property.
      Property description:

      Specifies the orientation of the container.

      Can be set in CSS via the property: '-vfx-orientation'.

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

    • isFitToViewport

      public boolean isFitToViewport()
      Gets the value of the fitToViewport property.
      Property description:

      Specifies whether cells should be resized to be the same size of the viewport in the opposite direction of the current orientationProperty().

      Can be set in CSS via the property: '-vfx-fit-to-viewport'.

      Returns:
      the value of the fitToViewport property
      See Also:

    • fitToViewportProperty

      public io.github.palexdev.mfxcore.base.properties.styleable.StyleableBooleanProperty fitToViewportProperty()

      Specifies whether cells should be resized to be the same size of the viewport in the opposite direction of the current orientationProperty().

      Can be set in CSS via the property: '-vfx-fit-to-viewport'.

      Returns:
      the fitToViewport property
      See Also:

    • setFitToViewport

      public void setFitToViewport(boolean fitToViewport)
      Sets the value of the fitToViewport property.
      Property description:

      Specifies whether cells should be resized to be the same size of the viewport in the opposite direction of the current orientationProperty().

      Can be set in CSS via the property: '-vfx-fit-to-viewport'.

      Parameters:
      fitToViewport - the value for the fitToViewport 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 container, this prevents the content from going outside the view.

      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.

      Can be set in CSS via the property: '-vfx-clip-border-radius'.

      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 container, this prevents the content from going outside the view.

      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.

      Can be set in CSS via the property: '-vfx-clip-border-radius'.

      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 container, this prevents the content from going outside the view.

      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.

      Can be set in CSS via the property: '-vfx-clip-border-radius'.

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

    • getCacheCapacity

      public int getCacheCapacity()
      Gets the value of the cacheCapacity property.
      Property description:

      Specifies the maximum number of cells the cache can contain at any time. Excess will not be added to the queue and disposed immediately.

      Can be set in CSS via the property: '-vfx-cache-capacity'.

      Returns:
      the value of the cacheCapacity property
      See Also:

    • cacheCapacityProperty

      public io.github.palexdev.mfxcore.base.properties.styleable.StyleableIntegerProperty cacheCapacityProperty()

      Specifies the maximum number of cells the cache can contain at any time. Excess will not be added to the queue and disposed immediately.

      Can be set in CSS via the property: '-vfx-cache-capacity'.

      Returns:
      the cacheCapacity property
      See Also:

    • setCacheCapacity

      public void setCacheCapacity(int cacheCapacity)
      Sets the value of the cacheCapacity property.
      Property description:

      Specifies the maximum number of cells the cache can contain at any time. Excess will not be added to the queue and disposed immediately.

      Can be set in CSS via the property: '-vfx-cache-capacity'.

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

    • getClassCssMetaData

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

    • getControlCssMetaData

      protected List<javafx.css.CssMetaData<? extends javafx.css.Styleable, ?>> getControlCssMetaData()
      Overrides:
      getControlCssMetaData in class javafx.scene.control.Control

    • getCache

      protected VFXCellsCache<T,C> getCache()
      Returns:
      the cache instance used by this container

    • cacheSize

      public int cacheSize()
      Delegate for VFXCellsCache.size().

    • itemsProperty

      public javafx.beans.property.ListProperty<T> itemsProperty()
      Description copied from interface: VFXContainer

      Specifies the ObservableList used to store the items.

      We use a ListProperty because it offers many commodities such as both the size and emptiness of the list as observable properties, as well as the possibility of adding an InvalidationListener that will both inform about changes of the property and in the list.

      Specified by:
      itemsProperty in interface VFXContainer<T>
      Returns:
      the items property
      See Also:

    • getCellFactory

      public CellFactory<T,C> getCellFactory()
      Description copied from interface: WithCellFactory
      Specifies the wrapper class CellFactory for the cell factory function
      Specified by:
      getCellFactory in interface WithCellFactory<T, C extends VFXCell<T>>

    • getHelper

      public VFXListHelper<T,C> getHelper()
      Gets the value of the helper property.
      Property description:
      Specifies the instance of the VFXListHelper built by the helperFactoryProperty().
      Returns:
      the value of the helper property
      See Also:

    • helperProperty

      public javafx.beans.property.ReadOnlyObjectProperty<VFXListHelper<T,C>> helperProperty()
      Specifies the instance of the VFXListHelper built by the helperFactoryProperty().
      Returns:
      the helper property
      See Also:

    • setHelper

      protected void setHelper(VFXListHelper<T,C> helper)
      Sets the value of the helper property.
      Property description:
      Specifies the instance of the VFXListHelper built by the helperFactoryProperty().
      Parameters:
      helper - the value for the helper property
      See Also:

    • getHelperFactory

      public Function<javafx.geometry.Orientation, VFXListHelper<T,C>> getHelperFactory()
      Gets the value of the helperFactory property.
      Property description:
      Specifies the function used to build a VFXListHelper instance depending on the container's orientation.
      Returns:
      the value of the helperFactory property
      See Also:

    • helperFactoryProperty

      public io.github.palexdev.mfxcore.base.properties.functional.FunctionProperty<javafx.geometry.Orientation, VFXListHelper<T,C>> helperFactoryProperty()
      Specifies the function used to build a VFXListHelper instance depending on the container's orientation.
      Returns:
      the helperFactory property
      See Also:

    • setHelperFactory

      public void setHelperFactory(Function<javafx.geometry.Orientation, VFXListHelper<T,C>> helperFactory)
      Sets the value of the helperFactory property.
      Property description:
      Specifies the function used to build a VFXListHelper instance depending on the container's orientation.
      Parameters:
      helperFactory - the value for the helperFactory property
      See Also:

    • vPosProperty

      public javafx.beans.property.DoubleProperty vPosProperty()

      Specifies the container's vertical position.

      In case the orientation is set to Orientation.VERTICAL, this is to be considered a 'virtual' position, as the container will never reach unreasonably high values for performance reasons. See VFXListHelper.VerticalHelper to understand how virtual scroll is handled.

      Specified by:
      vPosProperty in interface VFXContainer<T>
      Returns:
      the vPos property
      See Also:

    • hPosProperty

      public javafx.beans.property.DoubleProperty hPosProperty()

      Specifies the container's horizontal position.

      In case the orientation is set to Orientation.HORIZONTAL, this is to be considered a 'virtual' position, as the container will never reach unreasonably high values for performance reasons. See VFXListHelper.HorizontalHelper to understand how virtual scroll is handled.

      Specified by:
      hPosProperty in interface VFXContainer<T>
      Returns:
      the hPos property
      See Also:

    • getState

      public VFXListState<T,C> getState()
      Gets the value of the state property.
      Property description:
      Specifies the container's current state. The state carries useful information such as the range of displayed items and the cells ordered by index, or by item (not ordered).
      Returns:
      the value of the state property
      See Also:

    • stateProperty

      public javafx.beans.property.ReadOnlyObjectProperty<VFXListState<T,C>> stateProperty()
      Specifies the container's current state. The state carries useful information such as the range of displayed items and the cells ordered by index, or by item (not ordered).
      Returns:
      the state property
      See Also:

    • setState

      protected void setState(VFXListState<T,C> state)
      Sets the value of the state property.
      Property description:
      Specifies the container's current state. The state carries useful information such as the range of displayed items and the cells ordered by index, or by item (not ordered).
      Parameters:
      state - the value for the state 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 javafx.beans.property.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:

    • context

      public VFXContext<T> context()
      Specified by:
      context in interface VFXContainer<T>
      Returns:
      the VFXContext object that carries the virtualized container's instance and additional external services that may be needed/used by the cells.