egui_arbor/lib.rs
1//! A flexible tree/outliner widget for [egui](https://github.com/emilk/egui).
2//!
3//! `egui-arbor` provides a customizable hierarchical tree view widget inspired by
4//! Blender's outliner, designed to integrate seamlessly with egui applications.
5//!
6//! # Features
7//!
8//! - **Hierarchical Tree View**: Display nested data structures with collections and entities
9//! - **Expand/Collapse**: Navigate through tree hierarchy with visual expand/collapse arrows
10//! - **Drag & Drop**: Reorder and reparent nodes with Before/After/Inside positioning
11//! - **Action Icons**: Built-in visibility, lock, and selection toggles with custom icon support
12//! - **Inline Editing**: Double-click to rename nodes with keyboard shortcuts
13//! - **Multi-Selection**: Select multiple nodes with Shift-click, Ctrl/Cmd-click, or box selection
14//! - **Customizable Styling**: Configure indentation, colors, icons, and spacing
15//! - **Trait-Based Integration**: Works with any data structure implementing [`OutlinerNode`]
16//! - **State Persistence**: Automatic state management via egui's memory system
17//! - **Tree Operations**: Built-in helpers for common tree manipulations (rename, remove, insert)
18//! - **Default Actions**: Ready-to-use [`OutlinerActions`] implementation with event logging
19//!
20//! # Multi-Selection
21//!
22//! The outliner supports multiple selection modes:
23//! - **Click**: Select a single node (clears other selections)
24//! - **Ctrl/Cmd-Click**: Toggle selection of a node without clearing others
25//! - **Shift-Click**: Select a range of nodes from the last selected to the clicked node
26//! - **Box Selection**: Click and drag in empty space to select multiple nodes with a selection box
27//! - Hold Ctrl/Cmd while box selecting to add to existing selection
28//!
29//! # Quick Start
30//!
31//! To use the outliner, you need to:
32//! 1. Implement [`OutlinerNode`] on your data structure
33//! 2. Optionally implement [`tree_ops::TreeOperations`] for tree manipulation helpers
34//! 3. Use [`default_actions::DefaultActions`] or implement [`OutlinerActions`] yourself
35//! 4. Create an [`Outliner`] and call its [`show`](Outliner::show) method
36//!
37//! # Example
38//!
39//! ```rust
40//! use egui_arbor::{Outliner, OutlinerNode, tree_ops::TreeOperations, default_actions::DefaultActions};
41//!
42//! // 1. Define your data structure
43//! #[derive(Clone)]
44//! struct TreeNode {
45//! id: u64,
46//! name: String,
47//! children: Vec<TreeNode>,
48//! }
49//!
50//! // 2. Implement OutlinerNode trait
51//! impl OutlinerNode for TreeNode {
52//! type Id = u64;
53//!
54//! fn id(&self) -> Self::Id { self.id }
55//! fn name(&self) -> &str { &self.name }
56//! fn is_collection(&self) -> bool { !self.children.is_empty() }
57//! fn children(&self) -> &[Self] { &self.children }
58//! fn children_mut(&mut self) -> &mut Vec<Self> { &mut self.children }
59//! }
60//!
61//! // 3. Get tree operations for free!
62//! impl TreeOperations for TreeNode {}
63//!
64//! // 4. Use in your egui code with default actions
65//! fn show_tree(ui: &mut egui::Ui, nodes: &[TreeNode], actions: &mut DefaultActions<u64>) {
66//! let response = Outliner::new("my_tree")
67//! .show(ui, nodes, actions);
68//!
69//! // Handle events
70//! if let Some(id) = response.selected() {
71//! println!("Selected node: {:?}", id);
72//! }
73//! }
74//! ```
75//!
76//! # Core Types
77//!
78//! - [`Outliner`] - The main widget for rendering hierarchical trees
79//! - [`OutlinerNode`] - Trait to implement on your data structures
80//! - [`OutlinerActions`] - Trait for handling user interactions
81//! - [`OutlinerResponse`] - Response type containing event information
82//! - [`OutlinerState`] - Persistent state for expansion and editing
83//! - [`Style`] - Visual styling configuration
84//! - [`DragDropState`] - State tracking for drag-drop operations
85//!
86//! # Helper Modules
87//!
88//! - [`tree_ops`] - Tree manipulation operations (rename, remove, insert)
89//! - [`default_actions`] - Ready-to-use actions implementation with state tracking
90//! - [`event_log`] - Event logging system for tracking user interactions
91//!
92//! # Optional Features
93//!
94//! - `serde` - Enable serialization support for state persistence
95
96pub mod default_actions;
97pub mod drag_drop;
98pub mod event_log;
99pub mod outliner;
100pub mod response;
101pub mod state;
102pub mod style;
103pub mod traits;
104pub mod tree_ops;
105
106// Re-export main types for convenience
107pub use drag_drop::{DragDropState, DragDropVisuals};
108pub use outliner::Outliner;
109pub use response::{DropEvent, OutlinerResponse};
110pub use state::{BoxSelectionState, OutlinerState};
111pub use style::{ExpandIconStyle, Style};
112pub use traits::{ActionIcon, DropPosition, IconType, OutlinerActions, OutlinerNode};