Merge pull request #1170 from Textualize/new-tree

New Tree Control

Author: willmcgugan

CHANGELOG.md

@@ -1,11 +1,22 @@
 # Change Log
 
-
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+
+## [0.6.0] - Unreleased
+
+### Added
+
+- Added "inherited bindings" -- BINDINGS classvar will be merged with base classes, unless inherit_bindings is set to False
+- Added `Tree` widget which replaces `TreeControl`.
+
+### Changed
+
+- Rebuilt `DirectoryTree` with new `Tree` control.
+
 ## [0.5.0] - 2022-11-20
 
 ### Added

docs/api/directory_tree.md

@@ -0,0 +1 @@
+::: textual.widgets.DirectoryTree

docs/api/tree.md

@@ -0,0 +1 @@
+::: textual.widgets.Tree

docs/api/tree_node.md

@@ -0,0 +1 @@
+::: textual.widgets.TreeNode

docs/examples/widgets/directory_tree.py

@@ -0,0 +1,12 @@
+from textual.app import App, ComposeResult
+from textual.widgets import DirectoryTree
+
+
+class DirectoryTreeApp(App):
+    def compose(self) -> ComposeResult:
+        yield DirectoryTree("./")
+
+
+if __name__ == "__main__":
+    app = DirectoryTreeApp()
+    app.run()

docs/examples/widgets/tree.py

@@ -0,0 +1,18 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Tree
+
+
+class TreeApp(App):
+    def compose(self) -> ComposeResult:
+        tree: Tree = Tree("Dune")
+        tree.root.expand()
+        characters = tree.root.add("Characters", expand=True)
+        characters.add_leaf("Paul")
+        characters.add_leaf("Jessica")
+        characters.add_leaf("Channi")
+        yield tree
+
+
+if __name__ == "__main__":
+    app = TreeApp()
+    app.run()

docs/widgets/directory_tree.md

@@ -0,0 +1,43 @@
+# DirectoryTree
+
+A tree control to navigate the contents of your filesystem.
+
+- [x] Focusable
+- [ ] Container
+
+
+## Example
+
+The example below creates a simple tree to navigate the current working directory.
+
+```python
+--8<-- "docs/examples/widgets/directory_tree.py"
+```
+
+## Messages
+
+### FileSelected
+
+The `DirectoryTree.FileSelected` message is sent when the user selects a file in the tree
+
+- [x] Bubbles
+
+#### Attributes
+
+| attribute | type  | purpose           |
+| --------- | ----- | ----------------- |
+| `path`    | `str` | Path of the file. |
+
+## Reactive Attributes
+
+| Name          | Type   | Default | Description                                     |
+| ------------- | ------ | ------- | ----------------------------------------------- |
+| `show_root`   | `bool` | `True`  | Show the root node.                             |
+| `show_guides` | `bool` | `True`  | Show guide lines between levels.                |
+| `guide_depth` | `int`  | `4`     | Amount of indentation between parent and child. |
+
+
+## See Also
+
+* [Tree][textual.widgets.DirectoryTree] code reference
+* [Tree][textual.widgets.Tree] code reference

docs/widgets/tree.md

@@ -0,0 +1,80 @@
+# Tree
+
+A tree control widget.
+
+- [x] Focusable
+- [ ] Container
+
+
+## Example
+
+The example below creates a simple tree.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/tree.py"}
+    ```
+
+=== "tree.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/tree.py"
+    ```
+
+A each tree widget has a "root" attribute which is an instance of a [TreeNode][textual.widgets.TreeNode]. Call [add()][textual.widgets.TreeNode.add] or [add_leaf()][textual.widgets.TreeNode.add_leaf] to add new nodes underneath the root. Both these methods return a TreeNode for the child, so you can add more levels.
+
+
+## Reactive Attributes
+
+| Name          | Type   | Default | Description                                     |
+| ------------- | ------ | ------- | ----------------------------------------------- |
+| `show_root`   | `bool` | `True`  | Show the root node.                             |
+| `show_guides` | `bool` | `True`  | Show guide lines between levels.                |
+| `guide_depth` | `int`  | `4`     | Amount of indentation between parent and child. |
+
+
+
+## Messages
+
+### NodeSelected
+
+The `Tree.NodeSelected` message is sent when the user selects a tree node.
+
+
+#### Attributes
+
+| attribute | type                                 | purpose        |
+| --------- | ------------------------------------ | -------------- |
+| `node`    | [TreeNode][textual.widgets.TreeNode] | Selected node. |
+
+
+### NodeExpanded
+
+The `Tree.NodeExpanded` message is sent when the user expands a node in the tree.
+
+#### Attributes
+
+| attribute | type                                 | purpose        |
+| --------- | ------------------------------------ | -------------- |
+| `node`    | [TreeNode][textual.widgets.TreeNode] | Expanded node. |
+
+
+### NodeCollapsed
+
+
+The `Tree.NodeCollapsed` message is sent when the user expands a node in the tree.
+
+
+#### Attributes
+
+| attribute | type                                 | purpose         |
+| --------- | ------------------------------------ | --------------- |
+| `node`    | [TreeNode][textual.widgets.TreeNode] | Collapsed node. |
+
+
+
+
+## See Also
+
+* [Tree][textual.widgets.Tree] code reference
+* [TreeNode][textual.widgets.TreeNode] code reference

docs/widgets/tree_control.md

@@ -3,22 +3,19 @@ Screen {
 }
 
 #tree-view {
-    display: none;
+    display: none; 
     scrollbar-gutter: stable;
-    width: auto;
+    overflow: auto;    
+    width: auto;    
+    height: 100%;            
+    dock: left;       
 }
 
 CodeBrowser.-show-tree #tree-view {
-    display: block;
-    dock: left;
-    height: 100%;            
+    display: block;        
     max-width: 50%;
-    background: #151C25;    
 }
 
-DirectoryTree {
-    padding-right: 1;   
-}
 
 #code-view {
     overflow: auto scroll;