Trait MediaDirsExt

pub trait MediaDirsExt: Sized

XDG-specific extensions to fs::MediaDirs.

The XDG conventions are defined by the Freedesktop.org project through the xdg-user-dirs tool. This configuration is generally present on desktop Linux distributions, although adoption is less widespread than the base directory specification.

The XDG conventions are written to be usable on any Unix-like filesystem, thus this extension being provided in os::unix rather than os::linux. However, while some tooling does use XDG conventions on macOS, note that macOS has its own separate conventions for user directories. Consider carefully what conventions your users will expect your application to follow along with any legacy path compatibility you might need to support.

Required Methods

fn xdg() -> Result<Self>

Load the user directory paths according to the xdg-user-dirs tool.

This directly reads and parses the $XDG_CONFIG_HOME/user-dirs.dirs file as defined and maintained by the xdg-user-dirs tool.

Errors

Errors if the user's home directory cannot be determined or if the $XDG_CONFIG_HOME/user-dirs.dirs file cannot be read.

Implementation-specific behavior

Only the format maintained by xdg-user-dirs-update is supported. Any configuration that does not match the expected format will result in loading an unspecified path or None for that directory. To be more specific:

  • Any line not in the format of XDG_{NAME}_DIR={path} where {NAME} is one of DESKTOP, DOWNLOAD, TEMPLATES, PUBLICSHARE, DOCUMENTS, MUSIC, PICTURES, or VIDEOS is ignored.
  • {path} must be a "-quoted shell-escaped path.
  • {path} may only start with / or $HOME/. A home-relative path is returned relative to env::home_dir; shell expansion is not performed.
  • A directory set to just $HOME marks it as removed, and results in a None value for that path.
  • If shell expansion syntax other than a leading $HOME is present, the produced directory path is unspecified. This is invalid config according to the xdg-user-dirs tooling.

This behavior may change in the future. One example change that we explicitly reserve the right to make is to load paths that we currently ignore, such as path formats that are not canonically supported by xdg-user-dirs but which may occur in manually-edited user-dirs.dirs.

fn templates(&self) -> Option<&Path>

The OS-privileged user "Templates" directory, often the Templates folder in the user's home directory.

As a media directory, this should typically be used as a default path for file selection dialogs, not for automatically accessed file paths.

fn set_templates(&mut self, path: PathBuf) -> &mut Self

Set the paths for [Self::templates].

Panics

Panics if the provided path is not absolute.

Implementors