Expand description
Multi-platform abstractions for native file picker dialogs, including dedicated image and video pickers on mobile.
§Platform behavior
All types & functions in this crate are completely platform-independent, so your app code doesn’t need to deal with any of this, but here are some details about how things are implemented on a per-platform basis, in case you’re curious.
- macOS, Linux, Windows: desktop platforms are mostly a wrapper around
rfd. - Android: file pickers use the system document picker
(via//!
ACTION_OPEN_DOCUMENT/ACTION_CREATE_DOCUMENT).- Media picking uses the system Photo Picker when available, otherwise it falls back to the document picker above.
- On Android 10 and up, it saves directly to Downloads via
MediaStore.Downloads. - On Android 8 and 9, it writes directly to storage if the legacy external storage
write permission is granted. Otherwise it falls back to
ACTION_CREATE_DOCUMENT. - Minimum API level: 26 (Android 8.0). The bundled Java helper is loaded via
InMemoryDexClassLoader, which requires API 26. Newer features (the system Photo Picker,MediaStore.Downloads) are used only when the device supports them, so setminSdkto at least 26 in your app.
- iOS: file picking use
UIDocumentPickerViewController, while media picking usesPHPickerViewController.
On Android, picked files are returned as content:// URIs (there’s no other real option),
and as regular filesystem paths on all other platforms (desktop and iOS).
The PickedFile::into_local_file function abstracts over that by returning either the
existing real filesystem path or streaming the URI’s content into a temp file
in the app’s cache dir and then returning that.
Thus, you can always get the file as a regular path.
§Callbacks and thread contexts
All completion callbacks run on a background thread (a true native OS thread, not an async task). The picker dialog popup never runs on the main UI thread, so callbacks can easily do blocking work like reading the picked file or copying its bytes around without freezing the UI.
To communicate between the callback that runs in a background thread and your app’s
main UI thread, use a communication primitive like a channel, or something similar
from your UI toolkit, e.g., Cx::post_action in Makepad.
Structs§
- File
Dialog - A native file dialog builder.
- Local
File - A file guaranteed to be reachable through a filesystem path.
- Picked
File - A file chosen by the user in a native file/media picker dialog.
Enums§
- Error
- Errors encountered when showing a native file dialog/picker.
- Media
Kind - The type of media to show in a native media picker.
- Media
Representation - Which representation of a picked media item the platform should hand back.
- Start
Location - A well-known directory that a file dialog should start in.
Constants§
- DEFAULT_
IMAGE_ EXTENSIONS - The image file extensions that
pick_image(and the image half ofpick_image_or_video) filter by, unless you override them withFileDialog::add_filter. - DEFAULT_
VIDEO_ EXTENSIONS - The video file extensions that
pick_video(and the video half ofpick_image_or_video) filter by, unless you override them withFileDialog::add_filter.