Struct FilePickerState 

pub struct FilePickerState { /* private fields */ }

The path text, the listings, the filtered rows, and the selection of a FilePicker.

The text is a path. Everything up to and including its last separator is the directory that is listed; what follows is a fuzzy query over that directory’s entries. Typing a separator after a query goes inside the folder it names, and a leading ~ stands for the source’s home. Folders come first. A double click or Enter goes inside a folder, and the Up button goes to the parent.

A click selects a file. In a picker that takes multiple files, Cmd (Ctrl elsewhere) toggles a file, Shift selects the range from the last file clicked, and Cmd+A selects every file listed while the path has no query. Enter or a double click on a file chooses it, and Cmd+Enter (Ctrl+Enter elsewhere) chooses the selection. The selection belongs to the directory that is listed, and only files that show count: a file the filter or the query hides is not chosen.

Implementations

impl FilePickerState

pub fn new(window: &mut Window, cx: &mut Context<'_, Self>) -> Self

A picker on the local file system, at the user’s home folder (the root when there is none). It takes one file, and hides hidden entries. Name another start with with_initial.

pub fn with_source( self, source: impl FileSource, window: &mut Window, cx: &mut Context<'_, Self>, ) -> Self

Lists entries from source instead of the local file system. The listings cached so far are dropped and the current directory is listed again. The picker starts at the new source’s home, unless with_initial named a start, and at the root when the source has no home. See FileSource for how to write one.

pub fn set_source( &mut self, source: impl FileSource, window: &mut Window, cx: &mut Context<'_, Self>, )

Lists from source from now on, as with_source does for a picker being built: the listings cached so far are dropped, the requests in flight are cancelled, and the picker goes to the new source’s home, or keeps the path it was given with with_initial.

pub fn with_initial( self, path: impl AsRef<str>, window: &mut Window, cx: &mut Context<'_, Self>, ) -> Self

Starts in path, which is listed at once. A path that starts with ~ is in the source’s home. This wins over the source’s home as the start.

pub fn with_multiple(self, multiple: bool) -> Self

Whether the picker takes more than one file. The default is one.

pub fn with_filters( self, filters: Vec<FileFilter>, cx: &mut Context<'_, Self>, ) -> Self

The file types the user can switch between, such as “All files” and “Rust files”. The first is active. A filter with no extensions shows every file. With one filter the dialog names it, and with several it offers a menu. Folders always show.

pub fn set_active_filter(&mut self, index: usize, cx: &mut Context<'_, Self>)

Makes the filter at index the active one. An index out of range changes nothing.

pub fn set_show_hidden(&mut self, show: bool, cx: &mut Context<'_, Self>)

Shows or hides the hidden entries. They are hidden by default.

pub fn on_auth_required( self, handler: impl Fn(&mut Window, &mut App) + 'static, ) -> Self

Sets what the “Sign in” button does. A source that needs the user to log in fails a listing with ListError::AuthRequired, and the list then shows the source’s message with a “Sign in” button that calls handler. The picker holds no login code: the application signs the user in, then calls retry to list again. Without a handler the button is not shown.

pub fn retry(&mut self, cx: &mut Context<'_, Self>)

Lists the directory again: the spinner shows and the source is asked for the first page. Call it after the user signed in, or let the “Retry” button call it.

pub fn failure(&self) -> Option<&ListError>

Why the directory could not be listed, when it could not.

pub fn allow_new_folder(self, allow: bool) -> Self

Offers a “New folder” button, which opens a row at the top of the list to name a folder in the directory that is listed. It is off by default, and shows only when the source can make folders.

pub fn allows_new_folder(&self) -> bool

Whether the picker is set to offer a “New folder” button.

pub fn set_allow_new_folder(&mut self, allow: bool, cx: &mut Context<'_, Self>)

Offers or withdraws the “New folder” button.

pub fn can_create_folder(&self) -> bool

Whether the button shows: it is on and the source can make folders.

pub fn is_naming_folder(&self) -> bool

Whether the row that names a new folder is open.

pub fn new_folder_name(&self, cx: &App) -> Option<SharedString>

The name typed in the row that names a new folder, or None while the row is closed.

pub fn begin_new_folder( &mut self, window: &mut Window, cx: &mut Context<'_, Self>, )

Opens the row that names a new folder, with “Untitled folder” selected. Nothing is made until the name is confirmed with Enter. It does nothing while the directory loads, or when the source cannot make folders.

pub fn create_folder( &mut self, name: &str, window: &mut Window, cx: &mut Context<'_, Self>, ) -> Result<(), CreateFolderError>

Makes the folder name in the directory that is listed, the way the row does: the row opens with name, or takes it when it is already open, the name is checked, the source is asked, and the result shows in the row. The picker reports FilePickerEvent::FolderCreated when the folder exists.

Fails with CreateFolderError::NotReady while the directory loads or a folder is being made, CreateFolderError::Unsupported when new folders are off or the source cannot make them, and CreateFolderError::InvalidName or CreateFolderError::Exists for a name that is refused before the source is asked.

pub fn input(&self) -> &Entity<InputState>

The path field’s state.

pub fn dir(&self) -> &SourcePath

The directory that is listed.

pub fn query(&self) -> &str

The query: the text after the last separator.

pub fn text(&self, cx: &App) -> SharedString

The path text, as the field shows it.

pub fn listing(&self) -> Option<&FileListing>

What is known about the directory that is listed.

pub fn row_count(&self) -> usize

How many entries the list shows, not counting the “Load more” row.

pub fn highlighted(&self) -> Option<SharedString>

The name of the entry the keyboard is on.

pub fn names(&self) -> Vec<SharedString>

The names the list shows, in order.

pub fn multiple(&self) -> bool

Whether the picker takes more than one file.

pub fn filters(&self) -> &[FileFilter]

The filters the user can switch between.

pub fn active_filter_index(&self) -> usize

The index of the active filter.

pub fn active_filter(&self) -> Option<&FileFilter>

The active filter, when there are any.

pub fn filtered_out(&self) -> usize

How many files of the listed directory the active filter hides, not counting hidden files.

pub fn hidden_files(&self) -> usize

How many hidden files of the listed directory the switch hides.

pub fn file_count(&self) -> usize

How many files the listed directory holds, whatever the filter and the switch hide.

pub fn show_hidden(&self) -> bool

Whether hidden entries show.

pub fn selection(&self) -> Vec<SourcePath>

The files selected and showing, in the order of the list.

pub fn select_all(&mut self, cx: &mut Context<'_, Self>)

Selects every file that shows. A picker for one file does nothing.

pub fn clear_selection(&mut self, cx: &mut Context<'_, Self>)

Selects nothing.

pub fn confirm(&mut self, cx: &mut Context<'_, Self>)

Chooses the selection, if it is not empty.

pub fn cancel(&mut self, cx: &mut Context<'_, Self>)

Cancels the picker and every request to the source that is still running: their answers never arrive. A directory that was still loading is listed again when the picker shows.

pub fn go_up(&mut self, window: &mut Window, cx: &mut Context<'_, Self>)

Goes to the parent of the listed directory. The root is its own parent.

pub fn descend( &mut self, name: &str, window: &mut Window, cx: &mut Context<'_, Self>, )

Goes inside the folder name of the listed directory.

pub fn load_more(&mut self, cx: &mut Context<'_, Self>)

Asks the source for the next page of the listed directory, when it has one and no request is running. After a failure it asks again.

Trait Implementations

impl EventEmitter<FilePickerEvent> for FilePickerState

impl Focusable for FilePickerState

The path field’s focus, which holds the keyboard for the picker.

fn focus_handle(&self, cx: &App) -> FocusHandle

Returns the focus handle associated with this view.