Guide API
Skip to main content

FileList

Struct FileList 

Source
pub struct FileList { /* private fields */ }
Expand description

The file-listing pane of the file dialog. A concrete SortedSearch (hence ListViewer) over a name-sorted Vec<SearchRec> (== a FileCollection’s contents), with two columns and incremental type-to-search.

§Structural shape

This is a direct SortedSearch impl — the same shape as SortedListBox, NOT DirListBox (which is a plain ListViewer). It therefore wires handle_event→sorted_handle_event and cursor_request→sorted_cursor, inherits the default is_selected (the focused item is the selected one), and contributes no dialog data (value() == None).

§The search key

search is the one method whose comparator is non-obvious: it must compare via search_rec_compare over raw SearchRecs, not over get_text (which appends / to dir names and would mis-order). The key carries an attr of FA_DIREC when the shift_state holds KB_SHIFT or the typed prefix starts with ., routing the search into the directory section of the collection. That routing exists only in search_rec_compare’s file/dir ordering — hence this is a per-impl search, not the shared get_text one.

§Native paths

get_text appends / to directory names; the listing is case-sensitive (the DOS-only upper-casing of the search key has no Linux counterpart).

§Owner broadcasts

On every focus change the list broadcasts a “file focused” command (subject = the focused entry), and on double-click/Enter it broadcasts a “file double-clicked” command. Both are wired via the on_focus_changed hook (ListViewer::on_focus_changed) and the select_item override; the focused record is resolved through the pump’s ResolveFocusedFile broker — the broadcast itself is payload-less and carries a resolvable source id.

§Intentional simplifications

  • No dialog data (value() == None).
  • There is no out-of-memory guard on the listing: a Rust Vec grows fallibly only on true allocation failure, which aborts.
  • No path canonicalization is needed: the caller passes an absolute /-path.

§Turbo Vision heritage

Ports TFileList (fileopen.cpp/dialogs.h), a sorted-list-box subclass; here it becomes a direct SortedSearch impl (deviation D2), persistence is dropped (deviation D12), and the DOS path model becomes native /-paths (deviation D14).

Implementations§

Source§

impl FileList

Source

pub fn new(bounds: Rect, h: Option<ViewId>, v: Option<ViewId>) -> Self

Construct an empty two-column file list, ready to be populated by read_directory or read_directory_listing.

num_cols is fixed at 2 (files in the left column, dirs in the right); the text cursor is shown at column 1 for the incremental type-to-search indicator. h is accepted for API parity with ListBox::new but ignored — a file list only uses the vertical scrollbar v. Pass None for h and the vertical scrollbar’s ViewId for v.

Source

pub fn list(&self) -> &[SearchRec]

Borrow the sorted file/directory listing as a slice.

Populated by read_directory and read_directory_listing; empty until the first call. The slice is in search_rec_compare order: plain files first (alphabetically), then directories, then ".." last. Use focused_rec to get the cursor’s current entry.

Source

pub fn focused_rec(&self) -> Option<SearchRec>

The focused entry, or None when the list is empty (or the focus is out of range). Read by the pump’s ResolveFocusedFile broker to deliver the focused-file payload to the filename input line / info pane.

Source

pub fn read_directory_listing(&mut self, dir: &str, wildcard: &str)

Read and publish the listing without a Context — a sibling of read_directory for the dialog construction path and deterministic tests. Builds and publishes the listing to the list-viewer state (range/focused/top_item) but does NOT sync the scrollbar or broadcast a focused-file event, because both need a Context. The ctx-ful read_directory (driven from reset_current) is the path that does the scrollbar sync + broadcast.

Source

pub fn read_directory( &mut self, dir: &str, wildcard: &str, ctx: &mut Context<'_>, )

Read dir’s contents from the filesystem, apply wildcard filtering, publish the sorted listing to the list-viewer state, and broadcast a “file focused” event so the filename input line and info pane update.

The ctx-ful sibling of read_directory_listing: use this when a live Context is available (i.e. from within an event handler or reset_current). The context-free variant is for construction and deterministic tests where no event loop is running.

Trait Implementations§

Source§

impl ListViewer for FileList

Source§

fn get_text(&self, item: i32) -> String

Return the display text for item item: the bare file name for plain files, or the name with a trailing / appended for directories.

Called on every redraw by the shared list-viewer draw routine. The trailing / signals a directory to the user without altering the underlying SearchRec::name. Out-of-bounds indices return an empty string and never panic.

Source§

fn on_focus_changed(&mut self, ctx: &mut Context<'_>)

Fired on EVERY focus change.

Broadcasts a payload-less “file focused” command with this view as the resolvable source; the pump’s ResolveFocusedFile broker reads focused_rec and delivers it to the consumer. The shared focus machinery invokes this hook after it updates the focused index, so the new entry is already in place.

Source§

fn select_item(&mut self, _item: i32, ctx: &mut Context<'_>)

On double-click / Enter, broadcast a “file double-clicked” command.

Payload-less: the only consumer (FileDialog’s event handler) merely turns it into an OK, and never reads the record. It does not run the default selection behaviour, so it does NOT also emit a generic list-item-selected broadcast.

Source§

fn lv(&self) -> &ListViewerState

Borrow the embedded ListViewerState.
Source§

fn lv_mut(&mut self) -> &mut ListViewerState

Mutably borrow the embedded ListViewerState.
Source§

fn list_roles(&self) -> ListRoles

The six color roles draw uses for this list’s color matrix. Read more
Source§

fn is_selected(&self, item: i32) -> bool

Whether item should be drawn in the selected color. Read more
Source§

fn item_role(&self, _item: i32) -> Option<Role>

An optional per-item Role for a normal row — one that is neither the focused cursor item nor selected. Only the role’s foreground is used: the row keeps the list’s surface background, so a tinted row still reads as part of the list. None (the default) keeps the plain surface colour. A table uses it to tint a whole row (a dimmed or an error row); the focused and selected colours always win over it.
Source§

fn find_query(&self) -> Option<&str>

The current non-empty find query, or None when find mode is Off or the query is empty. The shared draw reads this to highlight matches; hosts read it to mirror the query elsewhere.
Source§

fn set_find_query(&mut self, query: &str, ctx: &mut Context<'_>)

Set the find query from an external source — e.g. a host InputLine that owns the text and drives an unfocused list’s incremental find (a combobox). The mirror image of typed find, minus the keystrokes: a whole-string setter because a text source always holds the complete string. Read more
Source§

fn clear_find(&mut self, ctx: &mut Context<'_>)

Clear the find query — the host-callable Esc equivalent. Equivalent to set_find_query("", ctx): no-op when find is Off or already empty, else fires Command::LIST_FIND_CHANGED and runs Self::on_query_changed.
Source§

fn on_query_changed(&mut self, _ctx: &mut Context<'_>)

Hook fired after the find query changes (default: no-op). A self-filtering concrete widget overrides it to re-derive its visible rows from its source. Called by the shared handle_event and by Self::set_find_query (including Self::clear_find).
Source§

impl SortedSearch for FileList

Source§

fn search(&self, cur: &[char]) -> i32

Map a typed prefix to its insertion point in the sorted listing.

The search key’s attr is FA_DIREC when Shift is held (shift_state & KB_SHIFT) OR the typed prefix starts with ., else 0 — this routes the search into the directory or file section of the listing. The name is the typed prefix verbatim (case-sensitive on Linux).

Returns the first index i in 0..range where search_rec_compare(items[i], key) != Less (the insertion point), or range if none. Compares via search_rec_compare over raw SearchRecs (so attr routing applies) — NOT over the display text.

Source§

fn search_pos(&self) -> i32

The index of the last matched char in the focused item’s text; -1 = no active search.
Source§

fn set_search_pos(&mut self, pos: i32)

Source§

fn shift_state(&self) -> u8

The shift bits captured at the search_pos -1↔0 transition. A plain sorted list box never reads it; file/dir subclasses’ search does.
Source§

fn set_shift_state(&mut self, s: u8)

Source§

impl View for FileList

Source§

fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context<'_>)

Dispatch mouse, keyboard, and incremental type-to-search events.

Delegates to the shared sorted-list handler (sorted_handle_event): printable characters start or extend an incremental search that jumps the cursor to the first matching file name (Shift → searches the directory section); arrow keys, Page Up/Down, and mouse navigate the two-column listing; Enter / double-click fires select_item which broadcasts Command::FILE_DOUBLE_CLICKED. The event loop drives this; callers do not call it directly.

Source§

fn set_state(&mut self, flag: StateFlag, enable: bool, ctx: &mut Context<'_>)

No special state handling — the plain shared behaviour (its only owner notification is in the focus-change hook above).

Source§

fn on_bounds_changed(&mut self, ctx: &mut Context<'_>)

Republish the scrollbar range on resize.

Source§

fn value(&self) -> Option<FieldValue>

None — the file list contributes nothing to dialog data transfer.

Source§

fn state(&self) -> &ViewState

Borrow the embedded ViewState (the view’s data members).
Source§

fn state_mut(&mut self) -> &mut ViewState

Mutably borrow the embedded ViewState.
Source§

fn draw(&mut self, ctx: &mut DrawCtx<'_>)

Paint the view through ctx. Must be overridden. Read more
Source§

fn cursor_request(&self) -> Option<Point>

The view-local hardware-cursor position this view wants shown, or None to hide it. Base: Some(cursor) iff the view is focused with a visible cursor, else None. Read more
Source§

fn apply_scroll_sync( &mut self, h: Option<i32>, v: Option<i32>, ctx: &mut Context<'_>, )

The shared scrollbar read-sync broker hook. Defaulted no-op; scroll-aware widgets override it to apply a freshly-read scrollbar delta to themselves. The pump passes the horizontal/vertical scrollbar values (None if that bar is absent or unresolved), each read via View::value. Overridden by the list viewers (delegate to list_viewer::apply_scroll), Scroller, the outline viewer, and the editor — every sibling-scrollbar read sync routes through this one method instead of a pump downcast. Read more
Source§

fn as_any_mut(&mut self) -> Option<&mut dyn Any>

Downcast hook for the rare parent→child push that needs the concrete type (e.g. a window pushing its zoomed flag to its frame). Base returns None; only views that must be reached concretely override it. (Any requires 'static, which every view is.)
Source§

fn valid(&mut self, _cmd: Command, _ctx: &mut Context<'_>) -> bool

Whether the view is in a valid state for cmd (e.g. a modal end / focus release). Base is always true. Read more
Source§

fn set_modal_answer(&mut self, _cmd: Command)

Stash the user’s choice from an async modal message box this view requested via Context::request_message_box (the answer_to/RouteModalAnswer round-trip). Default: no-op. Overridden by views that drive a Yes/No/Cancel prompt out of valid (e.g. FileEditor caches it for the re-validate).
Source§

fn set_value(&mut self, _v: FieldValue)

Load a typed FieldValue into this control. Read more
Source§

fn set_modal_data(&mut self, _data: FieldValue)

Deliver a finished modal’s typed result record to the view that launched it. Defaulted no-op; a launcher view overrides it to load the record. Two producers call it: Read more
Source§

fn set_value_ctx(&mut self, v: FieldValue, ctx: &mut Context<'_>)

Scatter a typed FieldValue into this control with a Context. Default: calls set_value (the context-free setter). Override when scatter needs deferred publishing (e.g. ListBox republishes its vertical scrollbar via focus_item).
Source§

fn awaken(&mut self)

Post-construction initialization hook. Called once after the view has been inserted into its group and the group’s layout is complete — the earliest point at which a view may safely resolve sibling ids or run initialization that requires a fully-wired tree. Override when a widget needs to do work that cannot happen during construction (e.g. reading a linked control’s current value). Base is a no-op.
Source§

fn size_limits(&self, owner_size: Point) -> (Point, Point)

The (min, max) size this view may take inside an owner of owner_size. Read more
Source§

fn calc_bounds(&mut self, owner_size: Point, delta: Point) -> Rect

The new bounds after the owner resized to owner_size (delta = new - old). Computes the size limits via the overridable size_limits hook — so a widget override (e.g. a window’s minimum) participates — then delegates the grow math to ViewState::calc_bounds (the single source). Returns the bounds; it does not apply them (change_bounds does).
Source§

fn change_bounds(&mut self, bounds: Rect)

Apply bounds to this view and propagate as needed. Read more
Source§

fn caret_size(&self) -> u8

The caret size this view wants while its cursor is shown, as a percentage of the character cell (1..=100). Base: CARET_INSERT (a block) when the cursor_ins state is set, else CARET_NORMAL (the normal caret). The event loop reads it along the same focused chain as cursor_request; Group overrides it to descend into its current child. Read more
Source§

fn find_mut(&mut self, id: ViewId) -> Option<&mut dyn View>

Resolve id to a descendant of this view (never self — the parent identifies a view by id). A leaf has no descendants, so the base returns None; a Group overrides to search its children and recurse; a Group-embedding view delegates to its inner group. This is the “tree-walk via Context” — the uniform way the event loop / a capture handler acts on a view it holds only by id (move a window’s bounds, flip the dragging flag, …).
Source§

fn remove_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool

Remove the descendant named by id from whichever group owns it. Returns true if it was found+removed. Distinct from find_mut because removal happens in the owner’s child Vec (a view cannot remove itself — it doesn’t know its owner) and must run the owning group’s reset_current. Base: false (a leaf owns nothing).
Source§

fn focus_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool

Focus (select) the descendant named by id within whichever group owns it — the tree-op behind a label focusing its linked control. Returns true if id was found in this subtree (selectable or not — finding it stops the walk). Distinct from find_mut because focusing happens in the owning group (a view cannot select itself within itself): the owning Group calls focus_child after applying the selectable gate. Base: false (a leaf owns nothing). Read more
Source§

fn has_focusable_leaf(&self) -> bool

Whether this view’s subtree contains a focusable leaf (visible, enabled, selectable). Base: whether THIS view is itself a focusable leaf; Group overrides to recurse into children; wrapper views delegate. Used by the hierarchical Tab traversal to skip selectable-but-empty subtrees.
Source§

fn focus_to_edge(&mut self, backward: bool, ctx: &mut Context<'_>) -> bool

Focus the first (Tab, backward = false) or last (Shift-Tab, backward = true) focusable leaf in this view’s subtree, establishing the full focus path down to it. Returns true if a focusable leaf was focused. Read more
Source§

fn reset_current(&mut self, _ctx: &mut Context<'_>)

Establish this view’s INTERNAL currency — for a group-bearing view, set its current child to the first visible+selectable child. The insert-time currency cascade cannot run inside the context-less Group::insert, so exec_view calls this on a freshly-inserted modal BEFORE focusing it, so the modal’s first selectable child is current on open (otherwise the modal is keyboard-dead until a nav event — see the seam note in exec_view). Base: no-op (a leaf has no internal currency); Group overrides; Window/Dialog delegate.
Source§

fn settle_currency(&mut self, _ctx: &mut Context<'_>)

Run any pending insert-time reset-current cascades in this subtree. Read more
Source§

fn set_visible_descendant( &mut self, id: ViewId, visible: bool, ctx: &mut Context<'_>, ) -> bool

Tree-op: set the visible flag of the descendant named by id from its OWNING group, running the owning group’s currency tail. Toggling visibility on a selectable view re-picks the owner’s current child, in both directions (show and hide). Returns true if id was found in this subtree. Read more
Source§

fn number(&self) -> Option<i16>

The window number for Alt-N selection. Base views are unnumbered (None); Window overrides to return its number when > 0 (0 means unnumbered → None).
Source§

fn grabs_focus_on_click(&self) -> bool

Whether a mouse-down inside this view should auto-select (focus) it — the per-view opt-out for the group’s mouse-down auto-select (see Group::route_event). Default true (the common case); a Button overrides to return its grab-focus flag. A view returning false is not focused by a click but still receives the click (so it can act, e.g. press, without becoming the current view).
Source§

fn select_window_num(&mut self, num: i16, ctx: &mut Context<'_>) -> bool

Tree-op: ask this subtree to select the window numbered num. Returns whether one matched. Consistent with the find_mut / remove_descendant tree-op family: the live loop holds a subtree only by id (here, the desktop) and asks it to act. Default: no-op (false). Desktop overrides.
Source§

fn tile(&mut self, _r: Rect)

Tree-op: lay this subtree’s tileable windows out in a grid (the tile command). Base: no-op (only Desktop lays out windows). r is the desktop-local layout rect. Mirrors select_window_num: the live loop drives the desktop by id through &mut dyn View.
Source§

fn cascade(&mut self, _r: Rect)

Tree-op: lay this subtree’s tileable windows out cascaded (the cascade command). Base: no-op; Desktop overrides.
Source§

fn update_menu_commands(&mut self, _disabled_cmds: &CommandSet)

The menu command-graying broker hook. Defaulted no-op; menu views override to re-gray their menu tree against the program’s live disabled-command set (denylist — the argument is the set of commands currently disabled; an item grays iff its command is in it). The free fn menu::menu_view::update_menu_commands implements the re-gray walk. Read more
Source§

fn set_menu_current(&mut self, _current: Option<usize>)

The menu-highlight write-back hook. Defaulted no-op; menu views (MenuBar / MenuBox) override to set their MenuViewState::current — the write-only display cache their draw reads to pick the selected colour. Read more
Source§

fn get_help_ctx(&self) -> HelpCtx

The effective help context for status-line switching. Returns HelpCtx::DRAGGING while the view is being dragged, otherwise the view’s own ViewState::help_ctx. Read more
Source§

fn descendant_global_bounds(&self, _id: ViewId, _acc: Point) -> Option<Rect>

Resolve descendant id to its absolute bounds, given acc = this view’s own absolute origin. Base returns None (a leaf owns no descendants); a Group overrides to walk its children accumulating origins, and a Group-embedding view delegates to its inner group. The THistory open path needs its linked input line’s bounds in the root/absolute frame, because exec_view root-inserts the modal and the modal frame hit-tests in absolute coords (the documented ROOT-INSERT + (0,0) caveat). Mirrors find_mut’s recursion but returns geometry, not a borrow.
Source§

fn set_indicator_value(&mut self, _location: Point, _modified: bool)

The editor→indicator status-push broker hook. Defaulted no-op; the editor’s status Indicator overrides it to store the new cursor location + modified flag. Driven by Deferred::IndicatorSetValue: the editor (a leaf) cannot reach its indicator sibling inline, so it requests this and the pump calls the method by id — virtual dispatch, not a downcast.
Source§

fn apply_page_sync(&mut self, _idx: usize, _ctx: &mut Context<'_>)

The tab-bar→page-stack switch broker hook. Defaulted no-op; PageStack overrides it to make page idx active. Driven by Deferred::PageStackSync: the pump reads the bound tab bar’s value and calls this method by id — virtual dispatch, not a downcast.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync> ⓘ

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.