[jfx20] RFR: 8290863: Update the documentation of Virtualized controls to include the best practice of not using Nodes directly in the item list [v4]

[Nir Lisker]

On Fri, 20 Jan 2023 11:16:04 GMT, Ajit Ghaisas <aghaisas at openjdk.org> wrote:

>> This PR adds a warning about inserting Nodes directly into the virtualized containers such as ListView, TreeView, TableView and TreeTableView. It also adds code snippets showing the recommended pattern of using a custom cell factory for each of the virtualized control.
>
> Ajit Ghaisas has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Additional review fixes

Left some minor inline comments that are relevant for the other classes here as well.

Looking at the current `ListView` docs, I think it's not very informative. The main paragraph talks about generics in Java:

> A ListView is able to have its generic type set to represent the type of data in the backing model. Doing this has the benefit of making various methods in the ListView, as well as the supporting classes (mentioned below), type-safe. In addition, making use of the generic type supports substantially simplified development of applications making use of ListView, as all modern IDEs are able to auto-complete far more successfully with the additional type information.

I think that all of that should be removed, and your explanation on how to actually use `ListView` should be added instead. While it's tied to the "Customizing Visuals" section, the points of `ListView` is for it contain data/model instances which are interpreted as a visual `Node` by the `ListView`, so it should belong in the main paragraph.

I can come up with a redistribution of the paragraphs if you want and if you don't consider this out of scope.

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

PR: https://git.openjdk.org/jfx/pull/995