Struct FileTree 

pub struct FileTree { /* private fields */ }

Lazy-loading file explorer tree.

Implementations

impl FileTree

pub fn new(root: impl Into<Arc<str>>) -> Self

Create a new file tree rooted at root.

pub fn entry_source(self, source: FileTreeEntrySource) -> Self

Set the source used to enumerate directory entries.

FileTreeEntrySource::Local is the default. With a provided source, missing expanded directories render the loading row and are requested through FileTree::on_entry_request.

pub fn show_hidden(self, show_hidden: bool) -> Self

Toggle hidden entries (dotfiles).

pub fn max_entries_per_dir(self, max_entries: usize) -> Self

Set max number of children loaded per directory.

pub fn show_icons(self, show_icons: bool) -> Self

Toggle icon rendering.

pub fn icon_style(self, style: FileIconStyle) -> Self

Set icon style for file tree items.

pub fn icon_palette(self, palette: FileIconPalette) -> Self

Set the color palette for file icons.

pub fn icon_override( self, pattern: impl Into<Arc<str>>, icon: impl Into<Arc<str>>, color: Option<Color>, ) -> Self

Add a custom icon override for a file extension or name.

The pattern can be a file extension (e.g., “rs”, “md”) or a full filename (e.g., “README.md”). The icon will be used for files matching this pattern.

pub fn show_arrows(self, show: bool) -> Self

Toggle expansion arrows before directories.

pub fn indent_style(self, style: IndentStyle) -> Self

Set style of indentation guides.

pub fn indent_guide_style(self, style: Style) -> Self

Set style for indent guides.

pub fn indent_guide_start_depth(self, depth: usize) -> Self

Set the first non-root depth that renders indentation guides (default 1).

pub fn indent_width(self, width: u16) -> Self

Set indentation cells per hierarchy level (default 2).

pub fn directory_icon(self, icon: impl Into<Arc<str>>) -> Self

Set directory icon.

pub fn opened_directory_icon(self, icon: impl Into<Arc<str>>) -> Self

Set “opened directory” icon.

pub fn file_icon(self, icon: impl Into<Arc<str>>) -> Self

Set regular file icon.

pub fn symlink_icon(self, icon: impl Into<Arc<str>>) -> Self

Set symlink icon.

pub fn other_icon(self, icon: impl Into<Arc<str>>) -> Self

Set “other type” icon.

pub fn directory_label_style(self, style: Style) -> Self

Set the label style for directory rows.

pub fn file_label_style(self, style: Style) -> Self

Set the label style for regular file rows.

pub fn path_style( self, path: impl Into<Arc<str>>, style: FileTreeItemStyle, ) -> Self

Set item decorations for an exact path under the effective root.

pub fn path_styles( self, styles: impl IntoIterator<Item = (impl Into<Arc<str>>, FileTreeItemStyle)>, ) -> Self

Set item decorations for exact paths under the effective root.

pub fn loading_label(self, label: impl Into<Arc<str>>) -> Self

Set loading row label.

pub fn error_prefix(self, prefix: impl Into<Arc<str>>) -> Self

Set load-error prefix.

pub fn width(self, width: Length) -> Self

Set width.

pub fn height(self, height: Length) -> Self

Set height.

pub fn style(self, style: Style) -> Self

Set base style.

pub fn hover_style(self, style: Style) -> Self

Set hovered style.

pub fn extend_hover_style(self, style: Style) -> Self

Extend the themed hovered style.

pub fn inherit_hover_style(self) -> Self

Inherit the themed hovered style.

pub fn hover_style_slot(self, slot: StyleSlot) -> Self

Set hover style slot directly for composite forwarding.

pub fn item_hover_style(self, style: Style) -> Self

Set hovered row style.

pub fn extend_item_hover_style(self, style: Style) -> Self

Extend the themed hovered row style.

pub fn inherit_item_hover_style(self) -> Self

Inherit the themed hovered row style.

pub fn item_hover_style_slot(self, slot: StyleSlot) -> Self

Set item-hover style slot directly for composite forwarding.

pub fn selection_style(self, style: Style) -> Self

Set selected row style.

pub fn extend_selection_style(self, style: Style) -> Self

Extend the themed selected row style.

pub fn inherit_selection_style(self) -> Self

Inherit the themed selected row style.

pub fn selection_style_slot(self, slot: StyleSlot) -> Self

Set selected row style slot directly for composite forwarding.

pub fn unfocused_selection_style(self, style: Style) -> Self

Set selected row style while the file tree is not focused.

pub fn extend_unfocused_selection_style(self, style: Style) -> Self

Extend the themed selected row style while the file tree is not focused.

pub fn inherit_unfocused_selection_style(self) -> Self

Inherit the themed selected row style while the file tree is not focused.

pub fn unfocused_selection_style_slot(self, slot: StyleSlot) -> Self

Set unfocused selected row style slot directly for composite forwarding.

pub fn selected(self, selected: usize) -> Self

Set the selected visible row index.

pub fn clear_selection(self, clear: bool) -> Self

Clear the selection highlight (no current row).

When true, this is authoritative over both the controlled selected prop and internal selection state. See crate::widgets::Tree::clear_selection.

pub fn selected_path(self, path: impl Into<Arc<str>>) -> Self

Select a visible row by path.

The path may be absolute under the tree root or relative to it. Selection is a no-op when the normalized path is outside the root or is not present in the current visible projection.

pub fn reveal_path(self, path: impl Into<Arc<str>>) -> Self

Reveal a path by expanding/loading ancestor directories when possible.

The path may be absolute under the tree root or relative to it. Revealing is a no-op for paths outside the root, paths hidden by show_hidden(false), unreadable directories, capped directory entries, and paths absent from the active all-files/changed-only projection.

pub fn select_path(self, path: impl Into<Arc<str>>) -> Self

Reveal and select a path, forcing scroll to the row when it is visible.

This combines reveal_path and selected_path behavior. With controlled expanded_paths, the path can only be revealed when the controlled expansion set (plus this reveal request for rendering) makes the ancestors available to load.

pub fn force_scroll_to_selected(self, force: bool) -> Self

Force scroll to make the selected item visible on next render.

pub fn expanded_paths( self, paths: impl IntoIterator<Item = impl Into<Arc<str>>>, ) -> Self

Control expanded directory paths.

pub fn initial_expanded_paths( self, paths: impl IntoIterator<Item = impl Into<Arc<str>>>, ) -> Self

Seed expansion state the tree then owns, so an application can restore what was expanded before the tree was unmounted or re-rooted.

Paths may be absolute under the tree root or relative to it; paths outside the root are ignored. They are applied when the tree mounts and whenever the root changes, and never again — later edits to this set do not disturb expansion the user has since changed. Pair it with Self::on_toggle to record what to seed next time.

Ancestors are deliberately not expanded along with a seeded path: collapsing a directory leaves what is inside it expanded, so seeding a descendant must not reopen the parent the user closed. A seeded path becomes visible when its parent is expanded again.

Ignored when Self::expanded_paths controls expansion, which is authoritative on its own.

pub fn selection_symbol(self, symbol: Option<impl Into<Arc<str>>>) -> Self

Set selected row prefix symbol.

pub fn selection_symbol_style(self, style: Option<Style>) -> Self

Set selected row prefix style.

pub fn unfocused_selection_symbol_style(self, style: Option<Style>) -> Self

Set selected row prefix style while the file tree is not focused.

pub fn scrollbar(self, scrollbar: bool) -> Self

Toggle scrollbar.

pub fn scrollbar_config(self, config: ScrollbarConfig) -> Self

Set scrollbar configuration.

pub fn scroll_keys(self, keys: ScrollKeymap) -> Self

Configure keyboard scrolling bindings.

pub fn scroll_wheel(self, enabled: bool) -> Self

Enable mouse wheel scrolling.

pub fn show_scroll_indicators(self, show: bool) -> Self

Toggle hidden-row indicators (N more).

pub fn scroll_indicator_style(self, style: Style) -> Self

Set hidden-row indicator style.

pub fn empty_text(self, text: impl Into<Arc<str>>) -> Self

Set empty-state text.

pub fn empty_text_style(self, style: Style) -> Self

Set empty-state style.

pub fn empty_text_padding(self, padding: impl Into<Padding>) -> Self

Set the inset around the empty-state text.

The tree’s own rows are flush with the surface because the root row starts the hierarchy there, but a placeholder is prose rather than a row, and applications usually align it with their other empty states instead. Defaults to none, which keeps it flush with the rows.

pub fn explorer(self, explorer: bool) -> Self

Toggle explorer filter input above the tree.

pub fn tree_focus_key(self, key: impl Into<Arc<str>>) -> Self

Set the key used to focus the tree inside this composite widget.

pub fn explorer_focus_key(self, key: impl Into<Arc<str>>) -> Self

Set the key used to focus the explorer input inside this composite widget.

pub fn explorer_placeholder(self, text: impl Into<Arc<str>>) -> Self

Set explorer placeholder text.

pub fn explorer_prefix(self, prefix: impl Into<Arc<str>>) -> Self

Set explorer input prefix text.

pub fn explorer_input_border(self, border: bool) -> Self

Toggle explorer input border.

pub fn explorer_input_border_style(self, style: BorderStyle) -> Self

Set explorer input border style.

pub fn explorer_input_padding(self, padding: impl Into<Padding>) -> Self

Set explorer input padding.

pub fn explorer_input_style(self, style: Style) -> Self

Set explorer input style.

pub fn explorer_input_focus_style(self, style: Style) -> Self

Set explorer input style when focused.

pub fn extend_explorer_input_focus_style(self, style: Style) -> Self

Extend the themed explorer input focus style.

pub fn inherit_explorer_input_focus_style(self) -> Self

Inherit the themed explorer input focus style.

pub fn explorer_input_focus_style_slot(self, slot: StyleSlot) -> Self

Set explorer input focus style slot directly for composite forwarding.

pub fn explorer_input_focus_content_style(self, style: Style) -> Self

Set focused explorer input content text style.

pub fn explorer_placeholder_style(self, style: Style) -> Self

Set explorer placeholder style.

pub fn explorer_focus_placeholder_style(self, style: Style) -> Self

Set explorer placeholder style when focused.

pub fn explorer_match_style(self, style: Style) -> Self

Set explorer search match highlight style.

pub fn explorer_divider(self, show: bool) -> Self

Toggle divider below the explorer input.

pub fn explorer_divider_join_frame(self, join: bool) -> Self

Toggle frame-join behavior for explorer divider.

pub fn explorer_divider_char(self, ch: char) -> Self

Set divider character for explorer divider.

pub fn explorer_divider_style(self, style: Style) -> Self

Set explorer divider style.

pub fn on_explorer_focus( self, cb: Callback<FileTreeExplorerFocusOrigin>, ) -> Self

Set the callback fired when the explorer input receives focus.

pub fn on_explorer_blur(self, cb: Callback<()>) -> Self

Set the callback fired when the explorer input loses focus.

pub fn on_explorer_escape(self, cb: Callback<()>) -> Self

Set the callback fired when Escape or an outside tree/divider click leaves an explorer focused directly by pointer.

Explorer focus entered from the tree with / returns to the tree instead and does not emit this callback. Without a callback, pointer-entered explorer focus also returns to the tree.

pub fn activate_on_click(self, activate_on_click: bool) -> Self

Set tree activation behavior for mouse clicks.

pub fn focusable(self, focusable: bool) -> Self

Control focusability.

pub fn tab_stop(self, tab_stop: bool) -> Self

Control whether the file tree participates in Tab / Shift+Tab traversal.

pub fn on_focus(self, cb: Callback<()>) -> Self

Set the callback fired when the file tree gains focus.

pub fn on_blur(self, cb: Callback<()>) -> Self

Set the callback fired when the file tree loses focus.

pub fn on_entry_request(self, cb: Callback<FileTreeEntryRequest>) -> Self

Set the callback fired when a provided entry source needs a directory listing.

The callback should only enqueue application work. Perform remote or other blocking I/O in a crate::Command, then rebuild the widget with a matching FileTreeDirectoryListing in FileTreeEntrySource::Provided.

pub fn keymap(self, keymap: TreeKeymap) -> Self

Configure expand/collapse keymap.

pub fn git_status(self, enabled: bool) -> Self

Toggle Git status decorations.

pub fn highlight_changed_labels(self, enabled: bool) -> Self

Toggle applying change status styles to file and directory labels.

Status indicators remain styled independently. The default is false, so file names keep their regular file-kind styling while dirty state is shown in the right-aligned metadata.

pub fn git_view(self, view: FileTreeGitView) -> Self

Set the changed-file display mode using the Git-compatible alias.

pub fn change_source(self, source: FileTreeChangeSource) -> Self

Set the source used for changed-file decorations and changed-only projection.

pub fn change_view(self, view: FileTreeChangeView) -> Self

Set the source-agnostic changed-file display mode.

pub fn git_changed_only(self, enabled: bool) -> Self

Toggle changed-only mode using the Git-compatible builder name.

pub fn show_diff_stats(self, enabled: bool) -> Self

Toggle diff statistics decorations for any change source.

pub fn git_diff_stats(self, enabled: bool) -> Self

Toggle diff statistics decorations using the Git-compatible builder name.

pub fn git_icon_style(self, style: GitIconStyle) -> Self

Set icon style for Git status indicators.

pub fn refresh_git_status(self) -> Self

Request an immediate Git status refresh.

Call this when building the widget in response to a user action.

pub fn git_refresh_token(self, token: u64) -> Self

Set explicit refresh token for Git status loading.

When the token changes, the component triggers a new background refresh.

pub fn git_marker_modified(self, marker: impl Into<Arc<str>>) -> Self

Set marker for Modified git status.

pub fn git_marker_added(self, marker: impl Into<Arc<str>>) -> Self

Set marker for Added git status.

pub fn git_marker_deleted(self, marker: impl Into<Arc<str>>) -> Self

Set marker for Deleted git status.

pub fn git_marker_renamed(self, marker: impl Into<Arc<str>>) -> Self

Set marker for Renamed git status.

pub fn git_marker_untracked(self, marker: impl Into<Arc<str>>) -> Self

Set marker for Untracked git status.

pub fn git_marker_conflicted(self, marker: impl Into<Arc<str>>) -> Self

Set marker for Conflicted git status.

pub fn git_style_modified(self, style: Style) -> Self

Set style for Modified git status marker.

pub fn git_style_added(self, style: Style) -> Self

Set style for Added git status marker.

pub fn git_style_deleted(self, style: Style) -> Self

Set style for Deleted git status marker.

pub fn git_style_renamed(self, style: Style) -> Self

Set style for Renamed git status marker.

pub fn git_style_untracked(self, style: Style) -> Self

Set style for Untracked git status marker.

pub fn git_style_conflicted(self, style: Style) -> Self

Set style for Conflicted git status marker.

pub fn change_suffix_style(self, style: Style) -> Self

Set a source-agnostic style patch for right-aligned change metadata.

pub fn git_suffix_style(self, style: Style) -> Self

Set a Git-compatible style patch for right-aligned change metadata.

pub fn change_suffix_priority(self, priority: FileTreeSuffixPriority) -> Self

Set whether labels or right-aligned change metadata win when rows are narrow.

pub fn git_suffix_priority(self, priority: FileTreeSuffixPriority) -> Self

Set Git-compatible truncation priority for right-aligned change metadata.

pub fn on_select(self, cb: Callback<FileTreeEvent>) -> Self

Set selection callback.

pub fn on_activate(self, cb: Callback<FileTreeEvent>) -> Self

Fired when a row is activated (Enter, or click when activate_on_click is true).

pub fn on_toggle(self, cb: Callback<FileTreeToggleEvent>) -> Self

Set expand/collapse callback.

Trait Implementations

impl Clone for FileTree

fn clone(&self) -> FileTree

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl From<FileTree> for Element

fn from(file_tree: FileTree) -> Self

Converts to this type from the input type.