1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
use std::collections::HashSet;
use ratatui::style::Style;
use ratatui::text::Text;
/// One item inside a [`Tree`](crate::Tree).
///
/// Can have zero or more `children`.
///
/// # Identifier
///
/// The generic argument `Identifier` is used to keep the state like the currently selected or opened [`TreeItem`s](Item) in the [`TreeState`](crate::TreeState).
///
/// It needs to be unique among its siblings but can be used again on parent or child [`TreeItem`s](Item).
/// A common example would be a filename which has to be unique in its directory while it can exist in another.
///
/// The `text` can be different from its `identifier`.
/// To repeat the filename analogy: File browsers sometimes hide file extensions.
/// The filename `main.rs` is the identifier while its shown as `main`.
/// Two files `main.rs` and `main.toml` can exist in the same directory and can both be displayed as `main` but their identifier is different.
///
/// Just like every file in a file system can be uniquely identified with its file and directory names each [`TreeItem`](Item) in a [`Tree`](crate::Tree) can be with these identifiers.
/// As an example the following two identifiers describe the main file in a Rust cargo project: `vec!["src", "main.rs"]`.
///
/// The identifier does not need to be a `String` and is therefore generic.
/// Until version 0.14 this crate used `usize` and indices.
/// This might still be perfect for your use case.
///
/// # Example
///
/// ```
/// # use tui_tree_widget::TreeItem;
/// let a = TreeItem::new_leaf("l", "Leaf");
/// let b = TreeItem::new("r", "Root", vec![a])?;
/// # Ok::<(), std::io::Error>(())
/// ```
#[derive(Debug, Clone)]
pub struct Item<'a, Identifier> {
pub(super) identifier: Identifier,
pub(super) text: Text<'a>,
pub(super) style: Style,
pub(super) children: Vec<Item<'a, Identifier>>,
}
impl<'a, Identifier> Item<'a, Identifier>
where
Identifier: Clone + PartialEq + Eq + core::hash::Hash,
{
/// Create a new `TreeItem` without children.
#[must_use]
pub fn new_leaf<T>(identifier: Identifier, text: T) -> Self
where
T: Into<Text<'a>>,
{
Self {
identifier,
text: text.into(),
style: Style::new(),
children: Vec::new(),
}
}
/// Create a new `TreeItem` with children.
///
/// # Errors
///
/// Errors when there are duplicate identifiers in the children.
pub fn new<T>(
identifier: Identifier,
text: T,
children: Vec<Item<'a, Identifier>>,
) -> std::io::Result<Self>
where
T: Into<Text<'a>>,
{
let identifiers = children
.iter()
.map(|item| &item.identifier)
.collect::<HashSet<_>>();
if identifiers.len() != children.len() {
return Err(std::io::Error::new(
std::io::ErrorKind::AlreadyExists,
"The children contain duplicate identifiers",
));
}
Ok(Self {
identifier,
text: text.into(),
style: Style::new(),
children,
})
}
#[must_use]
pub fn children(&self) -> &[Item<Identifier>] {
&self.children
}
/// Get a reference to a child by index.
#[must_use]
pub fn child(&self, index: usize) -> Option<&Self> {
self.children.get(index)
}
/// Get a mutable reference to a child by index.
///
/// When you choose to change the `identifier` the [`TreeState`](crate::TreeState) might not work as expected afterwards.
#[must_use]
pub fn child_mut(&mut self, index: usize) -> Option<&mut Self> {
self.children.get_mut(index)
}
#[must_use]
pub fn height(&self) -> usize {
self.text.height()
}
#[must_use]
pub const fn style(mut self, style: Style) -> Self {
self.style = style;
self
}
/// Add a child to the `TreeItem`.
///
/// # Errors
///
/// Errors when the `identifier` of the `child` already exists in the children.
pub fn add_child(&mut self, child: Item<'a, Identifier>) -> std::io::Result<()> {
let existing = self
.children
.iter()
.map(|item| &item.identifier)
.collect::<HashSet<_>>();
if existing.contains(&child.identifier) {
return Err(std::io::Error::new(
std::io::ErrorKind::AlreadyExists,
"identifier already exists in the children",
));
}
self.children.push(child);
Ok(())
}
}
#[test]
#[should_panic = "duplicate identifiers"]
fn tree_item_new_errors_with_duplicate_identifiers() {
let item = Item::new_leaf("same", "text");
let another = item.clone();
Item::new("root", "Root", vec![item, another]).unwrap();
}
#[test]
#[should_panic = "identifier already exists"]
fn tree_item_add_child_errors_with_duplicate_identifiers() {
let item = Item::new_leaf("same", "text");
let another = item.clone();
let mut root = Item::new("root", "Root", vec![item]).unwrap();
root.add_child(another).unwrap();
}