Home

Awesome

tui-realm-treeview

<p align="center"> <img src="/docs/images/tui-realm-treeview.svg" width="256" height="256" alt="logo" /> </p> <p align="center">~ Treeview component for tui-realm ~</p> <p align="center"> <a href="https://github.com/veeso/orange-trees" target="_blank">orange trees</a> ยท <a href="https://github.com/veeso/tui-realm" target="_blank">tui-realm</a> ยท <a href="https://docs.rs/tui-realm-treeview" target="_blank">Documentation</a> </p> <p align="center">Developed by <a href="https://veeso.github.io/" target="_blank">@veeso</a></p> <p align="center">Current version: 2.0.0 (13/10/2024)</p> <p align="center"> <a href="https://opensource.org/licenses/MIT" ><img src="https://img.shields.io/badge/License-MIT-teal.svg" alt="License-MIT" /></a> <a href="https://github.com/veeso/tui-realm-treeview/stargazers" ><img src="https://img.shields.io/github/stars/veeso/tui-realm-treeview.svg" alt="Repo stars" /></a> <a href="https://crates.io/crates/tui-realm-treeview" ><img src="https://img.shields.io/crates/d/tui-realm-treeview.svg" alt="Downloads counter" /></a> <a href="https://crates.io/crates/tui-realm-treeview" ><img src="https://img.shields.io/crates/v/tui-realm-treeview.svg" alt="Latest version" /></a> <a href="https://ko-fi.com/veeso"> <img src="https://img.shields.io/badge/donate-ko--fi-red" alt="Ko-fi" /></a> </p> <p align="center"> <a href="https://github.com/veeso/tui-realm-treeview/actions" ><img src="https://github.com/veeso/tui-realm-treeview/workflows/Build/badge.svg" alt="CI" /></a> <a href="https://coveralls.io/github/veeso/tui-realm-treeview" ><img src="https://coveralls.io/repos/github/veeso/tui-realm-treeview/badge.svg" alt="Coveralls" /></a> <a href="https://docs.rs/tui-realm-treeview" ><img src="https://docs.rs/tui-realm-treeview/badge.svg" alt="Docs" /></a> </p>

About tui-realm-treeview ๐ŸŒฒ

tui-realm-treeview is an implementation of a treeview component for tui-realm. It uses the Orange trees engine for implementing trees.

Demo


Get started ๐Ÿ

Add tui-realm-treeview to your Cargo.toml ๐Ÿฆ€

tui-realm-treeview = "2"

Or if you don't use Crossterm, define the backend as you do with tui-realm:

tui-realm-treeview = { version = "2", default-features = false, features = [ "termion" ] }

Examples ๐Ÿ“‹

View how to use the treeview-component following the example. The example contains a simple file explorer using a tree view, the depth is set to 3.

cargo run --example demo

About performance

โ— 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 faster and reliable than the older version. That's because now I'm using a new engine for trees and I'm no more relying on the tui_tree_widget, which required me to convert the tree into another kind of structure which wasn't really 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.

In 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.


Component API

Commands:

CmdResultBehaviour
Custom($TREE_CMD_CLOSE)NoneClose selected node
Custom($TREE_CMD_OPEN)NoneOpen selected node
GoTo(Begin)Changed | NoneMove cursor to the top of the current tree node
GoTo(End)Changed | NoneMove cursor to the bottom of the current tree node
Move(Down)Changed | NoneGo to next element
Move(Up)Changed | NoneGo to previous element
Scroll(Down)Changed | NoneMove cursor down by defined max steps or end of node
Scroll(Up)Changed | NoneMove cursor up by defined max steps or begin of node
SubmitSubmitJust returns submit result with current state

State: the state returned is a One(String) containing the id of the selected node. If no node is selected None is returned.

Properties:

Updating the tree

The tree in this component is not inside the props, but is a member of the TreeView mock component structure. In order to update and work with the tree you've got basically two ways to do this.

Remounting the component

In 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. If you follow the example, you'll see I've implemented the constructor for my treeview component as follows:

impl FsTree {
    pub fn new(tree: Tree, initial_node: Option<String>) -> Self {
        // Preserve initial node if exists
        let initial_node = match initial_node {
            Some(id) if tree.root().query(&id).is_some() => id,
            _ => tree.root().id().to_string(),
        };
        FsTree {
            component: TreeView::default()
                .foreground(Color::Reset)
                .borders(
                    Borders::default()
                        .color(Color::LightYellow)
                        .modifiers(BorderType::Rounded),
                )
                .inactive(Style::default().fg(Color::Gray))
                .indent_size(3)
                .scroll_step(6)
                .title(tree.root().id(), Alignment::Left)
                .highlighted_color(Color::LightYellow)
                .highlight_symbol("๐Ÿฆ„")
                .with_tree(tree)
                .initial_node(initial_node),
        }
    }
}

I 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.

Updating the tree from the "on" method

This method is probably better than remounting, but it is not always possible to use this. When 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:

You 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.


Documentation ๐Ÿ“š

The developer documentation can be found on Rust Docs at https://docs.rs/tui-realm-treeview


Contributing and issues ๐Ÿค๐Ÿป

Contributions, bug reports, new features and questions are welcome! ๐Ÿ˜‰ If 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.

Please follow our contributing guidelines


Changelog โณ

View tui-realm-treeview's changelog HERE


Support the developer โ˜•

If you like tui-realm and you're grateful for the work I've done, please consider a little donation ๐Ÿฅณ

You can make a donation with one of these platforms:

ko-fi PayPal


License ๐Ÿ“ƒ

tui-realm-treeview is licensed under the MIT license.

You can read the entire license HERE