sdl3_sys/generated/
dialog.rs

1//! File dialog support.
2//!
3//! SDL offers file dialogs, to let users select files with native GUI
4//! interfaces. There are "open" dialogs, "save" dialogs, and folder selection
5//! dialogs. The app can control some details, such as filtering to specific
6//! files, or whether multiple files can be selected by the user.
7//!
8//! Note that launching a file dialog is a non-blocking operation; control
9//! returns to the app immediately, and a callback is called later (possibly in
10//! another thread) when the user makes a choice.
11
12use super::stdinc::*;
13
14use super::error::*;
15
16use super::properties::*;
17
18use super::video::*;
19
20/// An entry for filters for file dialogs.
21///
22/// `name` is a user-readable label for the filter (for example, "Office
23/// document").
24///
25/// `pattern` is a semicolon-separated list of file extensions (for example,
26/// "doc;docx"). File extensions may only contain alphanumeric characters,
27/// hyphens, underscores and periods. Alternatively, the whole string can be a
28/// single asterisk ("*"), which serves as an "All files" filter.
29///
30/// ## Availability
31/// This struct is available since SDL 3.2.0.
32///
33/// ## See also
34/// - [`SDL_DialogFileCallback`]
35/// - [`SDL_ShowOpenFileDialog`]
36/// - [`SDL_ShowSaveFileDialog`]
37/// - [`SDL_ShowOpenFolderDialog`]
38/// - [`SDL_ShowFileDialogWithProperties`]
39#[repr(C)]
40#[derive(Clone, Copy)]
41#[cfg_attr(feature = "debug-impls", derive(Debug))]
42pub struct SDL_DialogFileFilter {
43    pub name: *const ::core::ffi::c_char,
44    pub pattern: *const ::core::ffi::c_char,
45}
46
47impl ::core::default::Default for SDL_DialogFileFilter {
48    /// Initialize all fields to zero
49    #[inline(always)]
50    fn default() -> Self {
51        unsafe { ::core::mem::MaybeUninit::<Self>::zeroed().assume_init() }
52    }
53}
54
55/// Callback used by file dialog functions.
56///
57/// The specific usage is described in each function.
58///
59/// If `filelist` is:
60///
61/// - NULL, an error occurred. Details can be obtained with [`SDL_GetError()`].
62/// - A pointer to NULL, the user either didn't choose any file or canceled the
63///   dialog.
64/// - A pointer to non-`NULL`, the user chose one or more files. The argument
65///   is a null-terminated array of pointers to UTF-8 encoded strings, each
66///   containing a path.
67///
68/// The filelist argument should not be freed; it will automatically be freed
69/// when the callback returns.
70///
71/// The filter argument is the index of the filter that was selected, or -1 if
72/// no filter was selected or if the platform or method doesn't support
73/// fetching the selected filter.
74///
75/// In Android, the `filelist` are `content://` URIs. They should be opened
76/// using [`SDL_IOFromFile()`] with appropriate modes. This applies both to open
77/// and save file dialog.
78///
79/// ## Parameters
80/// - `userdata`: an app-provided pointer, for the callback's use.
81/// - `filelist`: the file(s) chosen by the user.
82/// - `filter`: index of the selected filter.
83///
84/// ## Availability
85/// This datatype is available since SDL 3.2.0.
86///
87/// ## See also
88/// - [`SDL_DialogFileFilter`]
89/// - [`SDL_ShowOpenFileDialog`]
90/// - [`SDL_ShowSaveFileDialog`]
91/// - [`SDL_ShowOpenFolderDialog`]
92/// - [`SDL_ShowFileDialogWithProperties`]
93pub type SDL_DialogFileCallback = ::core::option::Option<
94    unsafe extern "C" fn(
95        userdata: *mut ::core::ffi::c_void,
96        filelist: *const *const ::core::ffi::c_char,
97        filter: ::core::ffi::c_int,
98    ),
99>;
100
101unsafe extern "C" {
102    /// Displays a dialog that lets the user select a file on their filesystem.
103    ///
104    /// This is an asynchronous function; it will return immediately, and the
105    /// result will be passed to the callback.
106    ///
107    /// The callback will be invoked with a null-terminated list of files the user
108    /// chose. The list will be empty if the user canceled the dialog, and it will
109    /// be NULL if an error occurred.
110    ///
111    /// Note that the callback may be called from a different thread than the one
112    /// the function was invoked on.
113    ///
114    /// Depending on the platform, the user may be allowed to input paths that
115    /// don't yet exist.
116    ///
117    /// On Linux, dialogs may require XDG Portals, which requires DBus, which
118    /// requires an event-handling loop. Apps that do not use SDL to handle events
119    /// should add a call to [`SDL_PumpEvents`] in their main loop.
120    ///
121    /// ## Parameters
122    /// - `callback`: a function pointer to be invoked when the user selects a
123    ///   file and accepts, or cancels the dialog, or an error
124    ///   occurs.
125    /// - `userdata`: an optional pointer to pass extra data to the callback when
126    ///   it will be invoked.
127    /// - `window`: the window that the dialog should be modal for, may be NULL.
128    ///   Not all platforms support this option.
129    /// - `filters`: a list of filters, may be NULL. See the
130    ///   [`SDL_DialogFileFilter`](SDL_DialogFileFilter#code-examples)
131    ///   documentation for examples\]. Not all platforms support this
132    ///   option, and platforms that do support it may allow the user
133    ///   to ignore the filters. If non-NULL, it must remain valid at
134    ///   least until the callback is invoked.
135    /// - `nfilters`: the number of filters. Ignored if filters is NULL.
136    /// - `default_location`: the default folder or file to start the dialog at,
137    ///   may be NULL. Not all platforms support this option.
138    /// - `allow_many`: if non-zero, the user will be allowed to select multiple
139    ///   entries. Not all platforms support this option.
140    ///
141    /// ## Thread safety
142    /// This function should be called only from the main thread. The
143    ///   callback may be invoked from the same thread or from a
144    ///   different one, depending on the OS's constraints.
145    ///
146    /// ## Availability
147    /// This function is available since SDL 3.2.0.
148    ///
149    /// ## See also
150    /// - [`SDL_DialogFileCallback`]
151    /// - [`SDL_DialogFileFilter`]
152    /// - [`SDL_ShowSaveFileDialog`]
153    /// - [`SDL_ShowOpenFolderDialog`]
154    /// - [`SDL_ShowFileDialogWithProperties`]
155    pub fn SDL_ShowOpenFileDialog(
156        callback: SDL_DialogFileCallback,
157        userdata: *mut ::core::ffi::c_void,
158        window: *mut SDL_Window,
159        filters: *const SDL_DialogFileFilter,
160        nfilters: ::core::ffi::c_int,
161        default_location: *const ::core::ffi::c_char,
162        allow_many: ::core::primitive::bool,
163    );
164}
165
166unsafe extern "C" {
167    /// Displays a dialog that lets the user choose a new or existing file on their
168    /// filesystem.
169    ///
170    /// This is an asynchronous function; it will return immediately, and the
171    /// result will be passed to the callback.
172    ///
173    /// The callback will be invoked with a null-terminated list of files the user
174    /// chose. The list will be empty if the user canceled the dialog, and it will
175    /// be NULL if an error occurred.
176    ///
177    /// Note that the callback may be called from a different thread than the one
178    /// the function was invoked on.
179    ///
180    /// The chosen file may or may not already exist.
181    ///
182    /// On Linux, dialogs may require XDG Portals, which requires DBus, which
183    /// requires an event-handling loop. Apps that do not use SDL to handle events
184    /// should add a call to [`SDL_PumpEvents`] in their main loop.
185    ///
186    /// ## Parameters
187    /// - `callback`: a function pointer to be invoked when the user selects a
188    ///   file and accepts, or cancels the dialog, or an error
189    ///   occurs.
190    /// - `userdata`: an optional pointer to pass extra data to the callback when
191    ///   it will be invoked.
192    /// - `window`: the window that the dialog should be modal for, may be NULL.
193    ///   Not all platforms support this option.
194    /// - `filters`: a list of filters, may be NULL. Not all platforms support
195    ///   this option, and platforms that do support it may allow the
196    ///   user to ignore the filters. If non-NULL, it must remain
197    ///   valid at least until the callback is invoked.
198    /// - `nfilters`: the number of filters. Ignored if filters is NULL.
199    /// - `default_location`: the default folder or file to start the dialog at,
200    ///   may be NULL. Not all platforms support this option.
201    ///
202    /// ## Thread safety
203    /// This function should be called only from the main thread. The
204    ///   callback may be invoked from the same thread or from a
205    ///   different one, depending on the OS's constraints.
206    ///
207    /// ## Availability
208    /// This function is available since SDL 3.2.0.
209    ///
210    /// ## See also
211    /// - [`SDL_DialogFileCallback`]
212    /// - [`SDL_DialogFileFilter`]
213    /// - [`SDL_ShowOpenFileDialog`]
214    /// - [`SDL_ShowOpenFolderDialog`]
215    /// - [`SDL_ShowFileDialogWithProperties`]
216    pub fn SDL_ShowSaveFileDialog(
217        callback: SDL_DialogFileCallback,
218        userdata: *mut ::core::ffi::c_void,
219        window: *mut SDL_Window,
220        filters: *const SDL_DialogFileFilter,
221        nfilters: ::core::ffi::c_int,
222        default_location: *const ::core::ffi::c_char,
223    );
224}
225
226unsafe extern "C" {
227    /// Displays a dialog that lets the user select a folder on their filesystem.
228    ///
229    /// This is an asynchronous function; it will return immediately, and the
230    /// result will be passed to the callback.
231    ///
232    /// The callback will be invoked with a null-terminated list of files the user
233    /// chose. The list will be empty if the user canceled the dialog, and it will
234    /// be NULL if an error occurred.
235    ///
236    /// Note that the callback may be called from a different thread than the one
237    /// the function was invoked on.
238    ///
239    /// Depending on the platform, the user may be allowed to input paths that
240    /// don't yet exist.
241    ///
242    /// On Linux, dialogs may require XDG Portals, which requires DBus, which
243    /// requires an event-handling loop. Apps that do not use SDL to handle events
244    /// should add a call to [`SDL_PumpEvents`] in their main loop.
245    ///
246    /// ## Parameters
247    /// - `callback`: a function pointer to be invoked when the user selects a
248    ///   file and accepts, or cancels the dialog, or an error
249    ///   occurs.
250    /// - `userdata`: an optional pointer to pass extra data to the callback when
251    ///   it will be invoked.
252    /// - `window`: the window that the dialog should be modal for, may be NULL.
253    ///   Not all platforms support this option.
254    /// - `default_location`: the default folder or file to start the dialog at,
255    ///   may be NULL. Not all platforms support this option.
256    /// - `allow_many`: if non-zero, the user will be allowed to select multiple
257    ///   entries. Not all platforms support this option.
258    ///
259    /// ## Thread safety
260    /// This function should be called only from the main thread. The
261    ///   callback may be invoked from the same thread or from a
262    ///   different one, depending on the OS's constraints.
263    ///
264    /// ## Availability
265    /// This function is available since SDL 3.2.0.
266    ///
267    /// ## See also
268    /// - [`SDL_DialogFileCallback`]
269    /// - [`SDL_ShowOpenFileDialog`]
270    /// - [`SDL_ShowSaveFileDialog`]
271    /// - [`SDL_ShowFileDialogWithProperties`]
272    pub fn SDL_ShowOpenFolderDialog(
273        callback: SDL_DialogFileCallback,
274        userdata: *mut ::core::ffi::c_void,
275        window: *mut SDL_Window,
276        default_location: *const ::core::ffi::c_char,
277        allow_many: ::core::primitive::bool,
278    );
279}
280
281/// Various types of file dialogs.
282///
283/// This is used by [`SDL_ShowFileDialogWithProperties()`] to decide what kind of
284/// dialog to present to the user.
285///
286/// ## Availability
287/// This enum is available since SDL 3.2.0.
288///
289/// ## See also
290/// - [`SDL_ShowFileDialogWithProperties`]
291///
292/// ## Known values (`sdl3-sys`)
293/// | Associated constant | Global constant | Description |
294/// | ------------------- | --------------- | ----------- |
295/// | [`OPENFILE`](SDL_FileDialogType::OPENFILE) | [`SDL_FILEDIALOG_OPENFILE`] | |
296/// | [`SAVEFILE`](SDL_FileDialogType::SAVEFILE) | [`SDL_FILEDIALOG_SAVEFILE`] | |
297/// | [`OPENFOLDER`](SDL_FileDialogType::OPENFOLDER) | [`SDL_FILEDIALOG_OPENFOLDER`] | |
298#[repr(transparent)]
299#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
300pub struct SDL_FileDialogType(pub ::core::ffi::c_int);
301
302impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_FileDialogType {
303    #[inline(always)]
304    fn eq(&self, other: &::core::ffi::c_int) -> bool {
305        &self.0 == other
306    }
307}
308
309impl ::core::cmp::PartialEq<SDL_FileDialogType> for ::core::ffi::c_int {
310    #[inline(always)]
311    fn eq(&self, other: &SDL_FileDialogType) -> bool {
312        self == &other.0
313    }
314}
315
316impl From<SDL_FileDialogType> for ::core::ffi::c_int {
317    #[inline(always)]
318    fn from(value: SDL_FileDialogType) -> Self {
319        value.0
320    }
321}
322
323#[cfg(feature = "debug-impls")]
324impl ::core::fmt::Debug for SDL_FileDialogType {
325    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
326        #[allow(unreachable_patterns)]
327        f.write_str(match *self {
328            Self::OPENFILE => "SDL_FILEDIALOG_OPENFILE",
329            Self::SAVEFILE => "SDL_FILEDIALOG_SAVEFILE",
330            Self::OPENFOLDER => "SDL_FILEDIALOG_OPENFOLDER",
331
332            _ => return write!(f, "SDL_FileDialogType({})", self.0),
333        })
334    }
335}
336
337impl SDL_FileDialogType {
338    pub const OPENFILE: Self = Self((0 as ::core::ffi::c_int));
339    pub const SAVEFILE: Self = Self((1 as ::core::ffi::c_int));
340    pub const OPENFOLDER: Self = Self((2 as ::core::ffi::c_int));
341}
342
343pub const SDL_FILEDIALOG_OPENFILE: SDL_FileDialogType = SDL_FileDialogType::OPENFILE;
344pub const SDL_FILEDIALOG_SAVEFILE: SDL_FileDialogType = SDL_FileDialogType::SAVEFILE;
345pub const SDL_FILEDIALOG_OPENFOLDER: SDL_FileDialogType = SDL_FileDialogType::OPENFOLDER;
346
347#[cfg(feature = "metadata")]
348impl sdl3_sys::metadata::GroupMetadata for SDL_FileDialogType {
349    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
350        &crate::metadata::dialog::METADATA_SDL_FileDialogType;
351}
352
353unsafe extern "C" {
354    /// Create and launch a file dialog with the specified properties.
355    ///
356    /// These are the supported properties:
357    ///
358    /// - [`SDL_PROP_FILE_DIALOG_FILTERS_POINTER`]\: a pointer to a list of
359    ///   [`SDL_DialogFileFilter`] structs, which will be used as filters for
360    ///   file-based selections. Ignored if the dialog is an "Open Folder" dialog.
361    ///   If non-NULL, the array of filters must remain valid at least until the
362    ///   callback is invoked.
363    /// - [`SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`]\: the number of filters in the
364    ///   array of filters, if it exists.
365    /// - [`SDL_PROP_FILE_DIALOG_WINDOW_POINTER`]\: the window that the dialog should
366    ///   be modal for.
367    /// - [`SDL_PROP_FILE_DIALOG_LOCATION_STRING`]\: the default folder or file to
368    ///   start the dialog at.
369    /// - [`SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`]\: true to allow the user to select
370    ///   more than one entry.
371    /// - [`SDL_PROP_FILE_DIALOG_TITLE_STRING`]\: the title for the dialog.
372    /// - [`SDL_PROP_FILE_DIALOG_ACCEPT_STRING`]\: the label that the accept button
373    ///   should have.
374    /// - [`SDL_PROP_FILE_DIALOG_CANCEL_STRING`]\: the label that the cancel button
375    ///   should have.
376    ///
377    /// Note that each platform may or may not support any of the properties.
378    ///
379    /// ## Parameters
380    /// - `type`: the type of file dialog.
381    /// - `callback`: a function pointer to be invoked when the user selects a
382    ///   file and accepts, or cancels the dialog, or an error
383    ///   occurs.
384    /// - `userdata`: an optional pointer to pass extra data to the callback when
385    ///   it will be invoked.
386    /// - `props`: the properties to use.
387    ///
388    /// ## Thread safety
389    /// This function should be called only from the main thread. The
390    ///   callback may be invoked from the same thread or from a
391    ///   different one, depending on the OS's constraints.
392    ///
393    /// ## Availability
394    /// This function is available since SDL 3.2.0.
395    ///
396    /// ## See also
397    /// - [`SDL_FileDialogType`]
398    /// - [`SDL_DialogFileCallback`]
399    /// - [`SDL_DialogFileFilter`]
400    /// - [`SDL_ShowOpenFileDialog`]
401    /// - [`SDL_ShowSaveFileDialog`]
402    /// - [`SDL_ShowOpenFolderDialog`]
403    pub fn SDL_ShowFileDialogWithProperties(
404        r#type: SDL_FileDialogType,
405        callback: SDL_DialogFileCallback,
406        userdata: *mut ::core::ffi::c_void,
407        props: SDL_PropertiesID,
408    );
409}
410
411pub const SDL_PROP_FILE_DIALOG_FILTERS_POINTER: *const ::core::ffi::c_char =
412    c"SDL.filedialog.filters".as_ptr();
413
414pub const SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER: *const ::core::ffi::c_char =
415    c"SDL.filedialog.nfilters".as_ptr();
416
417pub const SDL_PROP_FILE_DIALOG_WINDOW_POINTER: *const ::core::ffi::c_char =
418    c"SDL.filedialog.window".as_ptr();
419
420pub const SDL_PROP_FILE_DIALOG_LOCATION_STRING: *const ::core::ffi::c_char =
421    c"SDL.filedialog.location".as_ptr();
422
423pub const SDL_PROP_FILE_DIALOG_MANY_BOOLEAN: *const ::core::ffi::c_char =
424    c"SDL.filedialog.many".as_ptr();
425
426pub const SDL_PROP_FILE_DIALOG_TITLE_STRING: *const ::core::ffi::c_char =
427    c"SDL.filedialog.title".as_ptr();
428
429pub const SDL_PROP_FILE_DIALOG_ACCEPT_STRING: *const ::core::ffi::c_char =
430    c"SDL.filedialog.accept".as_ptr();
431
432pub const SDL_PROP_FILE_DIALOG_CANCEL_STRING: *const ::core::ffi::c_char =
433    c"SDL.filedialog.cancel".as_ptr();
434
435#[cfg(doc)]
436use crate::everything::*;
sdl3_sys/generated/dialog.rs

sdl3_sys/generated/
dialog.rs
