Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/fxmisc/Flowless

Efficient VirtualFlow for JavaFX
https://github.com/fxmisc/Flowless

javafx viewport

Last synced: about 2 months ago
JSON representation

Efficient VirtualFlow for JavaFX

Host: GitHub
URL: https://github.com/fxmisc/Flowless
Owner: FXMisc
License: bsd-2-clause
Created: 2014-07-05T12:10:28.000Z (over 10 years ago)
Default Branch: master
Last Pushed: 2024-05-14T14:13:33.000Z (7 months ago)
Last Synced: 2024-06-15T04:41:14.081Z (6 months ago)
Topics: javafx, viewport
Language: Java
Homepage:
Size: 326 KB
Stars: 181
Watchers: 20
Forks: 38
Open Issues: 14
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

aboutfx - Flowless

README

        Flowless

========

Please note that as from version **0.6.5** Flowless requires Java 9 or newer.

Efficient VirtualFlow for JavaFX. VirtualFlow is a layout container that lays out _cells_ in a vertical or horizontal _flow_. The main feature of a _virtual_ flow is that only the currently visible cells are rendered in the scene. You may have a list of thousands of items, but only, say, 30 cells are rendered at any given time.

JavaFX has its own VirtualFlow, which is not part of the public API, but is used, for example, in the implementation of [ListView](https://openjfx.io/javadoc/23/javafx.controls/javafx/scene/control/ListView.html). It is, however, [not very efficient](https://bugs.openjdk.java.net/browse/JDK-8091726) when updating the viewport on items changed or scroll.

Here is a comparison of JavaFX's ListView vs. Flowless on a list of 80 items, 25 of which fit into the viewport.

|                                              | Flowless (# of cell creations / # of cell layouts) | JDK 8u40 ListView (# of `updateItem` calls / # of cell layouts) | JDK 16 ListView with fixed cell size (# of `updateItem` calls / # of cell layouts) |

|----------------------------------------------|:-----:|:-----:|:-----:|

| update an item in the viewport               |   1/1 | 1/1   | 1/1   |

| update an item outside the viewport          |   0/0 | 0/0   | 0/0   |

| delete an item in the middle of the viewport |   1/1 | 38/25 | 13/13 |

| add an item in the middle of the viewport    |   1/1 | 38/25 | 13/13 |

| scroll 5 items down                          |   5/5 | 5/5   | 5/5   |

| scroll 50 items down                         | 25/25 | 50/25 | 25/25 |

Here is the [source code](https://gist.github.com/Jugen/2d392fd72ebec9db3c5d2aca1f8f5eb5) of this mini-benchmark.

Use case for Flowless

---------------------

You will benefit from Flowless (compared to ListView) the most if you have many add/delete items occuring in the viewport and an expensive [updateItem](https://openjfx.io/javadoc/23/javafx.controls/javafx/scene/control/Cell.html#updateItem(T,boolean)) method.

Note, however, that Flowless is a low-level layout component and does not provide higher-level features like selection model or inline editing. One can, of course, implement those on top of Flowless.

Additional API

--------------

VirtualFlow in Flowless provides additional public API compared to ListView or VirtualFlow from JavaFX.

**Direct cell access** with [getCell(itemIndex)](https://fxmisc.github.io/flowless/javadoc/0.7.0/org/fxmisc/flowless/VirtualFlow.html#getCell-int-) and [getCellIfVisible(itemIndex)](https://fxmisc.github.io/flowless/javadoc/0.7.0/org/fxmisc/flowless/VirtualFlow.html#getCellIfVisible-int-) methods. This is useful for measurement purposes.

**List of currently visible cells** via [visibleCells()](https://fxmisc.github.io/flowless/javadoc/0.7.0/org/fxmisc/flowless/VirtualFlow.html#visibleCells--).

**Hit test** with the [hit(double x, double y)](https://fxmisc.github.io/flowless/javadoc/0.7.0/org/fxmisc/flowless/VirtualFlow.html#hit-double-double-) method that converts viewport coordinates into a cell index and coordinates relative to the cell, or indicates that the hit is before or beyond the cells.

**Navigate to a subregion of a cell** using the [show(itemIndex, region)](https://fxmisc.github.io/flowless/javadoc/0.7.0/org/fxmisc/flowless/VirtualFlow.html#show-int-javafx.geometry.Bounds-) method. This is a finer grained navigation than just the [show(itemIndex)](https://fxmisc.github.io/flowless/javadoc/0.7.0/org/fxmisc/flowless/VirtualFlow.html#show-int-) method.

**Scroll:** [scrollXBy(deltaX)](https://fxmisc.github.io/flowless/javadoc/0.7.0/org/fxmisc/flowless/VirtualFlow.html#scrollXBy-double-) and [scrollYBy(deltaY)](https://fxmisc.github.io/flowless/javadoc/0.7.0/org/fxmisc/flowless/VirtualFlow.html#scrollYBy-double-) methods.

**Gravity:** You can create VirtualFlow where cells stick to the bottom (vertical flow) or right (horizontal flow) when there are not enough items to fill the viewport.

Conceptual differences from ListView

------------------------------------

**Dumb cells.** This is the most important difference. For Flowless, cells are just [Node](https://openjfx.io/javadoc/23/javafx.graphics/javafx/scene/Node.html)s and don't encapsulate any logic regarding virtual flow. A cell does not even necessarily store the index of the item it is displaying. This allows VirtualFlow to have complete control over when the cells are created and/or updated.

**Cell reuse is opt-in,** not forced. Cells are not reused by default. A new cell is created for each item. This simplifies cell implementation and does not impair performance if reusing a cell would be about as expensive as creating a new one (i.e. `updateItem` would be expensive).

**No empty cells.** There are no _empty cells_ used to fill the viewport when there are too few items. A cell is either displaying an item, or is not displayed at all.

Assumptions about cells

-----------------------

As noted before, for the purposes of virtual flow in Flowless the cells are just `Node`s. You are not forced to inherit from `ListCell`. However, they are expected to behave according to the following rules:

* Cells of a vertical virtual flow should properly implement methods

  * `computeMinWidth(-1)`

  * `computePrefWidth(-1)`

  * `computePrefHeight(width)`

* Cells of a horizontal virtual flow should properly implement methods

  * `computeMinHeight(-1)`

  * `computePrefHeight(-1)`

  * `computePrefWidth(height)`

Include Flowless in your project

--------------------------------

#### Maven coordinates

| Group ID            | Artifact ID | Version |

| :---------:         | :---------: | :-----: |

| org.fxmisc.flowless | flowless    | 0.7.3   |

[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.fxmisc.flowless/flowless/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.fxmisc.flowless/flowless)

#### Gradle example

```groovy

dependencies {

    implementation group: 'org.fxmisc.flowless', name: 'flowless', version: '0.7.3'

}

```

#### Sbt example

```scala

libraryDependencies += "org.fxmisc.flowless" % "flowless" % "0.7.3"

```

#### Manual download

Download the [0.7.3 jar](https://github.com/FXMisc/Flowless/releases/tag/v0.7.3) and place it on your classpath.

Documentation

-------------

[Javadoc](https://fxmisc.github.io/flowless/javadoc/0.7.0/org/fxmisc/flowless/package-summary.html)