gtk4/auto/
file_chooser_native.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4#![allow(deprecated)]
5
6use crate::{ffi, FileChooser, FileChooserAction, FileFilter, NativeDialog, Window};
7use glib::{
8    prelude::*,
9    signal::{connect_raw, SignalHandlerId},
10    translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15    /// Use [`FileDialog`][crate::FileDialog] instead
16    /// [`FileChooserNative`][crate::FileChooserNative] is an abstraction of a dialog suitable
17    /// for use with “File Open” or “File Save as” commands.
18    ///
19    /// By default, this just uses a [`FileChooserDialog`][crate::FileChooserDialog] to implement
20    /// the actual dialog. However, on some platforms, such as Windows and
21    /// macOS, the native platform file chooser is used instead. When the
22    /// application is running in a sandboxed environment without direct
23    /// filesystem access (such as Flatpak), [`FileChooserNative`][crate::FileChooserNative] may call
24    /// the proper APIs (portals) to let the user choose a file and make it
25    /// available to the application.
26    ///
27    /// While the API of [`FileChooserNative`][crate::FileChooserNative] closely mirrors [`FileChooserDialog`][crate::FileChooserDialog],
28    /// the main difference is that there is no access to any [`Window`][crate::Window] or [`Widget`][crate::Widget]
29    /// for the dialog. This is required, as there may not be one in the case of a
30    /// platform native dialog.
31    ///
32    /// Showing, hiding and running the dialog is handled by the
33    /// [`NativeDialog`][crate::NativeDialog] functions.
34    ///
35    /// Note that unlike [`FileChooserDialog`][crate::FileChooserDialog], [`FileChooserNative`][crate::FileChooserNative] objects
36    /// are not toplevel widgets, and GTK does not keep them alive. It is your
37    /// responsibility to keep a reference until you are done with the
38    /// object.
39    ///
40    /// ## Typical usage
41    ///
42    /// In the simplest of cases, you can the following code to use
43    /// [`FileChooserNative`][crate::FileChooserNative] to select a file for opening:
44    ///
45    /// **⚠️ The following code is in c ⚠️**
46    ///
47    /// ```c
48    /// static void
49    /// on_response (GtkNativeDialog *native,
50    ///              int              response)
51    /// {
52    ///   if (response == GTK_RESPONSE_ACCEPT)
53    ///     {
54    ///       GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
55    ///       GFile *file = gtk_file_chooser_get_file (chooser);
56    ///
57    ///       open_file (file);
58    ///
59    ///       g_object_unref (file);
60    ///     }
61    ///
62    ///   g_object_unref (native);
63    /// }
64    ///
65    ///   // ...
66    ///   GtkFileChooserNative *native;
67    ///   GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
68    ///
69    ///   native = gtk_file_chooser_native_new ("Open File",
70    ///                                         parent_window,
71    ///                                         action,
72    ///                                         "_Open",
73    ///                                         "_Cancel");
74    ///
75    ///   g_signal_connect (native, "response", G_CALLBACK (on_response), NULL);
76    ///   gtk_native_dialog_show (GTK_NATIVE_DIALOG (native));
77    /// ```
78    ///
79    /// To use a [`FileChooserNative`][crate::FileChooserNative] for saving, you can use this:
80    ///
81    /// **⚠️ The following code is in c ⚠️**
82    ///
83    /// ```c
84    /// static void
85    /// on_response (GtkNativeDialog *native,
86    ///              int              response)
87    /// {
88    ///   if (response == GTK_RESPONSE_ACCEPT)
89    ///     {
90    ///       GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
91    ///       GFile *file = gtk_file_chooser_get_file (chooser);
92    ///
93    ///       save_to_file (file);
94    ///
95    ///       g_object_unref (file);
96    ///     }
97    ///
98    ///   g_object_unref (native);
99    /// }
100    ///
101    ///   // ...
102    ///   GtkFileChooserNative *native;
103    ///   GtkFileChooser *chooser;
104    ///   GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
105    ///
106    ///   native = gtk_file_chooser_native_new ("Save File",
107    ///                                         parent_window,
108    ///                                         action,
109    ///                                         "_Save",
110    ///                                         "_Cancel");
111    ///   chooser = GTK_FILE_CHOOSER (native);
112    ///
113    ///   if (user_edited_a_new_document)
114    ///     gtk_file_chooser_set_current_name (chooser, _("Untitled document"));
115    ///   else
116    ///     gtk_file_chooser_set_file (chooser, existing_file, NULL);
117    ///
118    ///   g_signal_connect (native, "response", G_CALLBACK (on_response), NULL);
119    ///   gtk_native_dialog_show (GTK_NATIVE_DIALOG (native));
120    /// ```
121    ///
122    /// For more information on how to best set up a file dialog,
123    /// see the [`FileChooserDialog`][crate::FileChooserDialog] documentation.
124    ///
125    /// ## Response Codes
126    ///
127    /// [`FileChooserNative`][crate::FileChooserNative] inherits from [`NativeDialog`][crate::NativeDialog],
128    /// which means it will return [`ResponseType::Accept`][crate::ResponseType::Accept] if the user accepted,
129    /// and [`ResponseType::Cancel`][crate::ResponseType::Cancel] if he pressed cancel. It can also return
130    /// [`ResponseType::DeleteEvent`][crate::ResponseType::DeleteEvent] if the window was unexpectedly closed.
131    ///
132    /// ## Differences from [`FileChooserDialog`][crate::FileChooserDialog]
133    ///
134    /// There are a few things in the [`FileChooser`][crate::FileChooser] interface that
135    /// are not possible to use with [`FileChooserNative`][crate::FileChooserNative], as such use would
136    /// prohibit the use of a native dialog.
137    ///
138    /// No operations that change the dialog work while the dialog is visible.
139    /// Set all the properties that are required before showing the dialog.
140    ///
141    /// ## Win32 details
142    ///
143    /// On windows the `IFileDialog` implementation (added in Windows Vista) is
144    /// used. It supports many of the features that [`FileChooser`][crate::FileChooser] has, but
145    /// there are some things it does not handle:
146    ///
147    /// * Any [`FileFilter`][crate::FileFilter] added using a mimetype
148    ///
149    /// If any of these features are used the regular [`FileChooserDialog`][crate::FileChooserDialog]
150    /// will be used in place of the native one.
151    ///
152    /// ## Portal details
153    ///
154    /// When the `org.freedesktop.portal.FileChooser` portal is available on
155    /// the session bus, it is used to bring up an out-of-process file chooser.
156    /// Depending on the kind of session the application is running in, this may
157    /// or may not be a GTK file chooser.
158    ///
159    /// ## macOS details
160    ///
161    /// On macOS the `NSSavePanel` and `NSOpenPanel` classes are used to provide
162    /// native file chooser dialogs. Some features provided by [`FileChooser`][crate::FileChooser]
163    /// are not supported:
164    ///
165    /// * Shortcut folders.
166    ///
167    /// ## Properties
168    ///
169    ///
170    /// #### `accept-label`
171    ///  The text used for the label on the accept button in the dialog, or
172    /// [`None`] to use the default text.
173    ///
174    /// Readable | Writeable
175    ///
176    ///
177    /// #### `cancel-label`
178    ///  The text used for the label on the cancel button in the dialog, or
179    /// [`None`] to use the default text.
180    ///
181    /// Readable | Writeable
182    /// <details><summary><h4>NativeDialog</h4></summary>
183    ///
184    ///
185    /// #### `modal`
186    ///  Whether the window should be modal with respect to its transient parent.
187    ///
188    /// Readable | Writeable
189    ///
190    ///
191    /// #### `title`
192    ///  The title of the dialog window
193    ///
194    /// Readable | Writeable
195    ///
196    ///
197    /// #### `transient-for`
198    ///  The transient parent of the dialog, or [`None`] for none.
199    ///
200    /// Readable | Writeable | Construct
201    ///
202    ///
203    /// #### `visible`
204    ///  Whether the window is currently visible.
205    ///
206    /// Readable | Writeable
207    /// </details>
208    /// <details><summary><h4>FileChooser</h4></summary>
209    ///
210    ///
211    /// #### `action`
212    ///  The type of operation that the file chooser is performing.
213    ///
214    /// Readable | Writeable
215    ///
216    ///
217    /// #### `create-folders`
218    ///  Whether a file chooser not in [`FileChooserAction::Open`][crate::FileChooserAction::Open] mode
219    /// will offer the user to create new folders.
220    ///
221    /// Readable | Writeable
222    ///
223    ///
224    /// #### `filter`
225    ///  The current filter for selecting files that are displayed.
226    ///
227    /// Readable | Writeable
228    ///
229    ///
230    /// #### `filters`
231    ///  A `GListModel` containing the filters that have been
232    /// added with gtk_file_chooser_add_filter().
233    ///
234    /// The returned object should not be modified. It may
235    /// or may not be updated for later changes.
236    ///
237    /// Readable
238    ///
239    ///
240    /// #### `select-multiple`
241    ///  Whether to allow multiple files to be selected.
242    ///
243    /// Readable | Writeable
244    ///
245    ///
246    /// #### `shortcut-folders`
247    ///  A `GListModel` containing the shortcut folders that have been
248    /// added with gtk_file_chooser_add_shortcut_folder().
249    ///
250    /// The returned object should not be modified. It may
251    /// or may not be updated for later changes.
252    ///
253    /// Readable
254    /// </details>
255    ///
256    /// # Implements
257    ///
258    /// [`NativeDialogExt`][trait@crate::prelude::NativeDialogExt], [`trait@glib::ObjectExt`], [`FileChooserExt`][trait@crate::prelude::FileChooserExt], [`NativeDialogExtManual`][trait@crate::prelude::NativeDialogExtManual], [`FileChooserExtManual`][trait@crate::prelude::FileChooserExtManual]
259    #[doc(alias = "GtkFileChooserNative")]
260    pub struct FileChooserNative(Object<ffi::GtkFileChooserNative, ffi::GtkFileChooserNativeClass>) @extends NativeDialog, @implements FileChooser;
261
262    match fn {
263        type_ => || ffi::gtk_file_chooser_native_get_type(),
264    }
265}
266
267impl FileChooserNative {
268    /// Creates a new [`FileChooserNative`][crate::FileChooserNative].
269    ///
270    /// # Deprecated since 4.10
271    ///
272    /// Use [`FileDialog`][crate::FileDialog] instead
273    /// ## `title`
274    /// Title of the native
275    /// ## `parent`
276    /// Transient parent of the native
277    /// ## `action`
278    /// Open or save mode for the dialog
279    /// ## `accept_label`
280    /// text to go in the accept button, or [`None`] for the default
281    /// ## `cancel_label`
282    /// text to go in the cancel button, or [`None`] for the default
283    ///
284    /// # Returns
285    ///
286    /// a new [`FileChooserNative`][crate::FileChooserNative]
287    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
288    #[allow(deprecated)]
289    #[doc(alias = "gtk_file_chooser_native_new")]
290    pub fn new(
291        title: Option<&str>,
292        parent: Option<&impl IsA<Window>>,
293        action: FileChooserAction,
294        accept_label: Option<&str>,
295        cancel_label: Option<&str>,
296    ) -> FileChooserNative {
297        assert_initialized_main_thread!();
298        unsafe {
299            from_glib_full(ffi::gtk_file_chooser_native_new(
300                title.to_glib_none().0,
301                parent.map(|p| p.as_ref()).to_glib_none().0,
302                action.into_glib(),
303                accept_label.to_glib_none().0,
304                cancel_label.to_glib_none().0,
305            ))
306        }
307    }
308
309    // rustdoc-stripper-ignore-next
310    /// Creates a new builder-pattern struct instance to construct [`FileChooserNative`] objects.
311    ///
312    /// This method returns an instance of [`FileChooserNativeBuilder`](crate::builders::FileChooserNativeBuilder) which can be used to create [`FileChooserNative`] objects.
313    pub fn builder() -> FileChooserNativeBuilder {
314        FileChooserNativeBuilder::new()
315    }
316
317    /// Retrieves the custom label text for the accept button.
318    ///
319    /// # Deprecated since 4.10
320    ///
321    /// Use [`FileDialog`][crate::FileDialog] instead
322    ///
323    /// # Returns
324    ///
325    /// The custom label
326    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
327    #[allow(deprecated)]
328    #[doc(alias = "gtk_file_chooser_native_get_accept_label")]
329    #[doc(alias = "get_accept_label")]
330    #[doc(alias = "accept-label")]
331    pub fn accept_label(&self) -> Option<glib::GString> {
332        unsafe {
333            from_glib_none(ffi::gtk_file_chooser_native_get_accept_label(
334                self.to_glib_none().0,
335            ))
336        }
337    }
338
339    /// Retrieves the custom label text for the cancel button.
340    ///
341    /// # Deprecated since 4.10
342    ///
343    /// Use [`FileDialog`][crate::FileDialog] instead
344    ///
345    /// # Returns
346    ///
347    /// The custom label
348    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
349    #[allow(deprecated)]
350    #[doc(alias = "gtk_file_chooser_native_get_cancel_label")]
351    #[doc(alias = "get_cancel_label")]
352    #[doc(alias = "cancel-label")]
353    pub fn cancel_label(&self) -> Option<glib::GString> {
354        unsafe {
355            from_glib_none(ffi::gtk_file_chooser_native_get_cancel_label(
356                self.to_glib_none().0,
357            ))
358        }
359    }
360
361    /// Sets the custom label text for the accept button.
362    ///
363    /// If characters in @label are preceded by an underscore, they are
364    /// underlined. If you need a literal underscore character in a label,
365    /// use “__” (two underscores). The first underlined character represents
366    /// a keyboard accelerator called a mnemonic.
367    ///
368    /// Pressing Alt and that key should activate the button.
369    ///
370    /// # Deprecated since 4.10
371    ///
372    /// Use [`FileDialog`][crate::FileDialog] instead
373    /// ## `accept_label`
374    /// custom label
375    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
376    #[allow(deprecated)]
377    #[doc(alias = "gtk_file_chooser_native_set_accept_label")]
378    #[doc(alias = "accept-label")]
379    pub fn set_accept_label(&self, accept_label: Option<&str>) {
380        unsafe {
381            ffi::gtk_file_chooser_native_set_accept_label(
382                self.to_glib_none().0,
383                accept_label.to_glib_none().0,
384            );
385        }
386    }
387
388    /// Sets the custom label text for the cancel button.
389    ///
390    /// If characters in @label are preceded by an underscore, they are
391    /// underlined. If you need a literal underscore character in a label,
392    /// use “__” (two underscores). The first underlined character represents
393    /// a keyboard accelerator called a mnemonic.
394    ///
395    /// Pressing Alt and that key should activate the button.
396    ///
397    /// # Deprecated since 4.10
398    ///
399    /// Use [`FileDialog`][crate::FileDialog] instead
400    /// ## `cancel_label`
401    /// custom label
402    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
403    #[allow(deprecated)]
404    #[doc(alias = "gtk_file_chooser_native_set_cancel_label")]
405    #[doc(alias = "cancel-label")]
406    pub fn set_cancel_label(&self, cancel_label: Option<&str>) {
407        unsafe {
408            ffi::gtk_file_chooser_native_set_cancel_label(
409                self.to_glib_none().0,
410                cancel_label.to_glib_none().0,
411            );
412        }
413    }
414
415    #[doc(alias = "accept-label")]
416    pub fn connect_accept_label_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
417        unsafe extern "C" fn notify_accept_label_trampoline<F: Fn(&FileChooserNative) + 'static>(
418            this: *mut ffi::GtkFileChooserNative,
419            _param_spec: glib::ffi::gpointer,
420            f: glib::ffi::gpointer,
421        ) {
422            let f: &F = &*(f as *const F);
423            f(&from_glib_borrow(this))
424        }
425        unsafe {
426            let f: Box_<F> = Box_::new(f);
427            connect_raw(
428                self.as_ptr() as *mut _,
429                b"notify::accept-label\0".as_ptr() as *const _,
430                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
431                    notify_accept_label_trampoline::<F> as *const (),
432                )),
433                Box_::into_raw(f),
434            )
435        }
436    }
437
438    #[doc(alias = "cancel-label")]
439    pub fn connect_cancel_label_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
440        unsafe extern "C" fn notify_cancel_label_trampoline<F: Fn(&FileChooserNative) + 'static>(
441            this: *mut ffi::GtkFileChooserNative,
442            _param_spec: glib::ffi::gpointer,
443            f: glib::ffi::gpointer,
444        ) {
445            let f: &F = &*(f as *const F);
446            f(&from_glib_borrow(this))
447        }
448        unsafe {
449            let f: Box_<F> = Box_::new(f);
450            connect_raw(
451                self.as_ptr() as *mut _,
452                b"notify::cancel-label\0".as_ptr() as *const _,
453                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
454                    notify_cancel_label_trampoline::<F> as *const (),
455                )),
456                Box_::into_raw(f),
457            )
458        }
459    }
460}
461
462impl Default for FileChooserNative {
463    fn default() -> Self {
464        glib::object::Object::new::<Self>()
465    }
466}
467
468// rustdoc-stripper-ignore-next
469/// A [builder-pattern] type to construct [`FileChooserNative`] objects.
470///
471/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
472#[must_use = "The builder must be built to be used"]
473pub struct FileChooserNativeBuilder {
474    builder: glib::object::ObjectBuilder<'static, FileChooserNative>,
475}
476
477impl FileChooserNativeBuilder {
478    fn new() -> Self {
479        Self {
480            builder: glib::object::Object::builder(),
481        }
482    }
483
484    /// The text used for the label on the accept button in the dialog, or
485    /// [`None`] to use the default text.
486    pub fn accept_label(self, accept_label: impl Into<glib::GString>) -> Self {
487        Self {
488            builder: self.builder.property("accept-label", accept_label.into()),
489        }
490    }
491
492    /// The text used for the label on the cancel button in the dialog, or
493    /// [`None`] to use the default text.
494    pub fn cancel_label(self, cancel_label: impl Into<glib::GString>) -> Self {
495        Self {
496            builder: self.builder.property("cancel-label", cancel_label.into()),
497        }
498    }
499
500    /// Whether the window should be modal with respect to its transient parent.
501    pub fn modal(self, modal: bool) -> Self {
502        Self {
503            builder: self.builder.property("modal", modal),
504        }
505    }
506
507    /// The title of the dialog window
508    pub fn title(self, title: impl Into<glib::GString>) -> Self {
509        Self {
510            builder: self.builder.property("title", title.into()),
511        }
512    }
513
514    /// The transient parent of the dialog, or [`None`] for none.
515    pub fn transient_for(self, transient_for: &impl IsA<Window>) -> Self {
516        Self {
517            builder: self
518                .builder
519                .property("transient-for", transient_for.clone().upcast()),
520        }
521    }
522
523    /// Whether the window is currently visible.
524    pub fn visible(self, visible: bool) -> Self {
525        Self {
526            builder: self.builder.property("visible", visible),
527        }
528    }
529
530    /// The type of operation that the file chooser is performing.
531    /// Use [`FileDialog`][crate::FileDialog] instead
532    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
533    pub fn action(self, action: FileChooserAction) -> Self {
534        Self {
535            builder: self.builder.property("action", action),
536        }
537    }
538
539    /// Whether a file chooser not in [`FileChooserAction::Open`][crate::FileChooserAction::Open] mode
540    /// will offer the user to create new folders.
541    /// Use [`FileDialog`][crate::FileDialog] instead
542    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
543    pub fn create_folders(self, create_folders: bool) -> Self {
544        Self {
545            builder: self.builder.property("create-folders", create_folders),
546        }
547    }
548
549    /// The current filter for selecting files that are displayed.
550    /// Use [`FileDialog`][crate::FileDialog] instead
551    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
552    pub fn filter(self, filter: &FileFilter) -> Self {
553        Self {
554            builder: self.builder.property("filter", filter.clone()),
555        }
556    }
557
558    /// Whether to allow multiple files to be selected.
559    /// Use [`FileDialog`][crate::FileDialog] instead
560    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
561    pub fn select_multiple(self, select_multiple: bool) -> Self {
562        Self {
563            builder: self.builder.property("select-multiple", select_multiple),
564        }
565    }
566
567    // rustdoc-stripper-ignore-next
568    /// Build the [`FileChooserNative`].
569    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
570    pub fn build(self) -> FileChooserNative {
571        assert_initialized_main_thread!();
572        self.builder.build()
573    }
574}