43 releases

0.15.1 Nov 16, 2024
0.14.1 Mar 19, 2024
0.12.1 Oct 20, 2023
0.11.4 May 19, 2023
0.0.1 Nov 27, 2020

#14 in GUI

Download history 55369/week @ 2024-08-23 59836/week @ 2024-08-30 50327/week @ 2024-09-06 45266/week @ 2024-09-13 45485/week @ 2024-09-20 50811/week @ 2024-09-27 50472/week @ 2024-10-04 54570/week @ 2024-10-11 49189/week @ 2024-10-18 52681/week @ 2024-10-25 56117/week @ 2024-11-01 54630/week @ 2024-11-08 56162/week @ 2024-11-15 56539/week @ 2024-11-22 63260/week @ 2024-11-29 52828/week @ 2024-12-06

238,611 downloads per month
Used in 212 crates (128 directly)

MIT license

170KB
4K SLoC

img

version Documentation dependency status

Rusty File Dialogs is a cross platform Rust library for using native file open/save dialogs. It provides both asynchronous and synchronous APIs. Supported platforms:

  • Windows
  • macOS
  • Linux & BSDs (GTK3 or XDG Desktop Portal)
  • WASM32 (async only)

Refer to the documentation for more details.

Platform-specific notes

Linux

Please refer to Linux & BSD backends for information about the needed dependencies to be able to compile on Linux.


lib.rs:

Rusty File Dialogs is a cross platform library for using native file open/save dialogs. It provides both asynchronous and synchronous APIs. Supported platforms:

  • Windows
  • macOS
  • Linux & BSDs (GTK3 or XDG Desktop Portal)
  • WASM32 (async only)

Examples

Synchronous

use rfd::FileDialog;

let files = FileDialog::new()
    .add_filter("text", &["txt", "rs"])
    .add_filter("rust", &["rs", "toml"])
    .set_directory("/")
    .pick_file();

Asynchronous

use rfd::AsyncFileDialog;

let future = async {
    let file = AsyncFileDialog::new()
        .add_filter("text", &["txt", "rs"])
        .add_filter("rust", &["rs", "toml"])
        .set_directory("/")
        .pick_file()
        .await;

    let data = file.unwrap().read().await;
};

Linux & BSD backends

On Linux & BSDs, two backends are available, one using the GTK3 Rust bindings and the other using the XDG Desktop Portal D-Bus API through ashpd & zbus.

GTK backend

The GTK backend is used when the xdg-portal feature is disabled with the default-features = false, and gtk3 is enabled instead. The GTK3 backend requires the C library and development headers to be installed to build RFD. The package names on various distributions are:

Distribution Installation Command
Fedora dnf install gtk3-devel
Arch pacman -S gtk3
Debian & Ubuntu apt install libgtk-3-dev

XDG Desktop Portal backend

The XDG Desktop Portal backend is used with the xdg-portal Cargo feature which is enabled by default. Either the tokio or async-std feature must be enabled. This backend will use either the GTK or KDE file dialog depending on the desktop environment in use at runtime. It does not have any non-Rust build dependencies, however it requires the user to have either the GTK, GNOME, or KDE XDG Desktop Portal backend installed at runtime. These are typically installed by the distribution together with the desktop environment. If you are packaging an application that uses RFD, ensure either one of these is installed with the package. The wlroots portal backend does not implement the D-Bus API that RFD requires (it does not interfere with the other portal implementations; they can all be installed simultaneously).

The XDG Desktop Portal has no API for message dialogs, so the [MessageDialog] and [AsyncMessageDialog] structs will not build with this backend.

macOS non-windowed applications, async, and threading

macOS async dialogs require an NSApplication instance, so the dialog is only truly async when opened in windowed environment like winit or SDL2. Otherwise, it will fallback to sync dialog. It is also recommended to spawn dialogs on your main thread. RFD can run dialogs from any thread but it is only possible in a windowed app and it adds a little bit of overhead. So it is recommended to spawn on main and await in other thread. Non-windowed apps will never be able to spawn async dialogs or from threads other than the main thread.

Customize button texts of message dialog in Windows

TaskDialogIndirect API is used for showing message dialog which can have customized button texts. It is only provided by ComCtl32.dll v6 but Windows use v5 by default. If you want to customize button texts or just need a modern dialog style (aka visual styles), you will need to:

  1. Enable cargo feature common-controls-v6.
  2. Add an application manifest to use ComCtl32.dll v5. See Windows Controls / Enabling Visual Styles

Here is an example using embed-resource.

Cargo features

  • gtk3: Uses GTK for dialogs on Linux & BSDs; has no effect on Windows and macOS
  • xdg-portal: Uses XDG Desktop Portal instead of GTK on Linux & BSDs
  • common-controls-v6: Use TaskDialogIndirect API from ComCtl32.dll v6 for showing message dialog. This is necessary if you need to customize dialog button texts.

State

API Stability
🚧
Feature Linux Windows MacOS Wasm32
SingleFile
MultipleFile
PickFolder
SaveFile
Filters ✔ (GTK only)
StartingPath
Async

rfd-extras

AKA features that are not file related

Feature Linux Windows MacOS Wasm32
MessageDialog ✔ (GTK only)
PromptDialog
ColorPicker

Dependencies

~0.1–17MB
~244K SLoC