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

[Ajit Ghaisas]

On Fri, 13 Jan 2023 12:32:53 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.

Thanks @andy-goryachev-oracle, @kevinrushforth and @nlisker for your review. My responses are inline -

> After thinking about it further, I agree with Andy. Having a bulleted list of what to avoid, and a code sample of the right way to do it, seems best.

I am convinced that we should avoid writing out the non-recommended code snippet in documentation. I will replace it with bulleted list as suggested.


> Instead of repeating this in every class, maybe writing it once in Cell and linking to it from these classes will be better?

@kevinrushforth and I did think about this suggestion before deciding to put the warning explicitly in each of the virtualized controls. Each of `ListView`, `TreeView`, `TableView` and `TreeTableView` control documentation has a section about "Customizing Visuals" which has a link to `Cell` documentation.
- The documentation for `Cell` already has an example of custom cell factory and also a bulleted list of key design goals.
Despite this we see multiple occurrences of `Node`s being put directly in the item list of virtualized controls. Hence, it was decided to replicate the explicit warning similar to the one we already have in the documentation of ComboBox.
- I feel it is better to have an example of custom factory specific to each of the virtualized controls which we cannot put in generic `Cell` documentation.

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

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