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}