Tree view demos do not use the TreeSource object - intentional or bug?

[drernie]

Is your feature request related to a problem? Please describe.
I am trying to learn the proper way to use TreeView.

The test code seems to use the TreeSource object:

• src/core/tests/widgets/test_tree.py
• src/core/tests/sources/test_tree_source.py

But the examples all just use Source:

• examples/tree
• examples/tree_source

Is this because TreeSource was added recently, and the examples just haven't been updated?

Describe the solution you'd like

If so, then I would love to see the examples rewritten (and happy to do it myself).

Describe alternatives you've considered
If I'm totally misunderstanding the point of TreeSource, that would be good to know, and perhaps document more clearly.

Additional context
Add any other context or screenshots about the feature request here.

[freakboy3742]

(Converted from an issue to a discussion because there wasn't anything clearly actionable without further discussion)

The trees demos aren't recent - they should be reasonably accurate renditions of what is possible with the Tree widget.

The "Tree" example doesn't reference "Source" anywhere in the code. It uses a TreeSource implicitly - Toga will convert a "tree like" set of primitives structure into a TreeSource. So I'm not sure what you're referring to when you say the Tree demo "uses Source"

The TreeSource example uses a subclass of Source, mixed with Node; it is, as the comment at the top of the example says, a less toy example. It's (intentionally) demonstrating that it is possible to feed a Tree with a custom source, provided you implement the required API. You don't need to use a Tree Source literally - you only need to provide a source that implements the TreeSource API (which is itself a superset of Source).

I won't disagree that we need a lot more than just an example project - we need a lot more explanatory documentation on how a TreeSource works. However, as far as I can make out, there's nothing fundamentally wrong with the tree ortree_source demos - they're just complex examples that need a lot more elaboration.

[drernie]

That’s fair. Let me rephrase that as a positive offer: would there be interest in me contributing an example that demonstrates explicit use of the TreeSource object and protocol?

…

Sent from my iPhone

On Jul 6, 2022, at 22:25, Russell Keith-Magee ***@***.***> wrote:  (Converted from an issue to a discussion because there wasn't anything clearly actionable without further discussion) The trees demos aren't recent - they should be reasonably accurate renditions of what is possible with the Tree widget. The "Tree" example doesn't reference "Source" anywhere in the code. It uses a TreeSource implicitly - Toga will convert a "tree like" set of primitives structure into a TreeSource. So I'm not sure what you're referring to when you say the Tree demo "uses Source" The TreeSource example uses a subclass of Source, mixed with Node; it is, as the comment at the top of the example says, a less toy example. It's (intentionally) demonstrating that it is possible to feed a Tree with a custom source, provided you implement the required API. You don't need to use a Tree Source literally - you only need to provide a source that implements the TreeSource API (which is itself a superset of Source). I won't disagree that we need a lot more than just an example project - we need a lot more explanatory documentation on how a TreeSource works. However, as far as I can make out, there's nothing fundamentally wrong with the tree ortree_source demos - they're just complex examples that need a lot more elaboration. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.

[freakboy3742]

I guess I'd say that another example isn't really what is needed - what is needed is an explanatory tutorial/topic document describing the idea behind a TreeSource, how the default one works, and how you can define a custom TreeSource. That document may benefit from having another example - but I'd suggest we need to start with the prose, not the example.

[drernie]

Ah. For my use case, I’m actually concerned about a different issue: how do I map a static data structure onto the *existing* TreeSource object. Specifically, I want to use TreeView to browse YAML (and JSON) documents — and perhaps even edit them. This seems like it should be straightforward (and useful) to do, but it wasn’t obvious how. Is that just me, or might it be of interest to the larger community?

…

Sent from my iPhone

On Jul 6, 2022, at 23:11, Russell Keith-Magee ***@***.***> wrote:  I guess I'd say that another example isn't really what is needed - what is needed is an explanatory tutorial/topic document describing the idea behind a TreeSource, how the default one works, and how you can define a custom TreeSource. That document may benefit from having another example - but I'd suggest we need to start with the prose, not the example. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.

[freakboy3742]

So... I'm clearly missing something, because the request you've made and the example you've given aren't really consistent.

The existing Tree example does show you how to map a static data structure. The original static data is defined in bee_movies; there's then a bunch of tree.node.append() calls to manipulate the tree data. We could possibly modify the example to provide a better example of passing in an initial static data structure (e.g., setting up the initial year node structure and some initial children); but, as I've said before, I think the issue is that we're missing documentation, not a completely new example.

However, your practical use case... isn't going to be best served by a static data structure. You're not going to be able to "just" throw a JSON document at a TreeView. At the very least, you're going to need to write an intermediate layer that will convert the JSON document structure into Tree-like data that the TreeView can interpret. This essentially means duplicating your JSON document into a parallel data structure that reproduces all the content of the JSON document. If you're planning to edit the document, you're essentially going to need to write a "serialization/deserialization" layer to convert from JSON to Tree format and back again.

The better solution will be to write a custom Tree Source that interprets the JSON/YAML data structure as a tree structure in-memory - which is what the TreeSource demo is doing. The TreeSource demo is providing a representation of the file system; but if you replace the filesystem inspection calls with calls that interpret the JSON data structure, you'll have an interface for viewing/editing a JSON document.

Again - the pieces are there in the examples... but what is missing is the description of why the examples are there, and how to adapt those examples to a specific use case.

[drernie]

Ah! So in the static case, it might work to convert YAML into a TreeSource. But in general, It sounds like I need a “TreeSourceController” that can work directly with my “model object” to implement the (currently implicit) TreeSourceProtocol. Let me ponder that some more and see if I can come back with a coherent proposal. Thanks!

…

Sent from my iPhone

On Jul 7, 2022, at 17:13, Russell Keith-Magee ***@***.***> wrote:  So... I'm clearly missing something, because the request you've made and the example you've given aren't really consistent. The existing Tree example does show you how to map a static data structure. The original static data is defined in bee_movies; there's then a bunch of tree.node.append() calls to manipulate the tree data. We could possibly modify the example to provide a better example of passing in an initial static data structure (e.g., setting up the initial year node structure and some initial children); but, as I've said before, I think the issue is that we're missing documentation, not a completely new example. However, your practical use case... isn't going to be best served by a static data structure. You're not going to be able to "just" throw a JSON document at a TreeView. At the very least, you're going to need to write an intermediate layer that will convert the JSON document structure into Tree-like data that the TreeView can interpret. This essentially means duplicating your JSON document into a parallel data structure that reproduces all the content of the JSON document. If you're planning to edit the document, you're essentially going to need to write a "serialization/deserialization" layer to convert from JSON to Tree format and back again. The better solution will be to write a custom Tree Source that interprets the JSON/YAML data structure as a tree structure in-memory - which is what the TreeSource demo is doing. The TreeSource demo is providing a representation of the file system; but if you replace the filesystem inspection calls with calls that interpret the JSON data structure, you'll have an interface for viewing/editing a JSON document. Again - the pieces are there in the examples... but what is missing is the description of why the examples are there, and how to adapt those examples to a specific use case. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.