{"id":21749053,"url":"https://github.com/veeso/tui-realm-treeview","last_synced_at":"2025-04-09T13:07:24.270Z","repository":{"id":49959495,"uuid":"373500614","full_name":"veeso/tui-realm-treeview","owner":"veeso","description":"🌲 treeview component for tui-realm 👑","archived":false,"fork":false,"pushed_at":"2024-10-13T17:58:53.000Z","size":1518,"stargazers_count":23,"open_issues_count":6,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-02T10:39:22.792Z","etag":null,"topics":["treeview-component","tui","tui-realm","tui-realm-treeview","tui-rs"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/veeso.png","metadata":{"funding":{"ko_fi":"veeso"},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-03T12:33:20.000Z","updated_at":"2025-03-27T20:50:33.000Z","dependencies_parsed_at":"2025-01-02T16:11:38.384Z","dependency_job_id":"6a38c9d9-e27e-489e-98d4-dc88d15d5bd0","html_url":"https://github.com/veeso/tui-realm-treeview","commit_stats":{"total_commits":58,"total_committers":3,"mean_commits":"19.333333333333332","dds":0.03448275862068961,"last_synced_commit":"8643267a4961e6d8acf02a89328bb4bb982a4a04"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veeso%2Ftui-realm-treeview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veeso%2Ftui-realm-treeview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veeso%2Ftui-realm-treeview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veeso%2Ftui-realm-treeview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/veeso","download_url":"https://codeload.github.com/veeso/tui-realm-treeview/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248045231,"owners_count":21038553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["treeview-component","tui","tui-realm","tui-realm-treeview","tui-rs"],"created_at":"2024-11-26T08:16:13.738Z","updated_at":"2025-04-09T13:07:24.252Z","avatar_url":"https://github.com/veeso.png","language":"Rust","funding_links":["https://ko-fi.com/veeso","https://www.paypal.me/chrisintin"],"categories":["Rust"],"sub_categories":[],"readme":"# tui-realm-treeview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"/docs/images/tui-realm-treeview.svg\" width=\"256\" height=\"256\" alt=\"logo\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e~ Treeview component for tui-realm ~\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/veeso/orange-trees\" target=\"_blank\"\u003eorange trees\u003c/a\u003e\n  ·\n  \u003ca href=\"https://github.com/veeso/tui-realm\" target=\"_blank\"\u003etui-realm\u003c/a\u003e\n  ·\n  \u003ca href=\"https://docs.rs/tui-realm-treeview\" target=\"_blank\"\u003eDocumentation\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003eDeveloped by \u003ca href=\"https://veeso.github.io/\" target=\"_blank\"\u003e@veeso\u003c/a\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003eCurrent version: 2.0.0 (13/10/2024)\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\n    \u003e\u003cimg\n      src=\"https://img.shields.io/badge/License-MIT-teal.svg\"\n      alt=\"License-MIT\"\n  /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/veeso/tui-realm-treeview/stargazers\"\n    \u003e\u003cimg\n      src=\"https://img.shields.io/github/stars/veeso/tui-realm-treeview.svg\"\n      alt=\"Repo stars\"\n  /\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/tui-realm-treeview\"\n    \u003e\u003cimg\n      src=\"https://img.shields.io/crates/d/tui-realm-treeview.svg\"\n      alt=\"Downloads counter\"\n  /\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/tui-realm-treeview\"\n    \u003e\u003cimg\n      src=\"https://img.shields.io/crates/v/tui-realm-treeview.svg\"\n      alt=\"Latest version\"\n  /\u003e\u003c/a\u003e\n  \u003ca href=\"https://ko-fi.com/veeso\"\u003e\n    \u003cimg\n      src=\"https://img.shields.io/badge/donate-ko--fi-red\"\n      alt=\"Ko-fi\"\n  /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/veeso/tui-realm-treeview/actions\"\n    \u003e\u003cimg\n      src=\"https://github.com/veeso/tui-realm-treeview/workflows/Build/badge.svg\"\n      alt=\"CI\"\n  /\u003e\u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/github/veeso/tui-realm-treeview\"\n    \u003e\u003cimg\n      src=\"https://coveralls.io/repos/github/veeso/tui-realm-treeview/badge.svg\"\n      alt=\"Coveralls\"\n  /\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.rs/tui-realm-treeview\"\n    \u003e\u003cimg\n      src=\"https://docs.rs/tui-realm-treeview/badge.svg\"\n      alt=\"Docs\"\n  /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n- [tui-realm-treeview](#tui-realm-treeview)\n  - [About tui-realm-treeview 🌲](#about-tui-realm-treeview-)\n  - [Get started 🏁](#get-started-)\n    - [Add tui-realm-treeview to your Cargo.toml 🦀](#add-tui-realm-treeview-to-your-cargotoml-)\n    - [Examples 📋](#examples-)\n    - [About performance](#about-performance)\n  - [Component API](#component-api)\n    - [Updating the tree](#updating-the-tree)\n      - [Remounting the component](#remounting-the-component)\n      - [Updating the tree from the \"on\" method](#updating-the-tree-from-the-on-method)\n  - [Documentation 📚](#documentation-)\n  - [Contributing and issues 🤝🏻](#contributing-and-issues-)\n  - [Changelog ⏳](#changelog-)\n  - [Support the developer ☕](#support-the-developer-)\n  - [License 📃](#license-)\n\n---\n\n## About tui-realm-treeview 🌲\n\ntui-realm-treeview is an implementation of a **treeview component** for [tui-realm](https://github.com/veeso/tui-realm).\nIt uses the [Orange trees](https://github.com/veeso/orange-trees) engine for implementing trees.\n\n![Demo](docs/images/demo.gif)\n\n---\n\n## Get started 🏁\n\n### Add tui-realm-treeview to your Cargo.toml 🦀\n\n```toml\ntui-realm-treeview = \"2\"\n```\n\nOr if you don't use **Crossterm**, define the backend as you do with tui-realm:\n\n```toml\ntui-realm-treeview = { version = \"2\", default-features = false, features = [ \"termion\" ] }\n```\n\n### Examples 📋\n\nView how to use the treeview-component following the [example](examples/demo.rs). The example contains a simple file explorer using a tree view, the depth is set to 3.\n\n```sh\ncargo run --example demo\n```\n\n- Press `ENTER` to expand the selected directory\n- Press `BACKSPACE` to go to upper directory\n- Move up and down with `UP/DOWN` arrow keys\n- Advance by up to 6 entries with `PGUP/PGDOWN`\n- Open directories with `RIGHT`\n- Close directories with `LEFT`\n- Change window between input field and treeview with `TAB`\n- Press `ESC` to quit\n\n### About performance\n\n❗ If you were a tui-realm-treeview 0.x user, I'm glad to announce that this new version of the library is much more\nfaster and reliable than the older version. That's because now I'm using a new engine for trees and I'm no more\nrelying on the tui_tree_widget, which required me to convert the tree into another kind of structure which wasn't\nreally compatible with the tree data structure. For this new library I've re-implemented everything, including the widget, to be 100% compatible with the orange-trees engine.\n\nIn this library there is a consistent use of recursion, and since rust is not functional, this might lead to stack overflows when dealing with huge trees.\n\n---\n\n## Component API\n\n**Commands**:\n\n| Cmd                       | Result            | Behaviour                                            |\n|---------------------------|-------------------|------------------------------------------------------|\n| `Custom($TREE_CMD_CLOSE)` | `None`            | Close selected node                                  |\n| `Custom($TREE_CMD_OPEN)`  | `None`            | Open selected node                                   |\n| `GoTo(Begin)`             | `Changed \\| None` | Move cursor to the top of the current tree node      |\n| `GoTo(End)`               | `Changed \\| None` | Move cursor to the bottom of the current tree node   |\n| `Move(Down)`              | `Changed \\| None` | Go to next element                                   |\n| `Move(Up)`                | `Changed \\| None` | Go to previous element                               |\n| `Scroll(Down)`            | `Changed \\| None` | Move cursor down by defined max steps or end of node |\n| `Scroll(Up)`              | `Changed \\| None` | Move cursor up by defined max steps or begin of node |\n| `Submit`                  | `Submit`          | Just returns submit result with current state        |\n\n**State**: the state returned is a `One(String)` containing the id of the selected node. If no node is selected `None` is returned.\n\n**Properties**:\n\n- `Background(Color)`: background color. The background color will be used as background for unselected entry, but will be used as foreground for the selected entry when focus is true\n- `Borders(Borders)`: set borders properties for component\n- `Custom($TREE_IDENT_SIZE, Size)`: Set space to render for each each depth level\n- `Custom($TREE_INITIAL_NODE, String)`: Select initial node in the tree. This option has priority over `keep_state`\n- `Custom($TREE_PRESERVE_STATE, Flag)`: If true, the selected entry will be kept after an update of the tree (obviously if the entry still exists in the tree).\n- `FocusStyle(Style)`: inactive style\n- `Foreground(Color)`: foreground color. The foreground will be used as foreground for the selected item, when focus is false, otherwise as background\n- `HighlightedColor(Color)`: The provided color will be used to highlight the selected node. `Foreground` will be used if unset.\n- `HighlightedStr(String)`: The provided string will be displayed on the left side of the selected entry in the tree\n- `ScrollStep(Length)`: Defines the maximum amount of rows to scroll\n- `TextProps(TextModifiers)`: set text modifiers\n- `Title(Title)`: Set box title\n\n### Updating the tree\n\nThe tree in this component is not inside the `props`, but is a member of the `TreeView` mock component structure.\nIn order to update and work with the tree you've got basically two ways to do this.\n\n#### Remounting the component\n\nIn situation where you need to update the tree on the update routine (as happens in the example), the best way to update the tree is to remount the component from scratch.\nIf you follow the example, you'll see I've implemented the constructor for my treeview component as follows:\n\n```rust\nimpl FsTree {\n    pub fn new(tree: Tree, initial_node: Option\u003cString\u003e) -\u003e Self {\n        // Preserve initial node if exists\n        let initial_node = match initial_node {\n            Some(id) if tree.root().query(\u0026id).is_some() =\u003e id,\n            _ =\u003e tree.root().id().to_string(),\n        };\n        FsTree {\n            component: TreeView::default()\n                .foreground(Color::Reset)\n                .borders(\n                    Borders::default()\n                        .color(Color::LightYellow)\n                        .modifiers(BorderType::Rounded),\n                )\n                .inactive(Style::default().fg(Color::Gray))\n                .indent_size(3)\n                .scroll_step(6)\n                .title(tree.root().id(), Alignment::Left)\n                .highlighted_color(Color::LightYellow)\n                .highlight_symbol(\"🦄\")\n                .with_tree(tree)\n                .initial_node(initial_node),\n        }\n    }\n}\n```\n\nI always set the initial_node and the tree in the constructor. This implementation allows me to update the tree whenever I want without losing the current state.\n\n#### Updating the tree from the \"on\" method\n\nThis method is probably better than remounting, but it is not always possible to use this.\nWhen you implement `Component` for your treeview, you have a mutable reference to the component, and so here you can call these methods to operate on the tree:\n\n- `pub fn tree(\u0026self) -\u003e \u0026Tree`: returns a reference to the tree\n- `pub fn tree_mut(\u0026mut self) -\u003e \u0026mut Tree`: returns a mutable reference to the tree; which allows you to operate on it\n- `pub fn set_tree(\u0026mut self, tree: Tree)`: update the current tree with another\n- `pub fn tree_state(\u0026self) -\u003e \u0026TreeState`: get a reference to the current tree state. (See tree state docs)\n\nYou can access these methods from the `on()` method as said before. So these methods can be handy when you update the tree after a certain events or maybe even better, you can set the tree if you receive it from a `UserEvent` produced by a **Port**.\n\n---\n\n## Documentation 📚\n\nThe developer documentation can be found on Rust Docs at \u003chttps://docs.rs/tui-realm-treeview\u003e\n\n---\n\n## Contributing and issues 🤝🏻\n\nContributions, bug reports, new features and questions are welcome! 😉\nIf you have any question or concern, or you want to suggest a new feature, or you want just want to improve tui-realm, feel free to open an issue or a PR.\n\nPlease follow [our contributing guidelines](CONTRIBUTING.md)\n\n---\n\n## Changelog ⏳\n\nView tui-realm-treeview's changelog [HERE](CHANGELOG.md)\n\n---\n\n## Support the developer ☕\n\nIf you like tui-realm and you're grateful for the work I've done, please consider a little donation 🥳\n\nYou can make a donation with one of these platforms:\n\n[![ko-fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge\u0026logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/veeso)\n[![PayPal](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge\u0026logo=paypal\u0026logoColor=white)](https://www.paypal.me/chrisintin)\n\n---\n\n## License 📃\n\ntui-realm-treeview is licensed under the MIT license.\n\nYou can read the entire license [HERE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveeso%2Ftui-realm-treeview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fveeso%2Ftui-realm-treeview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveeso%2Ftui-realm-treeview/lists"}