Struct DirectoryTree 

pub struct DirectoryTree { /* private fields */ }

The directory-tree widget state.

Owns UI state only — which folders are open, what has loaded, the active filter, and the selection set. It never creates, deletes, renames, moves, or writes anything on disk; filesystem operations belong to the application.

Implementations

impl DirectoryTree

pub fn on_toggled(&mut self, path: &Path) -> Option<ScanRequest>

React to an expand/collapse gesture on path.

Returns Some(request) exactly when a scan must be executed — the slow-path expansion of an unloaded directory. All other cases mutate (or ignore) in memory and return None:

• A — path is a file or not in the tree: no-op.
• B — expanded directory: collapse. The generation is not bumped, so an in-flight scan for this subtree stays valid; its result will merge into the collapsed (cached) node silently.
• C — collapsed and already loaded: fast-path expand, no I/O.
• D — collapsed and unloaded: bump the generation and request a scan; or, beyond max_depth, mark loaded-empty instead. If the path is in prefetching_paths, the user-initiated scan supersedes the in-flight prefetch (S8.7).

pub fn on_loaded(&mut self, payload: LoadPayload) -> LoadedOutcome

Merge a completed scan.

A payload is accepted iff its generation strictly equals the tree’s current counter (the counter wraps, so ordering comparisons would be meaningless). Stale payloads — and payloads for paths no longer in the tree — are discarded silently, leaving the state bit-identical.

On acceptance the node is rebuilt and, if prefetch is enabled and this was a user-initiated scan (path not in prefetching_paths), up to config.prefetch_per_parent follow-up ScanRequests are returned in LoadedOutcome::prefetch_requests (S8.2). Completions of prefetch scans never trigger further waves (S8.3).

impl DirectoryTree

pub fn on_drag_msg(&mut self, msg: DragMsg) -> DragOutcome

React to a drag-and-drop gesture message.

impl DirectoryTree

pub fn on_selected(&mut self, path: &Path, _is_dir: bool, mode: SelectionMode)

React to a selection gesture on path.

impl DirectoryTree

pub fn new(root_path: impl Into<PathBuf>) -> DirectoryTree

Mount a tree at root_path. The root node is created eagerly and is never removed or replaced; loading it still requires the first expansion gesture.

pub fn with_filter(self, filter: DisplayFilter) -> DirectoryTree

Builder: set the initial display filter.

pub fn with_max_depth(self, max_depth: u32) -> DirectoryTree

Builder: cap the load depth (components below the root; 0 means only the root’s direct children are ever loaded).

pub fn root(&self) -> &TreeNode

The root node. Always present.

pub fn config(&self) -> &TreeConfig

Current configuration.

pub fn filter(&self) -> DisplayFilter

Current display filter.

pub fn generation(&self) -> u32

Current generation counter (diagnostics and tests).

pub fn cache(&self) -> &TreeCache

Raw scan results accepted so far.

pub fn find(&self, path: &Path) -> Option<&TreeNode>

Find the node for path, if it is currently in the tree.

pub fn depth_of(&self, path: &Path) -> Option<u32>

Depth of path below the root in components; None if path is not the root or under it. The root itself is depth 0.

pub fn set_filter(&mut self, filter: DisplayFilter)

Switch the display filter, re-deriving every loaded node’s child list from the cache. Instant; issues no I/O and does not bump the generation. Expansion and loaded state survive (children are path-matched against the previous node graph). Selection flags are re-synced so that paths hidden by the new filter remain selected but their nodes’ is_selected reflects reality once visible again (S2.6 / S6.4).

pub fn visible_rows(&self) -> Vec<(&TreeNode, u32)>

The ordered list of rows currently drawn: a depth-first pre-order walk visiting the root and, beneath every directory that is expanded and loaded, its (already filter-derived) children.

The single source of draw order — the view, keyboard navigation, and range selection all consume this list, so they never diverge.

pub fn expand_blocking(&mut self, path: &Path) -> Option<LoadedOutcome>

Synchronously expand path: run DirectoryTree::on_toggled, execute any produced scan on the current thread, and merge.

Returns None when no scan was needed (fast-path expand, collapse, no-op) and Some(outcome) when a scan ran. This is the port of upstream’s __test_expand_blocking: it lets the specification suite — and quick scripts — bypass all async infrastructure. GUI code should use on_toggled with a worker instead.

pub fn selected_paths(&self) -> &[PathBuf]

The full insertion-ordered selection set (S6.x).

pub fn selected_path(&self) -> Option<&Path>

The single-select view: the most recently touched path (S3.3).

Returns None before any selection gesture. This is not the last element of selected_paths; it is active_path, which the component renders with the distinct “active” style.

pub fn is_selected(&self, path: &Path) -> bool

true iff path is in the selection set.

This is the authoritative query; prefer it over reading node.is_selected, which is a derived view hint.

pub fn with_prefetch_limit(self, n: u32) -> DirectoryTree

Builder: enable prefetch — after each user-initiated scan, speculatively scan up to n direct folder-children (S8.2). 0 disables prefetch.

pub fn with_prefetch_skip( self, skip: impl IntoIterator<Item = impl Into<String>>, ) -> DirectoryTree

Builder: replace the prefetch skip list (S8.5).

Entries are compared ASCII case-insensitively against each candidate child’s basename. Defaults to crate::config::DEFAULT_PREFETCH_SKIP.

pub fn prefetching_paths(&self) -> &HashSet<PathBuf>

Paths for which a speculative prefetch scan is currently in flight.

pub fn search_query(&self) -> Option<&str>

The active search query, or None when search is inactive.

pub fn search_state(&self) -> Option<&SearchState>

The active search state (query, visible paths, match count), or None when search is inactive.

pub fn search_match_count(&self) -> usize

Number of direct basename matches (S9.8). Use this for “N results” displays; ancestor rows shown for context are excluded.

pub fn set_search_query(&mut self, query: &str)

Activate or update the incremental search filter (S9.1–S9.9).

An empty string clears the search (S9.4). Search never triggers I/O — it filters only the already-loaded node graph (S9.9).

pub fn clear_search(&mut self)

Clear the active search and return to normal tree view.

Equivalent to set_search_query("") (S9.4).

pub fn drag_state(&self) -> Option<&DragState>

The active drag session, or None when no drag is in progress.

Trait Implementations

impl Clone for DirectoryTree

fn clone(&self) -> DirectoryTree

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DirectoryTree

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for DirectoryTree

fn eq(&self, other: &DirectoryTree) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for DirectoryTree