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 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
use std::collections::HashSet;
use ratatui::layout::{Position, Rect};
use crate::flatten::{flatten, Flattened};
use crate::tree_item::TreeItem;
/// Keeps the state of what is currently selected and what was opened in a [`Tree`](crate::Tree).
///
/// The generic argument `Identifier` is used to keep the state like the currently selected or opened [`TreeItem`]s in the [`TreeState`].
/// For more information see [`TreeItem`].
///
/// # Example
///
/// ```
/// # use tui_tree_widget::TreeState;
/// type Identifier = usize;
///
/// let mut state = TreeState::<Identifier>::default();
/// ```
#[must_use]
#[derive(Debug, Default)]
pub struct TreeState<Identifier> {
pub(super) offset: usize,
pub(super) opened: HashSet<Vec<Identifier>>,
pub(super) selected: Vec<Identifier>,
pub(super) ensure_selected_in_view_on_next_render: bool,
pub(super) last_area: Rect,
pub(super) last_biggest_index: usize,
/// All identifiers open on last render
pub(super) last_identifiers: Vec<Vec<Identifier>>,
/// Identifier rendered at `y` on last render
pub(super) last_rendered_identifiers: Vec<(u16, Vec<Identifier>)>,
}
impl<Identifier> TreeState<Identifier>
where
Identifier: Clone + PartialEq + Eq + core::hash::Hash,
{
#[must_use]
pub const fn get_offset(&self) -> usize {
self.offset
}
#[must_use]
#[deprecated = "Use self.opened()"]
pub fn get_all_opened(&self) -> Vec<Vec<Identifier>> {
self.opened.iter().cloned().collect()
}
#[must_use]
pub const fn opened(&self) -> &HashSet<Vec<Identifier>> {
&self.opened
}
#[must_use]
pub fn selected(&self) -> &[Identifier] {
&self.selected
}
/// Get a flat list of all currently viewable (including by scrolling) [`TreeItem`]s with this `TreeState`.
#[must_use]
pub fn flatten<'text>(
&self,
items: &'text [TreeItem<'text, Identifier>],
) -> Vec<Flattened<'text, Identifier>> {
flatten(&self.opened, items, &[])
}
/// Selects the given identifier.
///
/// Returns `true` when the selection changed.
///
/// Clear the selection by passing an empty identifier vector:
///
/// ```rust
/// # use tui_tree_widget::TreeState;
/// # let mut state = TreeState::<usize>::default();
/// state.select(Vec::new());
/// ```
pub fn select(&mut self, identifier: Vec<Identifier>) -> bool {
self.ensure_selected_in_view_on_next_render = true;
let changed = self.selected != identifier;
self.selected = identifier;
changed
}
/// Open a tree node.
/// Returns `true` when it was closed and has been opened.
/// Returns `false` when it was already open.
pub fn open(&mut self, identifier: Vec<Identifier>) -> bool {
if identifier.is_empty() {
false
} else {
self.opened.insert(identifier)
}
}
/// Close a tree node.
/// Returns `true` when it was open and has been closed.
/// Returns `false` when it was already closed.
pub fn close(&mut self, identifier: &[Identifier]) -> bool {
self.opened.remove(identifier)
}
/// Toggles a tree node open/close state.
/// When it is currently open, then [`close`](Self::close) is called. Otherwise [`open`](Self::open).
///
/// Returns `true` when a node is opened / closed.
/// As toggle always changes something, this only returns `false` when an empty identifier is given.
pub fn toggle(&mut self, identifier: Vec<Identifier>) -> bool {
if identifier.is_empty() {
false
} else if self.opened.contains(&identifier) {
self.close(&identifier)
} else {
self.open(identifier)
}
}
/// Toggles the currently selected tree node open/close state.
/// See also [`toggle`](Self::toggle)
///
/// Returns `true` when a node is opened / closed.
/// As toggle always changes something, this only returns `false` when nothing is selected.
pub fn toggle_selected(&mut self) -> bool {
if self.selected.is_empty() {
return false;
}
self.ensure_selected_in_view_on_next_render = true;
// Reimplement self.close because of multiple different borrows
let was_open = self.opened.remove(&self.selected);
if was_open {
return true;
}
self.open(self.selected.clone())
}
/// Closes all open nodes.
///
/// Returns `true` when any node was closed.
pub fn close_all(&mut self) -> bool {
if self.opened.is_empty() {
false
} else {
self.opened.clear();
true
}
}
/// Select the first node.
///
/// Returns `true` when the selection changed.
pub fn select_first(&mut self) -> bool {
let identifier = self.last_identifiers.first().cloned().unwrap_or_default();
self.select(identifier)
}
/// Select the last node.
///
/// Returns `true` when the selection changed.
pub fn select_last(&mut self) -> bool {
let new_identifier = self.last_identifiers.last().cloned().unwrap_or_default();
self.select(new_identifier)
}
/// Select the node on the given index.
///
/// Returns `true` when the selection changed.
///
/// This can be useful for mouse clicks.
#[deprecated = "Prefer self.click_at or self.rendered_at as visible index is hard to predict with height != 1"]
pub fn select_visible_index(&mut self, new_index: usize) -> bool {
let new_index = new_index.min(self.last_biggest_index);
let new_identifier = self
.last_identifiers
.get(new_index)
.cloned()
.unwrap_or_default();
self.select(new_identifier)
}
/// Move the current selection with the direction/amount by the given function.
///
/// Returns `true` when the selection changed.
///
/// # Example
///
/// ```
/// # use tui_tree_widget::TreeState;
/// # type Identifier = usize;
/// # let mut state = TreeState::<Identifier>::default();
/// // Move the selection one down
/// state.select_visible_relative(|current| {
/// // When nothing is currently selected, select index 0
/// // Otherwise select current + 1 (without panicing)
/// current.map_or(0, |current| current.saturating_add(1))
/// });
/// ```
///
/// For more examples take a look into the source code of [`key_up`](Self::key_up) or [`key_down`](Self::key_down).
/// They are implemented with this method.
#[deprecated = "renamed to select_relative"]
pub fn select_visible_relative<F>(&mut self, change_function: F) -> bool
where
F: FnOnce(Option<usize>) -> usize,
{
let identifiers = &self.last_identifiers;
let current_identifier = &self.selected;
let current_index = identifiers
.iter()
.position(|identifier| identifier == current_identifier);
let new_index = change_function(current_index).min(self.last_biggest_index);
let new_identifier = identifiers.get(new_index).cloned().unwrap_or_default();
self.select(new_identifier)
}
/// Move the current selection with the direction/amount by the given function.
///
/// Returns `true` when the selection changed.
///
/// # Example
///
/// ```
/// # use tui_tree_widget::TreeState;
/// # type Identifier = usize;
/// # let mut state = TreeState::<Identifier>::default();
/// // Move the selection one down
/// state.select_relative(|current| {
/// // When nothing is currently selected, select index 0
/// // Otherwise select current + 1 (without panicing)
/// current.map_or(0, |current| current.saturating_add(1))
/// });
/// ```
///
/// For more examples take a look into the source code of [`key_up`](Self::key_up) or [`key_down`](Self::key_down).
/// They are implemented with this method.
pub fn select_relative<F>(&mut self, change_function: F) -> bool
where
F: FnOnce(Option<usize>) -> usize,
{
let identifiers = &self.last_identifiers;
let current_identifier = &self.selected;
let current_index = identifiers
.iter()
.position(|identifier| identifier == current_identifier);
let new_index = change_function(current_index).min(self.last_biggest_index);
let new_identifier = identifiers.get(new_index).cloned().unwrap_or_default();
self.select(new_identifier)
}
/// Get the identifier that was rendered for the given position on last render.
#[must_use]
pub fn rendered_at(&self, position: Position) -> Option<&[Identifier]> {
if !self.last_area.contains(position) {
return None;
}
self.last_rendered_identifiers
.iter()
.rev()
.find(|(y, _)| position.y >= *y)
.map(|(_, identifier)| identifier.as_ref())
}
/// Select what was rendered at the given position on last render.
/// When it is already selected, toggle it.
///
/// Returns `true` when the state changed.
/// Returns `false` when there was nothing at the given position.
pub fn click_at(&mut self, position: Position) -> bool {
if let Some(identifier) = self.rendered_at(position) {
if identifier == self.selected {
self.toggle_selected()
} else {
self.select(identifier.to_vec())
}
} else {
false
}
}
/// Ensure the selected [`TreeItem`] is in view on next render
pub fn scroll_selected_into_view(&mut self) {
self.ensure_selected_in_view_on_next_render = true;
}
/// Scroll the specified amount of lines up
///
/// Returns `true` when the scroll position changed.
/// Returns `false` when the scrolling has reached the top.
pub fn scroll_up(&mut self, lines: usize) -> bool {
let before = self.offset;
self.offset = self.offset.saturating_sub(lines);
before != self.offset
}
/// Scroll the specified amount of lines down
///
/// Returns `true` when the scroll position changed.
/// Returns `false` when the scrolling has reached the last [`TreeItem`].
pub fn scroll_down(&mut self, lines: usize) -> bool {
let before = self.offset;
self.offset = self
.offset
.saturating_add(lines)
.min(self.last_biggest_index);
before != self.offset
}
/// Handles the up arrow key.
/// Moves up in the current depth or to its parent.
///
/// Returns `true` when the selection changed.
pub fn key_up(&mut self) -> bool {
self.select_relative(|current| {
// When nothing is selected, fall back to end
current.map_or(usize::MAX, |current| current.saturating_sub(1))
})
}
/// Handles the down arrow key.
/// Moves down in the current depth or into a child node.
///
/// Returns `true` when the selection changed.
pub fn key_down(&mut self) -> bool {
self.select_relative(|current| {
// When nothing is selected, fall back to start
current.map_or(0, |current| current.saturating_add(1))
})
}
/// Handles the left arrow key.
/// Closes the currently selected or moves to its parent.
///
/// Returns `true` when the selection or the open state changed.
pub fn key_left(&mut self) -> bool {
self.ensure_selected_in_view_on_next_render = true;
// Reimplement self.close because of multiple different borrows
let mut changed = self.opened.remove(&self.selected);
if !changed {
// Select the parent by removing the leaf from selection
let popped = self.selected.pop();
changed = popped.is_some();
}
changed
}
/// Handles the right arrow key.
/// Opens the currently selected.
///
/// Returns `true` when it was closed and has been opened.
/// Returns `false` when it was already open or nothing being selected.
pub fn key_right(&mut self) -> bool {
if self.selected.is_empty() {
false
} else {
self.ensure_selected_in_view_on_next_render = true;
self.open(self.selected.clone())
}
}
}