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

[Kevin Rushforth]

On Fri, 13 Jan 2023 16:39:37 GMT, Andy Goryachev <angorya 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.
>
> modules/javafx.controls/src/main/java/javafx/scene/control/ListView.java line 196:
> 
>> 194:  * <p> This example has an anonymous custom {@code ListCell} class in the custom cell factory.
>> 195:  * Note that the Rectangle (Node) object needs to be created in the custom {@code ListCell} class
>> 196:  * or in it's constructor and updated/used in it's updateItem method.
> 
> Do we *really* need a code sample to emphasize the fact that Nodes should not be a part of the data model?  
> Would it be better to create a bulleted list which briefly, but succinctly describes the rules that should be followed by the developer?
> Having said that, there is a certain benefit of having a code sample as it simplifies writing code via copy-paste.

I do think having a code sample of the best practices is helpful in this case, given how frequently we see anti-patterns.

> modules/javafx.controls/src/main/java/javafx/scene/control/TreeTableView.java line 295:
> 
>> 293:  * given cell and update them on demand using the data stored in the item for that cell.
>> 294:  *
>> 295:  * <p>For example, rather than use the following code:
> 
> perhaps instead of dedicating space to incorrect code, we should provide a correct code block only, emphasizing the fact that the data model must not contain Nodes, in text?

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.

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

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