Struct FileManagerState 

pub struct FileManagerState { /* private fields */ }

What a file manager has read of its root folder, what is open in it, and what is selected.

The application owns one of these per manager on screen, hands it every FileManagerMsg and draws it with FileManager. It reads folders in the background, keeps no settings and writes nothing of its own to disk.

use qframe::prelude::*;
use qframe::widgets::{FileManager, FileManagerMsg, FileManagerState};

struct Files {
    manager: FileManagerState,
    opened: Option<std::path::PathBuf>,
}

#[derive(Clone)]
enum Msg {
    Manager(FileManagerMsg),
    Open(std::path::PathBuf),
}

impl App for Files {
    type Msg = Msg;
    fn init(&mut self) -> Command<Msg> {
        self.manager.load(Msg::Manager)
    }
    fn update(&mut self, msg: Msg) -> Command<Msg> {
        match msg {
            Msg::Manager(message) => self.manager.update(message, Msg::Manager),
            Msg::Open(path) => {
                self.opened = Some(path);
                Command::none()
            }
        }
    }
    fn view(&self, ui: &mut View<'_, Msg>) {
        FileManager::new(&self.manager, Msg::Manager)
            .on_open(|path| Msg::Open(path.to_path_buf()))
            .show(ui)
            .fill();
    }
}

Implementations

impl FileManagerState

pub const ROOT: &'static str = ROOT

The key of the root folder: the manager’s top row, and the folder every other key is written relative to.

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

A manager of the folder at root, with nothing read yet.

The root is the manager’s top row and starts open: its entries are what the manager is for.

pub fn confined(self) -> Self

Keeps every operation inside the root: a key that climbs out of it is refused, and so is one that goes through a symbolic link, because a link can point anywhere.

An application that shows a folder the person must not leave (a project, a sandbox) asks for this; one that shows the whole file system does not. It is a rule about what may be changed on disk, so it belongs to the state the operations run from and not to the view, which is built afresh every frame.

pub fn is_confined(&self) -> bool

Whether operations are kept inside the root.

pub fn trashing(self) -> Self

Deleting puts an entry in the person’s own trash instead of taking it away for good, the way the freedesktop trash specification says: $XDG_DATA_HOME/Trash, or ~/.local/share/Trash when that variable says nothing.

An entry that cannot be renamed into that folder — one on another file system, or a run with no home folder at all — is not deleted quietly instead: the manager says there is no trash for it and asks whether to delete it for good, in the danger colour, as its own question.

Windows and macOS have a trash of their own that this specification does not describe, so there this asks the same question rather than inventing a folder.

pub fn trashing_in(self, folder: impl Into<PathBuf>) -> Self

Deleting puts an entry in the trash folder folder instead of the person’s own, for an application that keeps a trash of its own and for a test, which must never touch the person’s.

The folder is made when the first entry goes into it, with the files and info folders the specification asks for.

pub fn is_trashing(&self) -> bool

Whether deleting puts entries in a trash.

pub fn showing_hidden(self, showing: bool) -> Self

Shows the entries the platform hides: the ones whose name starts with a dot.

Off by default, the way a folder is usually looked at. The entries are read either way — one read of a folder is one read — so turning this on shows them without going to the disk, and a new entry’s name is checked against a hidden one that is already there whether they are shown or not.

pub fn set_showing_hidden(&mut self, showing: bool)

Shows or hides the hidden entries; see showing_hidden.

pub fn shows_hidden(&self) -> bool

Whether the entries the platform hides are shown.

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

Follows the folders on screen with a FolderWatch, so what another program changes in them is read again without being asked.

Off by default: the watch waits on a background thread, which a screen that is not shown has no reason to keep, and a test drives the batches itself. Turn it on for a manager the person is looking at and off again when it leaves the screen.

pub fn set_following(&mut self, following: bool)

Turns following outside changes on or off; see following.

pub fn follows_changes(&self) -> bool

Whether outside changes are followed.

pub fn root(&self) -> &Path

The folder the manager shows.

pub fn children(&self, key: &str) -> Option<&[FolderEntry]>

The entries of the folder key, when they have been read.

pub fn folder(&self) -> &str

The folder a flat view shows, the root until one is stepped into.

The tree shows the whole root and takes no notice of this; the list and the icons show this one folder, and FileManagerMsg::Enter and FileManagerMsg::Leave move through it.

pub fn details(&self, key: &str) -> Option<Option<&FileDetails>>

What is known about the entry key besides its name: its size, when it changed last and its permissions.

None while nothing has been asked for that entry, and Some(None) for one the system said nothing about — it went away, or may not be looked at. Ask for details with detail or FileManagerMsg::Detail; a tree row never asks.

pub fn has_details(&self, key: &str) -> bool

Whether the details of key have been asked for, whether or not the answer has come.

pub fn is_open(&self, key: &str) -> bool

Whether the folder key is open.

pub fn is_loading(&self, key: &str) -> bool

Whether the folder key is being read right now.

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

The key of the entry the cursor is on: the row with the pillar, which the keys move from.

pub fn chosen(&self) -> &[String]

The keys of every selected entry, the cursor’s among them unless it was taken out.

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

Why the root folder could not be read, when it could not be.

pub fn cut(&self) -> &[String]

The keys of the entries that were cut and wait to be pasted; empty while what waits is to be copied instead.

pub fn copied(&self) -> &[String]

The keys of the entries that were copied and wait to be pasted.

pub fn pending(&self) -> &[String]

The keys of the entries that wait to be pasted, whether pasting will move or copy them. Only one of the two waits at a time: copying something lets go of what was cut.

pub fn is_copying(&self) -> bool

Whether pasting what waits will copy it rather than move it.

pub fn is_cut(&self, key: &str) -> bool

Whether the entry key was cut, or is inside a folder that was. A copied entry is not: it stays where it is, so nothing about it is faint.

pub fn shown_children(&self, key: &str) -> Option<Vec<&FolderEntry>>

The entries of the folder key that are drawn: all of them, or the ones the platform does not hide while shows_hidden is off.

pub fn work(&self) -> Option<&FileWork>

The long operation running in the background, while one is running. See FileWork.

pub fn naming(&self) -> Option<&Naming>

The dialog asking for a name, while it is open.

pub fn is_folder(&self, key: &str) -> bool

Whether the entry key is a folder, as far as the manager has read.

pub fn folder_keys(&self) -> BTreeSet<String>

The keys of every folder the manager has read so far, the root excepted.

pub fn path(&self, key: &str) -> PathBuf

The path on disk of the entry key, the root itself for Self::ROOT.

pub fn select(&mut self, key: &str)

Makes key the one selected entry, with the cursor on it.

pub fn targets(&self, key: &str) -> Vec<String>

What an action asked for on the row key acts on: the whole selection when the row is one of several selected, and the row alone otherwise, the way a right click on a row is meant.

An entry inside a folder that is also taken is left out, because it goes wherever the folder goes; the root itself is never taken.

pub fn naming_problem(&self) -> Option<NameProblem>

What is wrong with the name typed so far, if anything; an empty name only once the person has tried to confirm it.

pub fn visible_folders(&self) -> Vec<String>

The folders whose rows are on screen: every open folder whose folders above it are all open too, the root first when it is. A folder left open inside a closed one is remembered, not shown.

impl FileManagerState

pub fn load<Msg: Clone + Send + 'static>( &mut self, wrap: impl Fn(FileManagerMsg) -> Msg + Send + Sync + 'static, ) -> Command<Msg>

Reads the root the first time, and every folder on screen again after that: the files may have changed while the manager was away.

Call it when the manager comes on screen. wrap turns the manager’s messages into the application’s own, as in update.

pub fn update<Msg: Clone + Send + 'static>( &mut self, message: FileManagerMsg, wrap: impl Fn(FileManagerMsg) -> Msg + Send + Sync + 'static, ) -> Command<Msg>

Applies message and answers with the work it asks for: folders are read and file operations run on background threads, never while drawing.

wrap is a function such as Msg::Manager, or a closure that captures what it needs, such as a screen’s own conversion. It is used for every message the work sends back, so it must be safe to move to another thread.

pub fn detail<Msg: Clone + Send + 'static>( &mut self, keys: Vec<String>, wrap: impl Fn(FileManagerMsg) -> Msg + Send + Sync + 'static, ) -> Command<Msg>

Asks for the details of the entries keys: their size, when they changed last and their permissions.

Only the keys nothing is known about yet are read, so asking for the same page twice costs nothing. Use this when the application knows exactly which rows it draws; a view that shows details asks for a page around the cursor by itself. Never hand it a whole folder: every key is one more call to the system, which over a remote file system is what a large folder cannot afford.

The answers come back as FileManagerMsg::Detailed and are read with details.

pub fn detail_page<Msg: Clone + Send + 'static>( &mut self, folder: &str, wrap: impl Fn(FileManagerMsg) -> Msg + Send + Sync + 'static, ) -> Command<Msg>

Asks for the details of a page of entries of the folder folder, around the cursor.

A page of two hundred entries is always more than a screen holds and far less than a large folder, so a person scrolling rarely waits and a folder of ten thousand entries never turns into ten thousand calls to the system. The cursor decides where the page sits; a cursor somewhere else, or nowhere, starts it at the top of the folder.

The views that show details use this by themselves; an application that knows exactly which rows it draws asks for those with detail instead.

pub fn detail_gaps(&self, folder: &str) -> Vec<String>

The entries of a page around the cursor in the folder folder that nothing is known about yet and that nothing is on its way for.

This is what a view showing details asks for while it draws: it is empty once the page is known or already being read, so the view asks once and then stops asking.

Trait Implementations

impl Debug for FileManagerState

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

Formats the value using the given formatter.