1 /* GTK - The GIMP Toolkit
2 * gtkfilechooser.c: Abstract interface for file selector GUIs
3 * Copyright (C) 2003, Red Hat, Inc.
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19 #include "config.h"
20 #include "gtkfilechooser.h"
21 #include "gtkfilechooserprivate.h"
22 #include "gtkintl.h"
23 #include "gtktypebuiltins.h"
24 #include "gtkprivate.h"
25 #include "gtkmarshalers.h"
26
27
28 /**
29 * SECTION:gtkfilechooser
30 * @Short_description: File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog
31 * @Title: GtkFileChooser
32 * @See_also: #GtkFileChooserDialog, #GtkFileChooserWidget, #GtkFileChooserButton
33 *
34 * #GtkFileChooser is an interface that can be implemented by file
35 * selection widgets. In GTK+, the main objects that implement this
36 * interface are #GtkFileChooserWidget, #GtkFileChooserDialog, and
37 * #GtkFileChooserButton. You do not need to write an object that
38 * implements the #GtkFileChooser interface unless you are trying to
39 * adapt an existing file selector to expose a standard programming
40 * interface.
41 *
42 * #GtkFileChooser allows for shortcuts to various places in the filesystem.
43 * In the default implementation these are displayed in the left pane. It
44 * may be a bit confusing at first that these shortcuts come from various
45 * sources and in various flavours, so lets explain the terminology here:
46 *
47 * - Bookmarks: are created by the user, by dragging folders from the
48 * right pane to the left pane, or by using the “Add”. Bookmarks
49 * can be renamed and deleted by the user.
50 *
51 * - Shortcuts: can be provided by the application. For example, a Paint
52 * program may want to add a shortcut for a Clipart folder. Shortcuts
53 * cannot be modified by the user.
54 *
55 * - Volumes: are provided by the underlying filesystem abstraction. They are
56 * the “roots” of the filesystem.
57 *
58 * # File Names and Encodings
59 *
60 * When the user is finished selecting files in a
61 * #GtkFileChooser, your program can get the selected names
62 * either as filenames or as URIs. For URIs, the normal escaping
63 * rules are applied if the URI contains non-ASCII characters.
64 * However, filenames are always returned in
65 * the character set specified by the
66 * `G_FILENAME_ENCODING` environment variable.
67 * Please see the GLib documentation for more details about this
68 * variable.
69 *
70 * This means that while you can pass the result of
71 * gtk_file_chooser_get_filename() to g_open() or g_fopen(),
72 * you may not be able to directly set it as the text of a
73 * #GtkLabel widget unless you convert it first to UTF-8,
74 * which all GTK+ widgets expect. You should use g_filename_to_utf8()
75 * to convert filenames into strings that can be passed to GTK+
76 * widgets.
77 *
78 * # Adding a Preview Widget
79 *
80 * You can add a custom preview widget to a file chooser and then
81 * get notification about when the preview needs to be updated.
82 * To install a preview widget, use
83 * gtk_file_chooser_set_preview_widget(). Then, connect to the
84 * #GtkFileChooser::update-preview signal to get notified when
85 * you need to update the contents of the preview.
86 *
87 * Your callback should use
88 * gtk_file_chooser_get_preview_filename() to see what needs
89 * previewing. Once you have generated the preview for the
90 * corresponding file, you must call
91 * gtk_file_chooser_set_preview_widget_active() with a boolean
92 * flag that indicates whether your callback could successfully
93 * generate a preview.
94 *
95 * ## Example: Using a Preview Widget ## {#gtkfilechooser-preview}
96 * |[<!-- language="C" -->
97 * {
98 * GtkImage *preview;
99 *
100 * ...
101 *
102 * preview = gtk_image_new ();
103 *
104 * gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
105 * g_signal_connect (my_file_chooser, "update-preview",
106 * G_CALLBACK (update_preview_cb), preview);
107 * }
108 *
109 * static void
110 * update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
111 * {
112 * GtkWidget *preview;
113 * char *filename;
114 * GdkPixbuf *pixbuf;
115 * gboolean have_preview;
116 *
117 * preview = GTK_WIDGET (data);
118 * filename = gtk_file_chooser_get_preview_filename (file_chooser);
119 *
120 * pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
121 * have_preview = (pixbuf != NULL);
122 * g_free (filename);
123 *
124 * gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
125 * if (pixbuf)
126 * g_object_unref (pixbuf);
127 *
128 * gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
129 * }
130 * ]|
131 *
132 * # Adding Extra Widgets
133 *
134 * You can add extra widgets to a file chooser to provide options
135 * that are not present in the default design. For example, you
136 * can add a toggle button to give the user the option to open a
137 * file in read-only mode. You can use
138 * gtk_file_chooser_set_extra_widget() to insert additional
139 * widgets in a file chooser.
140 *
141 * An example for adding extra widgets:
142 * |[<!-- language="C" -->
143 *
144 * GtkWidget *toggle;
145 *
146 * ...
147 *
148 * toggle = gtk_check_button_new_with_label ("Open file read-only");
149 * gtk_widget_show (toggle);
150 * gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
151 * }
152 * ]|
153 *
154 * If you want to set more than one extra widget in the file
155 * chooser, you can a container such as a #GtkBox or a #GtkGrid
156 * and include your widgets in it. Then, set the container as
157 * the whole extra widget.
158 */
159
160
161 typedef GtkFileChooserIface GtkFileChooserInterface;
162 G_DEFINE_INTERFACE (GtkFileChooser, gtk_file_chooser, G_TYPE_OBJECT);
163
164 static gboolean
confirm_overwrite_accumulator(GSignalInvocationHint * ihint,GValue * return_accu,const GValue * handler_return,gpointer dummy)165 confirm_overwrite_accumulator (GSignalInvocationHint *ihint,
166 GValue *return_accu,
167 const GValue *handler_return,
168 gpointer dummy)
169 {
170 gboolean continue_emission;
171 GtkFileChooserConfirmation conf;
172
173 conf = g_value_get_enum (handler_return);
174 g_value_set_enum (return_accu, conf);
175 continue_emission = (conf == GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM);
176
177 return continue_emission;
178 }
179
180 static void
gtk_file_chooser_default_init(GtkFileChooserInterface * iface)181 gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
182 {
183 GType iface_type = G_TYPE_FROM_INTERFACE (iface);
184
185 /**
186 * GtkFileChooser::current-folder-changed:
187 * @chooser: the object which received the signal.
188 *
189 * This signal is emitted when the current folder in a #GtkFileChooser
190 * changes. This can happen due to the user performing some action that
191 * changes folders, such as selecting a bookmark or visiting a folder on the
192 * file list. It can also happen as a result of calling a function to
193 * explicitly change the current folder in a file chooser.
194 *
195 * Normally you do not need to connect to this signal, unless you need to keep
196 * track of which folder a file chooser is showing.
197 *
198 * See also: gtk_file_chooser_set_current_folder(),
199 * gtk_file_chooser_get_current_folder(),
200 * gtk_file_chooser_set_current_folder_uri(),
201 * gtk_file_chooser_get_current_folder_uri().
202 */
203 g_signal_new (I_("current-folder-changed"),
204 iface_type,
205 G_SIGNAL_RUN_LAST,
206 G_STRUCT_OFFSET (GtkFileChooserIface, current_folder_changed),
207 NULL, NULL,
208 NULL,
209 G_TYPE_NONE, 0);
210
211 /**
212 * GtkFileChooser::selection-changed:
213 * @chooser: the object which received the signal.
214 *
215 * This signal is emitted when there is a change in the set of selected files
216 * in a #GtkFileChooser. This can happen when the user modifies the selection
217 * with the mouse or the keyboard, or when explicitly calling functions to
218 * change the selection.
219 *
220 * Normally you do not need to connect to this signal, as it is easier to wait
221 * for the file chooser to finish running, and then to get the list of
222 * selected files using the functions mentioned below.
223 *
224 * See also: gtk_file_chooser_select_filename(),
225 * gtk_file_chooser_unselect_filename(), gtk_file_chooser_get_filename(),
226 * gtk_file_chooser_get_filenames(), gtk_file_chooser_select_uri(),
227 * gtk_file_chooser_unselect_uri(), gtk_file_chooser_get_uri(),
228 * gtk_file_chooser_get_uris().
229 */
230 g_signal_new (I_("selection-changed"),
231 iface_type,
232 G_SIGNAL_RUN_LAST,
233 G_STRUCT_OFFSET (GtkFileChooserIface, selection_changed),
234 NULL, NULL,
235 NULL,
236 G_TYPE_NONE, 0);
237
238 /**
239 * GtkFileChooser::update-preview:
240 * @chooser: the object which received the signal.
241 *
242 * This signal is emitted when the preview in a file chooser should be
243 * regenerated. For example, this can happen when the currently selected file
244 * changes. You should use this signal if you want your file chooser to have
245 * a preview widget.
246 *
247 * Once you have installed a preview widget with
248 * gtk_file_chooser_set_preview_widget(), you should update it when this
249 * signal is emitted. You can use the functions
250 * gtk_file_chooser_get_preview_filename() or
251 * gtk_file_chooser_get_preview_uri() to get the name of the file to preview.
252 * Your widget may not be able to preview all kinds of files; your callback
253 * must call gtk_file_chooser_set_preview_widget_active() to inform the file
254 * chooser about whether the preview was generated successfully or not.
255 *
256 * Please see the example code in
257 * [Using a Preview Widget][gtkfilechooser-preview].
258 *
259 * See also: gtk_file_chooser_set_preview_widget(),
260 * gtk_file_chooser_set_preview_widget_active(),
261 * gtk_file_chooser_set_use_preview_label(),
262 * gtk_file_chooser_get_preview_filename(),
263 * gtk_file_chooser_get_preview_uri().
264 */
265 g_signal_new (I_("update-preview"),
266 iface_type,
267 G_SIGNAL_RUN_LAST,
268 G_STRUCT_OFFSET (GtkFileChooserIface, update_preview),
269 NULL, NULL,
270 NULL,
271 G_TYPE_NONE, 0);
272
273 /**
274 * GtkFileChooser::file-activated:
275 * @chooser: the object which received the signal.
276 *
277 * This signal is emitted when the user "activates" a file in the file
278 * chooser. This can happen by double-clicking on a file in the file list, or
279 * by pressing `Enter`.
280 *
281 * Normally you do not need to connect to this signal. It is used internally
282 * by #GtkFileChooserDialog to know when to activate the default button in the
283 * dialog.
284 *
285 * See also: gtk_file_chooser_get_filename(),
286 * gtk_file_chooser_get_filenames(), gtk_file_chooser_get_uri(),
287 * gtk_file_chooser_get_uris().
288 */
289 g_signal_new (I_("file-activated"),
290 iface_type,
291 G_SIGNAL_RUN_LAST,
292 G_STRUCT_OFFSET (GtkFileChooserIface, file_activated),
293 NULL, NULL,
294 NULL,
295 G_TYPE_NONE, 0);
296
297 /**
298 * GtkFileChooser::confirm-overwrite:
299 * @chooser: the object which received the signal.
300 *
301 * This signal gets emitted whenever it is appropriate to present a
302 * confirmation dialog when the user has selected a file name that
303 * already exists. The signal only gets emitted when the file
304 * chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode.
305 *
306 * Most applications just need to turn on the
307 * #GtkFileChooser:do-overwrite-confirmation property (or call the
308 * gtk_file_chooser_set_do_overwrite_confirmation() function), and
309 * they will automatically get a stock confirmation dialog.
310 * Applications which need to customize this behavior should do
311 * that, and also connect to the #GtkFileChooser::confirm-overwrite
312 * signal.
313 *
314 * A signal handler for this signal must return a
315 * #GtkFileChooserConfirmation value, which indicates the action to
316 * take. If the handler determines that the user wants to select a
317 * different filename, it should return
318 * %GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN. If it determines
319 * that the user is satisfied with his choice of file name, it
320 * should return %GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME.
321 * On the other hand, if it determines that the stock confirmation
322 * dialog should be used, it should return
323 * %GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM. The following example
324 * illustrates this.
325 *
326 * ## Custom confirmation ## {#gtkfilechooser-confirmation}
327 *
328 * |[<!-- language="C" -->
329 * static GtkFileChooserConfirmation
330 * confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data)
331 * {
332 * char *uri;
333 *
334 * uri = gtk_file_chooser_get_uri (chooser);
335 *
336 * if (is_uri_read_only (uri))
337 * {
338 * if (user_wants_to_replace_read_only_file (uri))
339 * return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME;
340 * else
341 * return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN;
342 * } else
343 * return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; // fall back to the default dialog
344 * }
345 *
346 * ...
347 *
348 * chooser = gtk_file_chooser_dialog_new (...);
349 *
350 * gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
351 * g_signal_connect (chooser, "confirm-overwrite",
352 * G_CALLBACK (confirm_overwrite_callback), NULL);
353 *
354 * if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT)
355 * save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser));
356 *
357 * gtk_widget_destroy (chooser);
358 * ]|
359 *
360 * Returns: a #GtkFileChooserConfirmation value that indicates which
361 * action to take after emitting the signal.
362 *
363 * Since: 2.8
364 */
365 g_signal_new (I_("confirm-overwrite"),
366 iface_type,
367 G_SIGNAL_RUN_LAST,
368 G_STRUCT_OFFSET (GtkFileChooserIface, confirm_overwrite),
369 confirm_overwrite_accumulator, NULL,
370 _gtk_marshal_ENUM__VOID,
371 GTK_TYPE_FILE_CHOOSER_CONFIRMATION, 0);
372
373 g_object_interface_install_property (iface,
374 g_param_spec_enum ("action",
375 P_("Action"),
376 P_("The type of operation that the file selector is performing"),
377 GTK_TYPE_FILE_CHOOSER_ACTION,
378 GTK_FILE_CHOOSER_ACTION_OPEN,
379 GTK_PARAM_READWRITE));
380 g_object_interface_install_property (iface,
381 g_param_spec_object ("filter",
382 P_("Filter"),
383 P_("The current filter for selecting which files are displayed"),
384 GTK_TYPE_FILE_FILTER,
385 GTK_PARAM_READWRITE));
386 g_object_interface_install_property (iface,
387 g_param_spec_boolean ("local-only",
388 P_("Local Only"),
389 P_("Whether the selected file(s) should be limited to local file: URLs"),
390 TRUE,
391 GTK_PARAM_READWRITE));
392 g_object_interface_install_property (iface,
393 g_param_spec_object ("preview-widget",
394 P_("Preview widget"),
395 P_("Application supplied widget for custom previews."),
396 GTK_TYPE_WIDGET,
397 GTK_PARAM_READWRITE));
398 g_object_interface_install_property (iface,
399 g_param_spec_boolean ("preview-widget-active",
400 P_("Preview Widget Active"),
401 P_("Whether the application supplied widget for custom previews should be shown."),
402 TRUE,
403 GTK_PARAM_READWRITE));
404 g_object_interface_install_property (iface,
405 g_param_spec_boolean ("use-preview-label",
406 P_("Use Preview Label"),
407 P_("Whether to display a stock label with the name of the previewed file."),
408 TRUE,
409 GTK_PARAM_READWRITE));
410 g_object_interface_install_property (iface,
411 g_param_spec_object ("extra-widget",
412 P_("Extra widget"),
413 P_("Application supplied widget for extra options."),
414 GTK_TYPE_WIDGET,
415 GTK_PARAM_READWRITE));
416 g_object_interface_install_property (iface,
417 g_param_spec_boolean ("select-multiple",
418 P_("Select Multiple"),
419 P_("Whether to allow multiple files to be selected"),
420 FALSE,
421 GTK_PARAM_READWRITE));
422
423 g_object_interface_install_property (iface,
424 g_param_spec_boolean ("show-hidden",
425 P_("Show Hidden"),
426 P_("Whether the hidden files and folders should be displayed"),
427 FALSE,
428 GTK_PARAM_READWRITE));
429
430 /**
431 * GtkFileChooser:do-overwrite-confirmation:
432 *
433 * Whether a file chooser in %GTK_FILE_CHOOSER_ACTION_SAVE mode
434 * will present an overwrite confirmation dialog if the user
435 * selects a file name that already exists.
436 *
437 * Since: 2.8
438 */
439 g_object_interface_install_property (iface,
440 g_param_spec_boolean ("do-overwrite-confirmation",
441 P_("Do overwrite confirmation"),
442 P_("Whether a file chooser in save mode "
443 "will present an overwrite confirmation dialog "
444 "if necessary."),
445 FALSE,
446 GTK_PARAM_READWRITE));
447
448 /**
449 * GtkFileChooser:create-folders:
450 *
451 * Whether a file chooser not in %GTK_FILE_CHOOSER_ACTION_OPEN mode
452 * will offer the user to create new folders.
453 *
454 * Since: 2.18
455 */
456 g_object_interface_install_property (iface,
457 g_param_spec_boolean ("create-folders",
458 P_("Allow folder creation"),
459 P_("Whether a file chooser not in open mode "
460 "will offer the user to create new folders."),
461 TRUE,
462 GTK_PARAM_READWRITE));
463 }
464
465 /**
466 * gtk_file_chooser_error_quark:
467 *
468 * Registers an error quark for #GtkFileChooser if necessary.
469 *
470 * Returns: The error quark used for #GtkFileChooser errors.
471 *
472 * Since: 2.4
473 **/
474 GQuark
gtk_file_chooser_error_quark(void)475 gtk_file_chooser_error_quark (void)
476 {
477 return g_quark_from_static_string ("gtk-file-chooser-error-quark");
478 }
479
480 /**
481 * gtk_file_chooser_set_action:
482 * @chooser: a #GtkFileChooser
483 * @action: the action that the file selector is performing
484 *
485 * Sets the type of operation that the chooser is performing; the
486 * user interface is adapted to suit the selected action. For example,
487 * an option to create a new folder might be shown if the action is
488 * %GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is
489 * %GTK_FILE_CHOOSER_ACTION_OPEN.
490 *
491 * Since: 2.4
492 **/
493 void
gtk_file_chooser_set_action(GtkFileChooser * chooser,GtkFileChooserAction action)494 gtk_file_chooser_set_action (GtkFileChooser *chooser,
495 GtkFileChooserAction action)
496 {
497 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
498
499 g_object_set (chooser, "action", action, NULL);
500 }
501
502 /**
503 * gtk_file_chooser_get_action:
504 * @chooser: a #GtkFileChooser
505 *
506 * Gets the type of operation that the file chooser is performing; see
507 * gtk_file_chooser_set_action().
508 *
509 * Returns: the action that the file selector is performing
510 *
511 * Since: 2.4
512 **/
513 GtkFileChooserAction
gtk_file_chooser_get_action(GtkFileChooser * chooser)514 gtk_file_chooser_get_action (GtkFileChooser *chooser)
515 {
516 GtkFileChooserAction action;
517
518 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
519
520 g_object_get (chooser, "action", &action, NULL);
521
522 return action;
523 }
524
525 /**
526 * gtk_file_chooser_set_local_only:
527 * @chooser: a #GtkFileChooser
528 * @local_only: %TRUE if only local files can be selected
529 *
530 * Sets whether only local files can be selected in the
531 * file selector. If @local_only is %TRUE (the default),
532 * then the selected file or files are guaranteed to be
533 * accessible through the operating systems native file
534 * system and therefore the application only
535 * needs to worry about the filename functions in
536 * #GtkFileChooser, like gtk_file_chooser_get_filename(),
537 * rather than the URI functions like
538 * gtk_file_chooser_get_uri(),
539 *
540 * On some systems non-native files may still be
541 * available using the native filesystem via a userspace
542 * filesystem (FUSE).
543 *
544 * Since: 2.4
545 **/
546 void
gtk_file_chooser_set_local_only(GtkFileChooser * chooser,gboolean local_only)547 gtk_file_chooser_set_local_only (GtkFileChooser *chooser,
548 gboolean local_only)
549 {
550 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
551
552 g_object_set (chooser, "local-only", local_only, NULL);
553 }
554
555 /**
556 * gtk_file_chooser_get_local_only:
557 * @chooser: a #GtkFileChooser
558 *
559 * Gets whether only local files can be selected in the
560 * file selector. See gtk_file_chooser_set_local_only()
561 *
562 * Returns: %TRUE if only local files can be selected.
563 *
564 * Since: 2.4
565 **/
566 gboolean
gtk_file_chooser_get_local_only(GtkFileChooser * chooser)567 gtk_file_chooser_get_local_only (GtkFileChooser *chooser)
568 {
569 gboolean local_only;
570
571 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
572
573 g_object_get (chooser, "local-only", &local_only, NULL);
574
575 return local_only;
576 }
577
578 /**
579 * gtk_file_chooser_set_select_multiple:
580 * @chooser: a #GtkFileChooser
581 * @select_multiple: %TRUE if multiple files can be selected.
582 *
583 * Sets whether multiple files can be selected in the file selector. This is
584 * only relevant if the action is set to be %GTK_FILE_CHOOSER_ACTION_OPEN or
585 * %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
586 *
587 * Since: 2.4
588 **/
589 void
gtk_file_chooser_set_select_multiple(GtkFileChooser * chooser,gboolean select_multiple)590 gtk_file_chooser_set_select_multiple (GtkFileChooser *chooser,
591 gboolean select_multiple)
592 {
593 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
594
595 g_object_set (chooser, "select-multiple", select_multiple, NULL);
596 }
597
598 /**
599 * gtk_file_chooser_get_select_multiple:
600 * @chooser: a #GtkFileChooser
601 *
602 * Gets whether multiple files can be selected in the file
603 * selector. See gtk_file_chooser_set_select_multiple().
604 *
605 * Returns: %TRUE if multiple files can be selected.
606 *
607 * Since: 2.4
608 **/
609 gboolean
gtk_file_chooser_get_select_multiple(GtkFileChooser * chooser)610 gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser)
611 {
612 gboolean select_multiple;
613
614 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
615
616 g_object_get (chooser, "select-multiple", &select_multiple, NULL);
617
618 return select_multiple;
619 }
620
621 /**
622 * gtk_file_chooser_set_create_folders:
623 * @chooser: a #GtkFileChooser
624 * @create_folders: %TRUE if the Create Folder button should be displayed
625 *
626 * Sets whether file choser will offer to create new folders.
627 * This is only relevant if the action is not set to be
628 * %GTK_FILE_CHOOSER_ACTION_OPEN.
629 *
630 * Since: 2.18
631 **/
632 void
gtk_file_chooser_set_create_folders(GtkFileChooser * chooser,gboolean create_folders)633 gtk_file_chooser_set_create_folders (GtkFileChooser *chooser,
634 gboolean create_folders)
635 {
636 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
637
638 g_object_set (chooser, "create-folders", create_folders, NULL);
639 }
640
641 /**
642 * gtk_file_chooser_get_create_folders:
643 * @chooser: a #GtkFileChooser
644 *
645 * Gets whether file choser will offer to create new folders.
646 * See gtk_file_chooser_set_create_folders().
647 *
648 * Returns: %TRUE if the Create Folder button should be displayed.
649 *
650 * Since: 2.18
651 **/
652 gboolean
gtk_file_chooser_get_create_folders(GtkFileChooser * chooser)653 gtk_file_chooser_get_create_folders (GtkFileChooser *chooser)
654 {
655 gboolean create_folders;
656
657 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
658
659 g_object_get (chooser, "create-folders", &create_folders, NULL);
660
661 return create_folders;
662 }
663
664 /**
665 * gtk_file_chooser_get_filename:
666 * @chooser: a #GtkFileChooser
667 *
668 * Gets the filename for the currently selected file in
669 * the file selector. The filename is returned as an absolute path. If
670 * multiple files are selected, one of the filenames will be returned at
671 * random.
672 *
673 * If the file chooser is in folder mode, this function returns the selected
674 * folder.
675 *
676 * Returns: (nullable) (type filename): The currently selected filename,
677 * or %NULL if no file is selected, or the selected file can't
678 * be represented with a local filename. Free with g_free().
679 *
680 * Since: 2.4
681 **/
682 gchar *
gtk_file_chooser_get_filename(GtkFileChooser * chooser)683 gtk_file_chooser_get_filename (GtkFileChooser *chooser)
684 {
685 GFile *file;
686 gchar *result = NULL;
687
688 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
689
690 file = gtk_file_chooser_get_file (chooser);
691
692 if (file)
693 {
694 result = g_file_get_path (file);
695 g_object_unref (file);
696 }
697
698 return result;
699 }
700
701 /**
702 * gtk_file_chooser_set_filename:
703 * @chooser: a #GtkFileChooser
704 * @filename: (type filename): the filename to set as current
705 *
706 * Sets @filename as the current filename for the file chooser, by changing to
707 * the file’s parent folder and actually selecting the file in list; all other
708 * files will be unselected. If the @chooser is in
709 * %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file’s base name will also appear in
710 * the dialog’s file name entry.
711 *
712 * Note that the file must exist, or nothing will be done except
713 * for the directory change.
714 *
715 * You should use this function only when implementing a save
716 * dialog for which you already have a file name to which
717 * the user may save. For example, when the user opens an existing file and
718 * then does Save As... to save a copy or
719 * a modified version. If you don’t have a file name already — for
720 * example, if the user just created a new file and is saving it for the first
721 * time, do not call this function. Instead, use something similar to this:
722 * |[<!-- language="C" -->
723 * if (document_is_new)
724 * {
725 * // the user just created a new document
726 * gtk_file_chooser_set_current_name (chooser, "Untitled document");
727 * }
728 * else
729 * {
730 * // the user edited an existing document
731 * gtk_file_chooser_set_filename (chooser, existing_filename);
732 * }
733 * ]|
734 *
735 * In the first case, the file chooser will present the user with useful suggestions
736 * as to where to save his new file. In the second case, the file’s existing location
737 * is already known, so the file chooser will use it.
738 *
739 * Returns: Not useful.
740 *
741 * Since: 2.4
742 **/
743 gboolean
gtk_file_chooser_set_filename(GtkFileChooser * chooser,const gchar * filename)744 gtk_file_chooser_set_filename (GtkFileChooser *chooser,
745 const gchar *filename)
746 {
747 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
748
749 gtk_file_chooser_unselect_all (chooser);
750 return gtk_file_chooser_select_filename (chooser, filename);
751 }
752
753 /**
754 * gtk_file_chooser_select_filename:
755 * @chooser: a #GtkFileChooser
756 * @filename: (type filename): the filename to select
757 *
758 * Selects a filename. If the file name isn’t in the current
759 * folder of @chooser, then the current folder of @chooser will
760 * be changed to the folder containing @filename.
761 *
762 * Returns: Not useful.
763 *
764 * See also: gtk_file_chooser_set_filename()
765 *
766 * Since: 2.4
767 **/
768 gboolean
gtk_file_chooser_select_filename(GtkFileChooser * chooser,const gchar * filename)769 gtk_file_chooser_select_filename (GtkFileChooser *chooser,
770 const gchar *filename)
771 {
772 GFile *file;
773 gboolean result;
774
775 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
776 g_return_val_if_fail (filename != NULL, FALSE);
777
778 file = g_file_new_for_path (filename);
779 result = gtk_file_chooser_select_file (chooser, file, NULL);
780 g_object_unref (file);
781
782 return result;
783 }
784
785 /**
786 * gtk_file_chooser_unselect_filename:
787 * @chooser: a #GtkFileChooser
788 * @filename: (type filename): the filename to unselect
789 *
790 * Unselects a currently selected filename. If the filename
791 * is not in the current directory, does not exist, or
792 * is otherwise not currently selected, does nothing.
793 *
794 * Since: 2.4
795 **/
796 void
gtk_file_chooser_unselect_filename(GtkFileChooser * chooser,const char * filename)797 gtk_file_chooser_unselect_filename (GtkFileChooser *chooser,
798 const char *filename)
799 {
800 GFile *file;
801
802 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
803 g_return_if_fail (filename != NULL);
804
805 file = g_file_new_for_path (filename);
806 gtk_file_chooser_unselect_file (chooser, file);
807 g_object_unref (file);
808 }
809
810 /* Converts a list of GFile* to a list of strings using the specified function */
811 static GSList *
files_to_strings(GSList * files,gchar * (* convert_func)(GFile * file))812 files_to_strings (GSList *files,
813 gchar * (*convert_func) (GFile *file))
814 {
815 GSList *strings;
816
817 strings = NULL;
818
819 for (; files; files = files->next)
820 {
821 GFile *file;
822 gchar *string;
823
824 file = files->data;
825 string = (* convert_func) (file);
826
827 if (string)
828 strings = g_slist_prepend (strings, string);
829 }
830
831 return g_slist_reverse (strings);
832 }
833
834 static gchar *
file_to_uri_with_native_path(GFile * file)835 file_to_uri_with_native_path (GFile *file)
836 {
837 gchar *result = NULL;
838 gchar *native;
839
840 native = g_file_get_path (file);
841 if (native)
842 {
843 result = g_filename_to_uri (native, NULL, NULL); /* NULL-GError */
844 g_free (native);
845 }
846
847 return result;
848 }
849
850 /**
851 * gtk_file_chooser_get_filenames:
852 * @chooser: a #GtkFileChooser
853 *
854 * Lists all the selected files and subfolders in the current folder of
855 * @chooser. The returned names are full absolute paths. If files in the current
856 * folder cannot be represented as local filenames they will be ignored. (See
857 * gtk_file_chooser_get_uris())
858 *
859 * Returns: (element-type filename) (transfer full): a #GSList
860 * containing the filenames of all selected files and subfolders in
861 * the current folder. Free the returned list with g_slist_free(),
862 * and the filenames with g_free().
863 *
864 * Since: 2.4
865 **/
866 GSList *
gtk_file_chooser_get_filenames(GtkFileChooser * chooser)867 gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
868 {
869 GSList *files, *result;
870
871 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
872
873 files = gtk_file_chooser_get_files (chooser);
874
875 result = files_to_strings (files, g_file_get_path);
876 g_slist_free_full (files, g_object_unref);
877
878 return result;
879 }
880
881 /**
882 * gtk_file_chooser_set_current_folder:
883 * @chooser: a #GtkFileChooser
884 * @filename: (type filename): the full path of the new current folder
885 *
886 * Sets the current folder for @chooser from a local filename.
887 * The user will be shown the full contents of the current folder,
888 * plus user interface elements for navigating to other folders.
889 *
890 * In general, you should not use this function. See the
891 * [section on setting up a file chooser dialog][gtkfilechooserdialog-setting-up]
892 * for the rationale behind this.
893 *
894 * Returns: Not useful.
895 *
896 * Since: 2.4
897 **/
898 gboolean
gtk_file_chooser_set_current_folder(GtkFileChooser * chooser,const gchar * filename)899 gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
900 const gchar *filename)
901 {
902 GFile *file;
903 gboolean result;
904
905 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
906 g_return_val_if_fail (filename != NULL, FALSE);
907
908 file = g_file_new_for_path (filename);
909 result = gtk_file_chooser_set_current_folder_file (chooser, file, NULL);
910 g_object_unref (file);
911
912 return result;
913 }
914
915 /**
916 * gtk_file_chooser_get_current_folder:
917 * @chooser: a #GtkFileChooser
918 *
919 * Gets the current folder of @chooser as a local filename.
920 * See gtk_file_chooser_set_current_folder().
921 *
922 * Note that this is the folder that the file chooser is currently displaying
923 * (e.g. "/home/username/Documents"), which is not the same
924 * as the currently-selected folder if the chooser is in
925 * %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER mode
926 * (e.g. "/home/username/Documents/selected-folder/". To get the
927 * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the
928 * usual way to get the selection.
929 *
930 * Returns: (nullable) (type filename): the full path of the current
931 * folder, or %NULL if the current path cannot be represented as a local
932 * filename. Free with g_free(). This function will also return
933 * %NULL if the file chooser was unable to load the last folder that
934 * was requested from it; for example, as would be for calling
935 * gtk_file_chooser_set_current_folder() on a nonexistent folder.
936 *
937 * Since: 2.4
938 **/
939 gchar *
gtk_file_chooser_get_current_folder(GtkFileChooser * chooser)940 gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
941 {
942 GFile *file;
943 gchar *filename;
944
945 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
946
947 file = gtk_file_chooser_get_current_folder_file (chooser);
948 if (!file)
949 return NULL;
950
951 filename = g_file_get_path (file);
952 g_object_unref (file);
953
954 return filename;
955 }
956
957 /**
958 * gtk_file_chooser_set_current_name:
959 * @chooser: a #GtkFileChooser
960 * @name: (type utf8): the filename to use, as a UTF-8 string
961 *
962 * Sets the current name in the file selector, as if entered
963 * by the user. Note that the name passed in here is a UTF-8
964 * string rather than a filename. This function is meant for
965 * such uses as a suggested name in a “Save As...” dialog. You can
966 * pass “Untitled.doc” or a similarly suitable suggestion for the @name.
967 *
968 * If you want to preselect a particular existing file, you should use
969 * gtk_file_chooser_set_filename() or gtk_file_chooser_set_uri() instead.
970 * Please see the documentation for those functions for an example of using
971 * gtk_file_chooser_set_current_name() as well.
972 *
973 * Since: 2.4
974 **/
975 void
gtk_file_chooser_set_current_name(GtkFileChooser * chooser,const gchar * name)976 gtk_file_chooser_set_current_name (GtkFileChooser *chooser,
977 const gchar *name)
978 {
979 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
980 g_return_if_fail (name != NULL);
981
982 GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_name (chooser, name);
983 }
984
985 /**
986 * gtk_file_chooser_get_current_name:
987 * @chooser: a #GtkFileChooser
988 *
989 * Gets the current name in the file selector, as entered by the user in the
990 * text entry for “Name”.
991 *
992 * This is meant to be used in save dialogs, to get the currently typed filename
993 * when the file itself does not exist yet. For example, an application that
994 * adds a custom extra widget to the file chooser for “file format” may want to
995 * change the extension of the typed filename based on the chosen format, say,
996 * from “.jpg” to “.png”.
997 *
998 * Returns: The raw text from the file chooser’s “Name” entry. Free this with
999 * g_free(). Note that this string is not a full pathname or URI; it is
1000 * whatever the contents of the entry are. Note also that this string is in
1001 * UTF-8 encoding, which is not necessarily the system’s encoding for filenames.
1002 *
1003 * Since: 3.10
1004 **/
1005 gchar *
gtk_file_chooser_get_current_name(GtkFileChooser * chooser)1006 gtk_file_chooser_get_current_name (GtkFileChooser *chooser)
1007 {
1008 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1009
1010 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_name (chooser);
1011 }
1012
1013 /**
1014 * gtk_file_chooser_get_uri:
1015 * @chooser: a #GtkFileChooser
1016 *
1017 * Gets the URI for the currently selected file in
1018 * the file selector. If multiple files are selected,
1019 * one of the filenames will be returned at random.
1020 *
1021 * If the file chooser is in folder mode, this function returns the selected
1022 * folder.
1023 *
1024 * Returns: (nullable) (transfer full): The currently selected URI, or %NULL
1025 * if no file is selected. If gtk_file_chooser_set_local_only() is set to
1026 * %TRUE (the default) a local URI will be returned for any FUSE locations.
1027 * Free with g_free()
1028 *
1029 * Since: 2.4
1030 **/
1031 gchar *
gtk_file_chooser_get_uri(GtkFileChooser * chooser)1032 gtk_file_chooser_get_uri (GtkFileChooser *chooser)
1033 {
1034 GFile *file;
1035 gchar *result = NULL;
1036
1037 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1038
1039 file = gtk_file_chooser_get_file (chooser);
1040 if (file)
1041 {
1042 if (gtk_file_chooser_get_local_only (chooser))
1043 result = file_to_uri_with_native_path (file);
1044 else
1045 result = g_file_get_uri (file);
1046
1047 g_object_unref (file);
1048 }
1049
1050 return result;
1051 }
1052
1053 /**
1054 * gtk_file_chooser_set_uri:
1055 * @chooser: a #GtkFileChooser
1056 * @uri: the URI to set as current
1057 *
1058 * Sets the file referred to by @uri as the current file for the file chooser,
1059 * by changing to the URI’s parent folder and actually selecting the URI in the
1060 * list. If the @chooser is %GTK_FILE_CHOOSER_ACTION_SAVE mode, the URI’s base
1061 * name will also appear in the dialog’s file name entry.
1062 *
1063 * Note that the URI must exist, or nothing will be done except for the
1064 * directory change.
1065 *
1066 * You should use this function only when implementing a save
1067 * dialog for which you already have a file name to which
1068 * the user may save. For example, when the user opens an existing file and then
1069 * does Save As... to save a copy or a
1070 * modified version. If you don’t have a file name already — for example,
1071 * if the user just created a new file and is saving it for the first time, do
1072 * not call this function. Instead, use something similar to this:
1073 * |[<!-- language="C" -->
1074 * if (document_is_new)
1075 * {
1076 * // the user just created a new document
1077 * gtk_file_chooser_set_current_name (chooser, "Untitled document");
1078 * }
1079 * else
1080 * {
1081 * // the user edited an existing document
1082 * gtk_file_chooser_set_uri (chooser, existing_uri);
1083 * }
1084 * ]|
1085 *
1086 *
1087 * In the first case, the file chooser will present the user with useful suggestions
1088 * as to where to save his new file. In the second case, the file’s existing location
1089 * is already known, so the file chooser will use it.
1090 *
1091 * Returns: Not useful.
1092 *
1093 * Since: 2.4
1094 **/
1095 gboolean
gtk_file_chooser_set_uri(GtkFileChooser * chooser,const char * uri)1096 gtk_file_chooser_set_uri (GtkFileChooser *chooser,
1097 const char *uri)
1098 {
1099 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1100
1101 gtk_file_chooser_unselect_all (chooser);
1102 return gtk_file_chooser_select_uri (chooser, uri);
1103 }
1104
1105 /**
1106 * gtk_file_chooser_select_uri:
1107 * @chooser: a #GtkFileChooser
1108 * @uri: the URI to select
1109 *
1110 * Selects the file to by @uri. If the URI doesn’t refer to a
1111 * file in the current folder of @chooser, then the current folder of
1112 * @chooser will be changed to the folder containing @filename.
1113 *
1114 * Returns: Not useful.
1115 *
1116 * Since: 2.4
1117 **/
1118 gboolean
gtk_file_chooser_select_uri(GtkFileChooser * chooser,const char * uri)1119 gtk_file_chooser_select_uri (GtkFileChooser *chooser,
1120 const char *uri)
1121 {
1122 GFile *file;
1123 gboolean result;
1124
1125 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1126 g_return_val_if_fail (uri != NULL, FALSE);
1127
1128 file = g_file_new_for_uri (uri);
1129 result = gtk_file_chooser_select_file (chooser, file, NULL);
1130 g_object_unref (file);
1131
1132 return result;
1133 }
1134
1135 /**
1136 * gtk_file_chooser_unselect_uri:
1137 * @chooser: a #GtkFileChooser
1138 * @uri: the URI to unselect
1139 *
1140 * Unselects the file referred to by @uri. If the file
1141 * is not in the current directory, does not exist, or
1142 * is otherwise not currently selected, does nothing.
1143 *
1144 * Since: 2.4
1145 **/
1146 void
gtk_file_chooser_unselect_uri(GtkFileChooser * chooser,const char * uri)1147 gtk_file_chooser_unselect_uri (GtkFileChooser *chooser,
1148 const char *uri)
1149 {
1150 GFile *file;
1151
1152 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1153 g_return_if_fail (uri != NULL);
1154
1155 file = g_file_new_for_uri (uri);
1156 gtk_file_chooser_unselect_file (chooser, file);
1157 g_object_unref (file);
1158 }
1159
1160 /**
1161 * gtk_file_chooser_select_all:
1162 * @chooser: a #GtkFileChooser
1163 *
1164 * Selects all the files in the current folder of a file chooser.
1165 *
1166 * Since: 2.4
1167 **/
1168 void
gtk_file_chooser_select_all(GtkFileChooser * chooser)1169 gtk_file_chooser_select_all (GtkFileChooser *chooser)
1170 {
1171 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1172
1173 GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_all (chooser);
1174 }
1175
1176 /**
1177 * gtk_file_chooser_unselect_all:
1178 * @chooser: a #GtkFileChooser
1179 *
1180 * Unselects all the files in the current folder of a file chooser.
1181 *
1182 * Since: 2.4
1183 **/
1184 void
gtk_file_chooser_unselect_all(GtkFileChooser * chooser)1185 gtk_file_chooser_unselect_all (GtkFileChooser *chooser)
1186 {
1187
1188 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1189
1190 GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_all (chooser);
1191 }
1192
1193 /**
1194 * gtk_file_chooser_get_uris:
1195 * @chooser: a #GtkFileChooser
1196 *
1197 * Lists all the selected files and subfolders in the current folder of
1198 * @chooser. The returned names are full absolute URIs.
1199 *
1200 * Returns: (element-type utf8) (transfer full): a #GSList containing the URIs of all selected
1201 * files and subfolders in the current folder. Free the returned list
1202 * with g_slist_free(), and the filenames with g_free().
1203 *
1204 * Since: 2.4
1205 **/
1206 GSList *
gtk_file_chooser_get_uris(GtkFileChooser * chooser)1207 gtk_file_chooser_get_uris (GtkFileChooser *chooser)
1208 {
1209 GSList *files, *result;
1210
1211 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1212
1213 files = gtk_file_chooser_get_files (chooser);
1214
1215 if (gtk_file_chooser_get_local_only (chooser))
1216 result = files_to_strings (files, file_to_uri_with_native_path);
1217 else
1218 result = files_to_strings (files, g_file_get_uri);
1219
1220 g_slist_free_full (files, g_object_unref);
1221
1222 return result;
1223 }
1224
1225 /**
1226 * gtk_file_chooser_set_current_folder_uri:
1227 * @chooser: a #GtkFileChooser
1228 * @uri: the URI for the new current folder
1229 *
1230 * Sets the current folder for @chooser from an URI.
1231 * The user will be shown the full contents of the current folder,
1232 * plus user interface elements for navigating to other folders.
1233 *
1234 * In general, you should not use this function. See the
1235 * [section on setting up a file chooser dialog][gtkfilechooserdialog-setting-up]
1236 * for the rationale behind this.
1237 *
1238 * Returns: %TRUE if the folder could be changed successfully, %FALSE
1239 * otherwise.
1240 *
1241 * Since: 2.4
1242 **/
1243 gboolean
gtk_file_chooser_set_current_folder_uri(GtkFileChooser * chooser,const gchar * uri)1244 gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser,
1245 const gchar *uri)
1246 {
1247 GFile *file;
1248 gboolean result;
1249
1250 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1251 g_return_val_if_fail (uri != NULL, FALSE);
1252
1253 file = g_file_new_for_uri (uri);
1254 result = gtk_file_chooser_set_current_folder_file (chooser, file, NULL);
1255 g_object_unref (file);
1256
1257 return result;
1258 }
1259
1260 /**
1261 * gtk_file_chooser_get_current_folder_uri:
1262 * @chooser: a #GtkFileChooser
1263 *
1264 * Gets the current folder of @chooser as an URI.
1265 * See gtk_file_chooser_set_current_folder_uri().
1266 *
1267 * Note that this is the folder that the file chooser is currently displaying
1268 * (e.g. "file:///home/username/Documents"), which is not the same
1269 * as the currently-selected folder if the chooser is in
1270 * %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER mode
1271 * (e.g. "file:///home/username/Documents/selected-folder/". To get the
1272 * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the
1273 * usual way to get the selection.
1274 *
1275 * Returns: (nullable) (transfer full): the URI for the current folder.
1276 * Free with g_free(). This function will also return %NULL if the file chooser
1277 * was unable to load the last folder that was requested from it; for example,
1278 * as would be for calling gtk_file_chooser_set_current_folder_uri() on a
1279 * nonexistent folder.
1280 *
1281 * Since: 2.4
1282 */
1283 gchar *
gtk_file_chooser_get_current_folder_uri(GtkFileChooser * chooser)1284 gtk_file_chooser_get_current_folder_uri (GtkFileChooser *chooser)
1285 {
1286 GFile *file;
1287 gchar *uri;
1288
1289 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1290
1291 file = gtk_file_chooser_get_current_folder_file (chooser);
1292 if (!file)
1293 return NULL;
1294
1295 uri = g_file_get_uri (file);
1296 g_object_unref (file);
1297
1298 return uri;
1299 }
1300
1301 /**
1302 * gtk_file_chooser_set_current_folder_file:
1303 * @chooser: a #GtkFileChooser
1304 * @file: the #GFile for the new folder
1305 * @error: (allow-none): location to store error, or %NULL.
1306 *
1307 * Sets the current folder for @chooser from a #GFile.
1308 * Internal function, see gtk_file_chooser_set_current_folder_uri().
1309 *
1310 * Returns: %TRUE if the folder could be changed successfully, %FALSE
1311 * otherwise.
1312 *
1313 * Since: 2.14
1314 **/
1315 gboolean
gtk_file_chooser_set_current_folder_file(GtkFileChooser * chooser,GFile * file,GError ** error)1316 gtk_file_chooser_set_current_folder_file (GtkFileChooser *chooser,
1317 GFile *file,
1318 GError **error)
1319 {
1320 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1321 g_return_val_if_fail (G_IS_FILE (file), FALSE);
1322 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1323
1324 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_folder (chooser, file, error);
1325 }
1326
1327 /**
1328 * gtk_file_chooser_get_current_folder_file:
1329 * @chooser: a #GtkFileChooser
1330 *
1331 * Gets the current folder of @chooser as #GFile.
1332 * See gtk_file_chooser_get_current_folder_uri().
1333 *
1334 * Returns: (transfer full): the #GFile for the current folder.
1335 *
1336 * Since: 2.14
1337 */
1338 GFile *
gtk_file_chooser_get_current_folder_file(GtkFileChooser * chooser)1339 gtk_file_chooser_get_current_folder_file (GtkFileChooser *chooser)
1340 {
1341 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1342
1343 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_folder (chooser);
1344 }
1345
1346 /**
1347 * gtk_file_chooser_select_file:
1348 * @chooser: a #GtkFileChooser
1349 * @file: the file to select
1350 * @error: (allow-none): location to store error, or %NULL
1351 *
1352 * Selects the file referred to by @file. An internal function. See
1353 * _gtk_file_chooser_select_uri().
1354 *
1355 * Returns: Not useful.
1356 *
1357 * Since: 2.14
1358 **/
1359 gboolean
gtk_file_chooser_select_file(GtkFileChooser * chooser,GFile * file,GError ** error)1360 gtk_file_chooser_select_file (GtkFileChooser *chooser,
1361 GFile *file,
1362 GError **error)
1363 {
1364 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1365 g_return_val_if_fail (G_IS_FILE (file), FALSE);
1366 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1367
1368 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_file (chooser, file, error);
1369 }
1370
1371 /**
1372 * gtk_file_chooser_unselect_file:
1373 * @chooser: a #GtkFileChooser
1374 * @file: a #GFile
1375 *
1376 * Unselects the file referred to by @file. If the file is not in the current
1377 * directory, does not exist, or is otherwise not currently selected, does nothing.
1378 *
1379 * Since: 2.14
1380 **/
1381 void
gtk_file_chooser_unselect_file(GtkFileChooser * chooser,GFile * file)1382 gtk_file_chooser_unselect_file (GtkFileChooser *chooser,
1383 GFile *file)
1384 {
1385 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1386 g_return_if_fail (G_IS_FILE (file));
1387
1388 GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_file (chooser, file);
1389 }
1390
1391 /**
1392 * gtk_file_chooser_get_files:
1393 * @chooser: a #GtkFileChooser
1394 *
1395 * Lists all the selected files and subfolders in the current folder of @chooser
1396 * as #GFile. An internal function, see gtk_file_chooser_get_uris().
1397 *
1398 * Returns: (element-type GFile) (transfer full): a #GSList
1399 * containing a #GFile for each selected file and subfolder in the
1400 * current folder. Free the returned list with g_slist_free(), and
1401 * the files with g_object_unref().
1402 *
1403 * Since: 2.14
1404 **/
1405 GSList *
gtk_file_chooser_get_files(GtkFileChooser * chooser)1406 gtk_file_chooser_get_files (GtkFileChooser *chooser)
1407 {
1408 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1409
1410 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_files (chooser);
1411 }
1412
1413 /**
1414 * gtk_file_chooser_set_file:
1415 * @chooser: a #GtkFileChooser
1416 * @file: the #GFile to set as current
1417 * @error: (allow-none): location to store the error, or %NULL to ignore errors.
1418 *
1419 * Sets @file as the current filename for the file chooser, by changing
1420 * to the file’s parent folder and actually selecting the file in list. If
1421 * the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file’s base name
1422 * will also appear in the dialog’s file name entry.
1423 *
1424 * If the file name isn’t in the current folder of @chooser, then the current
1425 * folder of @chooser will be changed to the folder containing @filename. This
1426 * is equivalent to a sequence of gtk_file_chooser_unselect_all() followed by
1427 * gtk_file_chooser_select_filename().
1428 *
1429 * Note that the file must exist, or nothing will be done except
1430 * for the directory change.
1431 *
1432 * If you are implementing a save dialog,
1433 * you should use this function if you already have a file name to which the
1434 * user may save; for example, when the user opens an existing file and then
1435 * does Save As... If you don’t have
1436 * a file name already — for example, if the user just created a new
1437 * file and is saving it for the first time, do not call this function.
1438 * Instead, use something similar to this:
1439 * |[<!-- language="C" -->
1440 * if (document_is_new)
1441 * {
1442 * // the user just created a new document
1443 * gtk_file_chooser_set_current_folder_file (chooser, default_file_for_saving);
1444 * gtk_file_chooser_set_current_name (chooser, "Untitled document");
1445 * }
1446 * else
1447 * {
1448 * // the user edited an existing document
1449 * gtk_file_chooser_set_file (chooser, existing_file);
1450 * }
1451 * ]|
1452 *
1453 * Returns: Not useful.
1454 *
1455 * Since: 2.14
1456 **/
1457 gboolean
gtk_file_chooser_set_file(GtkFileChooser * chooser,GFile * file,GError ** error)1458 gtk_file_chooser_set_file (GtkFileChooser *chooser,
1459 GFile *file,
1460 GError **error)
1461 {
1462 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1463 g_return_val_if_fail (G_IS_FILE (file), FALSE);
1464 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1465
1466 gtk_file_chooser_unselect_all (chooser);
1467 return gtk_file_chooser_select_file (chooser, file, error);
1468 }
1469
1470 /**
1471 * gtk_file_chooser_get_file:
1472 * @chooser: a #GtkFileChooser
1473 *
1474 * Gets the #GFile for the currently selected file in
1475 * the file selector. If multiple files are selected,
1476 * one of the files will be returned at random.
1477 *
1478 * If the file chooser is in folder mode, this function returns the selected
1479 * folder.
1480 *
1481 * Returns: (transfer full): a selected #GFile. You own the returned file;
1482 * use g_object_unref() to release it.
1483 *
1484 * Since: 2.14
1485 **/
1486 GFile *
gtk_file_chooser_get_file(GtkFileChooser * chooser)1487 gtk_file_chooser_get_file (GtkFileChooser *chooser)
1488 {
1489 GSList *list;
1490 GFile *result = NULL;
1491
1492 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1493
1494 list = gtk_file_chooser_get_files (chooser);
1495 if (list)
1496 {
1497 result = list->data;
1498 list = g_slist_delete_link (list, list);
1499
1500 g_slist_free_full (list, g_object_unref);
1501 }
1502
1503 return result;
1504 }
1505
1506 /**
1507 * _gtk_file_chooser_get_file_system:
1508 * @chooser: a #GtkFileChooser
1509 *
1510 * Gets the #GtkFileSystem of @chooser; this is an internal
1511 * implementation detail, used for conversion between paths
1512 * and filenames and URIs.
1513 *
1514 * Returns: the file system for @chooser.
1515 *
1516 * Since: 2.4
1517 **/
1518 GtkFileSystem *
_gtk_file_chooser_get_file_system(GtkFileChooser * chooser)1519 _gtk_file_chooser_get_file_system (GtkFileChooser *chooser)
1520 {
1521 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1522
1523 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_file_system (chooser);
1524 }
1525
1526 /* Preview widget
1527 */
1528 /**
1529 * gtk_file_chooser_set_preview_widget:
1530 * @chooser: a #GtkFileChooser
1531 * @preview_widget: widget for displaying preview.
1532 *
1533 * Sets an application-supplied widget to use to display a custom preview
1534 * of the currently selected file. To implement a preview, after setting the
1535 * preview widget, you connect to the #GtkFileChooser::update-preview
1536 * signal, and call gtk_file_chooser_get_preview_filename() or
1537 * gtk_file_chooser_get_preview_uri() on each change. If you can
1538 * display a preview of the new file, update your widget and
1539 * set the preview active using gtk_file_chooser_set_preview_widget_active().
1540 * Otherwise, set the preview inactive.
1541 *
1542 * When there is no application-supplied preview widget, or the
1543 * application-supplied preview widget is not active, the file chooser
1544 * will display no preview at all.
1545 *
1546 * Since: 2.4
1547 **/
1548 void
gtk_file_chooser_set_preview_widget(GtkFileChooser * chooser,GtkWidget * preview_widget)1549 gtk_file_chooser_set_preview_widget (GtkFileChooser *chooser,
1550 GtkWidget *preview_widget)
1551 {
1552 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1553
1554 g_object_set (chooser, "preview-widget", preview_widget, NULL);
1555 }
1556
1557 /**
1558 * gtk_file_chooser_get_preview_widget:
1559 * @chooser: a #GtkFileChooser
1560 *
1561 * Gets the current preview widget; see
1562 * gtk_file_chooser_set_preview_widget().
1563 *
1564 * Returns: (nullable) (transfer none): the current preview widget, or %NULL
1565 *
1566 * Since: 2.4
1567 **/
1568 GtkWidget *
gtk_file_chooser_get_preview_widget(GtkFileChooser * chooser)1569 gtk_file_chooser_get_preview_widget (GtkFileChooser *chooser)
1570 {
1571 GtkWidget *preview_widget;
1572
1573 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1574
1575 g_object_get (chooser, "preview-widget", &preview_widget, NULL);
1576
1577 /* Horrid hack; g_object_get() refs returned objects but
1578 * that contradicts the memory management conventions
1579 * for accessors.
1580 */
1581 if (preview_widget)
1582 g_object_unref (preview_widget);
1583
1584 return preview_widget;
1585 }
1586
1587 /**
1588 * gtk_file_chooser_set_preview_widget_active:
1589 * @chooser: a #GtkFileChooser
1590 * @active: whether to display the user-specified preview widget
1591 *
1592 * Sets whether the preview widget set by
1593 * gtk_file_chooser_set_preview_widget() should be shown for the
1594 * current filename. When @active is set to false, the file chooser
1595 * may display an internally generated preview of the current file
1596 * or it may display no preview at all. See
1597 * gtk_file_chooser_set_preview_widget() for more details.
1598 *
1599 * Since: 2.4
1600 **/
1601 void
gtk_file_chooser_set_preview_widget_active(GtkFileChooser * chooser,gboolean active)1602 gtk_file_chooser_set_preview_widget_active (GtkFileChooser *chooser,
1603 gboolean active)
1604 {
1605 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1606
1607 g_object_set (chooser, "preview-widget-active", active, NULL);
1608 }
1609
1610 /**
1611 * gtk_file_chooser_get_preview_widget_active:
1612 * @chooser: a #GtkFileChooser
1613 *
1614 * Gets whether the preview widget set by gtk_file_chooser_set_preview_widget()
1615 * should be shown for the current filename. See
1616 * gtk_file_chooser_set_preview_widget_active().
1617 *
1618 * Returns: %TRUE if the preview widget is active for the current filename.
1619 *
1620 * Since: 2.4
1621 **/
1622 gboolean
gtk_file_chooser_get_preview_widget_active(GtkFileChooser * chooser)1623 gtk_file_chooser_get_preview_widget_active (GtkFileChooser *chooser)
1624 {
1625 gboolean active;
1626
1627 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1628
1629 g_object_get (chooser, "preview-widget-active", &active, NULL);
1630
1631 return active;
1632 }
1633
1634 /**
1635 * gtk_file_chooser_set_use_preview_label:
1636 * @chooser: a #GtkFileChooser
1637 * @use_label: whether to display a stock label with the name of the previewed file
1638 *
1639 * Sets whether the file chooser should display a stock label with the name of
1640 * the file that is being previewed; the default is %TRUE. Applications that
1641 * want to draw the whole preview area themselves should set this to %FALSE and
1642 * display the name themselves in their preview widget.
1643 *
1644 * See also: gtk_file_chooser_set_preview_widget()
1645 *
1646 * Since: 2.4
1647 **/
1648 void
gtk_file_chooser_set_use_preview_label(GtkFileChooser * chooser,gboolean use_label)1649 gtk_file_chooser_set_use_preview_label (GtkFileChooser *chooser,
1650 gboolean use_label)
1651 {
1652 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1653
1654 g_object_set (chooser, "use-preview-label", use_label, NULL);
1655 }
1656
1657 /**
1658 * gtk_file_chooser_get_use_preview_label:
1659 * @chooser: a #GtkFileChooser
1660 *
1661 * Gets whether a stock label should be drawn with the name of the previewed
1662 * file. See gtk_file_chooser_set_use_preview_label().
1663 *
1664 * Returns: %TRUE if the file chooser is set to display a label with the
1665 * name of the previewed file, %FALSE otherwise.
1666 **/
1667 gboolean
gtk_file_chooser_get_use_preview_label(GtkFileChooser * chooser)1668 gtk_file_chooser_get_use_preview_label (GtkFileChooser *chooser)
1669 {
1670 gboolean use_label;
1671
1672 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1673
1674 g_object_get (chooser, "use-preview-label", &use_label, NULL);
1675
1676 return use_label;
1677 }
1678
1679 /**
1680 * gtk_file_chooser_get_preview_file:
1681 * @chooser: a #GtkFileChooser
1682 *
1683 * Gets the #GFile that should be previewed in a custom preview
1684 * Internal function, see gtk_file_chooser_get_preview_uri().
1685 *
1686 * Returns: (nullable) (transfer full): the #GFile for the file to preview,
1687 * or %NULL if no file is selected. Free with g_object_unref().
1688 *
1689 * Since: 2.14
1690 **/
1691 GFile *
gtk_file_chooser_get_preview_file(GtkFileChooser * chooser)1692 gtk_file_chooser_get_preview_file (GtkFileChooser *chooser)
1693 {
1694 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1695
1696 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_preview_file (chooser);
1697 }
1698
1699 /**
1700 * _gtk_file_chooser_add_shortcut_folder:
1701 * @chooser: a #GtkFileChooser
1702 * @file: file for the folder to add
1703 * @error: (allow-none): location to store error, or %NULL
1704 *
1705 * Adds a folder to be displayed with the shortcut folders in a file chooser.
1706 * Internal function, see gtk_file_chooser_add_shortcut_folder().
1707 *
1708 * Returns: %TRUE if the folder could be added successfully, %FALSE
1709 * otherwise.
1710 *
1711 * Since: 2.4
1712 **/
1713 gboolean
_gtk_file_chooser_add_shortcut_folder(GtkFileChooser * chooser,GFile * file,GError ** error)1714 _gtk_file_chooser_add_shortcut_folder (GtkFileChooser *chooser,
1715 GFile *file,
1716 GError **error)
1717 {
1718 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1719 g_return_val_if_fail (G_IS_FILE (file), FALSE);
1720
1721 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_shortcut_folder (chooser, file, error);
1722 }
1723
1724 /**
1725 * _gtk_file_chooser_remove_shortcut_folder:
1726 * @chooser: a #GtkFileChooser
1727 * @file: file for the folder to remove
1728 * @error: (allow-none): location to store error, or %NULL
1729 *
1730 * Removes a folder from the shortcut folders in a file chooser. Internal
1731 * function, see gtk_file_chooser_remove_shortcut_folder().
1732 *
1733 * Returns: %TRUE if the folder could be removed successfully, %FALSE
1734 * otherwise.
1735 *
1736 * Since: 2.4
1737 **/
1738 gboolean
_gtk_file_chooser_remove_shortcut_folder(GtkFileChooser * chooser,GFile * file,GError ** error)1739 _gtk_file_chooser_remove_shortcut_folder (GtkFileChooser *chooser,
1740 GFile *file,
1741 GError **error)
1742 {
1743 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1744 g_return_val_if_fail (G_IS_FILE (file), FALSE);
1745
1746 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_shortcut_folder (chooser, file, error);
1747 }
1748
1749 /**
1750 * gtk_file_chooser_get_preview_filename:
1751 * @chooser: a #GtkFileChooser
1752 *
1753 * Gets the filename that should be previewed in a custom preview
1754 * widget. See gtk_file_chooser_set_preview_widget().
1755 *
1756 * Returns: (nullable) (type filename): the filename to preview, or %NULL if
1757 * no file is selected, or if the selected file cannot be represented
1758 * as a local filename. Free with g_free()
1759 *
1760 * Since: 2.4
1761 **/
1762 char *
gtk_file_chooser_get_preview_filename(GtkFileChooser * chooser)1763 gtk_file_chooser_get_preview_filename (GtkFileChooser *chooser)
1764 {
1765 GFile *file;
1766 gchar *result = NULL;
1767
1768 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1769
1770 file = gtk_file_chooser_get_preview_file (chooser);
1771 if (file)
1772 {
1773 result = g_file_get_path (file);
1774 g_object_unref (file);
1775 }
1776
1777 return result;
1778 }
1779
1780 /**
1781 * gtk_file_chooser_get_preview_uri:
1782 * @chooser: a #GtkFileChooser
1783 *
1784 * Gets the URI that should be previewed in a custom preview
1785 * widget. See gtk_file_chooser_set_preview_widget().
1786 *
1787 * Returns: (nullable) (transfer full): the URI for the file to preview,
1788 * or %NULL if no file is selected. Free with g_free().
1789 *
1790 * Since: 2.4
1791 **/
1792 char *
gtk_file_chooser_get_preview_uri(GtkFileChooser * chooser)1793 gtk_file_chooser_get_preview_uri (GtkFileChooser *chooser)
1794 {
1795 GFile *file;
1796 gchar *result = NULL;
1797
1798 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1799
1800 file = gtk_file_chooser_get_preview_file (chooser);
1801 if (file)
1802 {
1803 result = g_file_get_uri (file);
1804 g_object_unref (file);
1805 }
1806
1807 return result;
1808 }
1809
1810 /**
1811 * gtk_file_chooser_set_extra_widget:
1812 * @chooser: a #GtkFileChooser
1813 * @extra_widget: widget for extra options
1814 *
1815 * Sets an application-supplied widget to provide extra options to the user.
1816 *
1817 * Since: 2.4
1818 **/
1819 void
gtk_file_chooser_set_extra_widget(GtkFileChooser * chooser,GtkWidget * extra_widget)1820 gtk_file_chooser_set_extra_widget (GtkFileChooser *chooser,
1821 GtkWidget *extra_widget)
1822 {
1823 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1824
1825 g_object_set (chooser, "extra-widget", extra_widget, NULL);
1826 }
1827
1828 /**
1829 * gtk_file_chooser_get_extra_widget:
1830 * @chooser: a #GtkFileChooser
1831 *
1832 * Gets the current extra widget; see
1833 * gtk_file_chooser_set_extra_widget().
1834 *
1835 * Returns: (nullable) (transfer none): the current extra widget, or %NULL
1836 *
1837 * Since: 2.4
1838 **/
1839 GtkWidget *
gtk_file_chooser_get_extra_widget(GtkFileChooser * chooser)1840 gtk_file_chooser_get_extra_widget (GtkFileChooser *chooser)
1841 {
1842 GtkWidget *extra_widget;
1843
1844 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1845
1846 g_object_get (chooser, "extra-widget", &extra_widget, NULL);
1847
1848 /* Horrid hack; g_object_get() refs returned objects but
1849 * that contradicts the memory management conventions
1850 * for accessors.
1851 */
1852 if (extra_widget)
1853 g_object_unref (extra_widget);
1854
1855 return extra_widget;
1856 }
1857
1858 /**
1859 * gtk_file_chooser_add_filter:
1860 * @chooser: a #GtkFileChooser
1861 * @filter: (transfer full): a #GtkFileFilter
1862 *
1863 * Adds @filter to the list of filters that the user can select between.
1864 * When a filter is selected, only files that are passed by that
1865 * filter are displayed.
1866 *
1867 * Note that the @chooser takes ownership of the filter, so you have to
1868 * ref and sink it if you want to keep a reference.
1869 *
1870 * Since: 2.4
1871 **/
1872 void
gtk_file_chooser_add_filter(GtkFileChooser * chooser,GtkFileFilter * filter)1873 gtk_file_chooser_add_filter (GtkFileChooser *chooser,
1874 GtkFileFilter *filter)
1875 {
1876 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1877
1878 GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_filter (chooser, filter);
1879 }
1880
1881 /**
1882 * gtk_file_chooser_remove_filter:
1883 * @chooser: a #GtkFileChooser
1884 * @filter: a #GtkFileFilter
1885 *
1886 * Removes @filter from the list of filters that the user can select between.
1887 *
1888 * Since: 2.4
1889 **/
1890 void
gtk_file_chooser_remove_filter(GtkFileChooser * chooser,GtkFileFilter * filter)1891 gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
1892 GtkFileFilter *filter)
1893 {
1894 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1895
1896 GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_filter (chooser, filter);
1897 }
1898
1899 /**
1900 * gtk_file_chooser_list_filters:
1901 * @chooser: a #GtkFileChooser
1902 *
1903 * Lists the current set of user-selectable filters; see
1904 * gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter().
1905 *
1906 * Returns: (element-type GtkFileFilter) (transfer container): a
1907 * #GSList containing the current set of user selectable filters. The
1908 * contents of the list are owned by GTK+, but you must free the list
1909 * itself with g_slist_free() when you are done with it.
1910 *
1911 * Since: 2.4
1912 **/
1913 GSList *
gtk_file_chooser_list_filters(GtkFileChooser * chooser)1914 gtk_file_chooser_list_filters (GtkFileChooser *chooser)
1915 {
1916 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1917
1918 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->list_filters (chooser);
1919 }
1920
1921 /**
1922 * gtk_file_chooser_set_filter:
1923 * @chooser: a #GtkFileChooser
1924 * @filter: a #GtkFileFilter
1925 *
1926 * Sets the current filter; only the files that pass the
1927 * filter will be displayed. If the user-selectable list of filters
1928 * is non-empty, then the filter should be one of the filters
1929 * in that list. Setting the current filter when the list of
1930 * filters is empty is useful if you want to restrict the displayed
1931 * set of files without letting the user change it.
1932 *
1933 * Since: 2.4
1934 **/
1935 void
gtk_file_chooser_set_filter(GtkFileChooser * chooser,GtkFileFilter * filter)1936 gtk_file_chooser_set_filter (GtkFileChooser *chooser,
1937 GtkFileFilter *filter)
1938 {
1939 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1940 g_return_if_fail (GTK_IS_FILE_FILTER (filter));
1941
1942 g_object_set (chooser, "filter", filter, NULL);
1943 }
1944
1945 /**
1946 * gtk_file_chooser_get_filter:
1947 * @chooser: a #GtkFileChooser
1948 *
1949 * Gets the current filter; see gtk_file_chooser_set_filter().
1950 *
1951 * Returns: (nullable) (transfer none): the current filter, or %NULL
1952 *
1953 * Since: 2.4
1954 **/
1955 GtkFileFilter *
gtk_file_chooser_get_filter(GtkFileChooser * chooser)1956 gtk_file_chooser_get_filter (GtkFileChooser *chooser)
1957 {
1958 GtkFileFilter *filter;
1959
1960 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1961
1962 g_object_get (chooser, "filter", &filter, NULL);
1963 /* Horrid hack; g_object_get() refs returned objects but
1964 * that contradicts the memory management conventions
1965 * for accessors.
1966 */
1967 if (filter)
1968 g_object_unref (filter);
1969
1970 return filter;
1971 }
1972
1973 /**
1974 * gtk_file_chooser_add_shortcut_folder:
1975 * @chooser: a #GtkFileChooser
1976 * @folder: (type filename): filename of the folder to add
1977 * @error: (allow-none): location to store error, or %NULL
1978 *
1979 * Adds a folder to be displayed with the shortcut folders in a file chooser.
1980 * Note that shortcut folders do not get saved, as they are provided by the
1981 * application. For example, you can use this to add a
1982 * “/usr/share/mydrawprogram/Clipart” folder to the volume list.
1983 *
1984 * Returns: %TRUE if the folder could be added successfully, %FALSE
1985 * otherwise. In the latter case, the @error will be set as appropriate.
1986 *
1987 * Since: 2.4
1988 **/
1989 gboolean
gtk_file_chooser_add_shortcut_folder(GtkFileChooser * chooser,const char * folder,GError ** error)1990 gtk_file_chooser_add_shortcut_folder (GtkFileChooser *chooser,
1991 const char *folder,
1992 GError **error)
1993 {
1994 GFile *file;
1995 gboolean result;
1996
1997 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1998 g_return_val_if_fail (folder != NULL, FALSE);
1999
2000 file = g_file_new_for_path (folder);
2001 result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_shortcut_folder (chooser, file, error);
2002 g_object_unref (file);
2003
2004 return result;
2005 }
2006
2007 /**
2008 * gtk_file_chooser_remove_shortcut_folder:
2009 * @chooser: a #GtkFileChooser
2010 * @folder: (type filename): filename of the folder to remove
2011 * @error: (allow-none): location to store error, or %NULL
2012 *
2013 * Removes a folder from a file chooser’s list of shortcut folders.
2014 *
2015 * Returns: %TRUE if the operation succeeds, %FALSE otherwise.
2016 * In the latter case, the @error will be set as appropriate.
2017 *
2018 * See also: gtk_file_chooser_add_shortcut_folder()
2019 *
2020 * Since: 2.4
2021 **/
2022 gboolean
gtk_file_chooser_remove_shortcut_folder(GtkFileChooser * chooser,const char * folder,GError ** error)2023 gtk_file_chooser_remove_shortcut_folder (GtkFileChooser *chooser,
2024 const char *folder,
2025 GError **error)
2026 {
2027 GFile *file;
2028 gboolean result;
2029
2030 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2031 g_return_val_if_fail (folder != NULL, FALSE);
2032
2033 file = g_file_new_for_path (folder);
2034 result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_shortcut_folder (chooser, file, error);
2035 g_object_unref (file);
2036
2037 return result;
2038 }
2039
2040 /**
2041 * gtk_file_chooser_list_shortcut_folders:
2042 * @chooser: a #GtkFileChooser
2043 *
2044 * Queries the list of shortcut folders in the file chooser, as set by
2045 * gtk_file_chooser_add_shortcut_folder().
2046 *
2047 * Returns: (nullable) (element-type filename) (transfer full): A list
2048 * of folder filenames, or %NULL if there are no shortcut folders.
2049 * Free the returned list with g_slist_free(), and the filenames with
2050 * g_free().
2051 *
2052 * Since: 2.4
2053 **/
2054 GSList *
gtk_file_chooser_list_shortcut_folders(GtkFileChooser * chooser)2055 gtk_file_chooser_list_shortcut_folders (GtkFileChooser *chooser)
2056 {
2057 GSList *folders;
2058 GSList *result;
2059
2060 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2061
2062 folders = _gtk_file_chooser_list_shortcut_folder_files (chooser);
2063
2064 result = files_to_strings (folders, g_file_get_path);
2065 g_slist_free_full (folders, g_object_unref);
2066
2067 return result;
2068 }
2069
2070 /**
2071 * gtk_file_chooser_add_shortcut_folder_uri:
2072 * @chooser: a #GtkFileChooser
2073 * @uri: URI of the folder to add
2074 * @error: (allow-none): location to store error, or %NULL
2075 *
2076 * Adds a folder URI to be displayed with the shortcut folders in a file
2077 * chooser. Note that shortcut folders do not get saved, as they are provided
2078 * by the application. For example, you can use this to add a
2079 * “file:///usr/share/mydrawprogram/Clipart” folder to the volume list.
2080 *
2081 * Returns: %TRUE if the folder could be added successfully, %FALSE
2082 * otherwise. In the latter case, the @error will be set as appropriate.
2083 *
2084 * Since: 2.4
2085 **/
2086 gboolean
gtk_file_chooser_add_shortcut_folder_uri(GtkFileChooser * chooser,const char * uri,GError ** error)2087 gtk_file_chooser_add_shortcut_folder_uri (GtkFileChooser *chooser,
2088 const char *uri,
2089 GError **error)
2090 {
2091 GFile *file;
2092 gboolean result;
2093
2094 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2095 g_return_val_if_fail (uri != NULL, FALSE);
2096
2097 file = g_file_new_for_uri (uri);
2098 result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_shortcut_folder (chooser, file, error);
2099 g_object_unref (file);
2100
2101 return result;
2102 }
2103
2104 /**
2105 * gtk_file_chooser_remove_shortcut_folder_uri:
2106 * @chooser: a #GtkFileChooser
2107 * @uri: URI of the folder to remove
2108 * @error: (allow-none): location to store error, or %NULL
2109 *
2110 * Removes a folder URI from a file chooser’s list of shortcut folders.
2111 *
2112 * Returns: %TRUE if the operation succeeds, %FALSE otherwise.
2113 * In the latter case, the @error will be set as appropriate.
2114 *
2115 * See also: gtk_file_chooser_add_shortcut_folder_uri()
2116 *
2117 * Since: 2.4
2118 **/
2119 gboolean
gtk_file_chooser_remove_shortcut_folder_uri(GtkFileChooser * chooser,const char * uri,GError ** error)2120 gtk_file_chooser_remove_shortcut_folder_uri (GtkFileChooser *chooser,
2121 const char *uri,
2122 GError **error)
2123 {
2124 GFile *file;
2125 gboolean result;
2126
2127 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2128 g_return_val_if_fail (uri != NULL, FALSE);
2129
2130 file = g_file_new_for_uri (uri);
2131 result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_shortcut_folder (chooser, file, error);
2132 g_object_unref (file);
2133
2134 return result;
2135 }
2136
2137 /**
2138 * gtk_file_chooser_list_shortcut_folder_uris:
2139 * @chooser: a #GtkFileChooser
2140 *
2141 * Queries the list of shortcut folders in the file chooser, as set by
2142 * gtk_file_chooser_add_shortcut_folder_uri().
2143 *
2144 * Returns: (nullable) (element-type utf8) (transfer full): A list of
2145 * folder URIs, or %NULL if there are no shortcut folders. Free the
2146 * returned list with g_slist_free(), and the URIs with g_free().
2147 *
2148 * Since: 2.4
2149 **/
2150 GSList *
gtk_file_chooser_list_shortcut_folder_uris(GtkFileChooser * chooser)2151 gtk_file_chooser_list_shortcut_folder_uris (GtkFileChooser *chooser)
2152 {
2153 GSList *folders;
2154 GSList *result;
2155
2156 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2157
2158 folders = _gtk_file_chooser_list_shortcut_folder_files (chooser);
2159
2160 result = files_to_strings (folders, g_file_get_uri);
2161 g_slist_free_full (folders, g_object_unref);
2162
2163 return result;
2164 }
2165
2166 GSList *
_gtk_file_chooser_list_shortcut_folder_files(GtkFileChooser * chooser)2167 _gtk_file_chooser_list_shortcut_folder_files (GtkFileChooser *chooser)
2168 {
2169 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2170
2171 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->list_shortcut_folders (chooser);
2172 }
2173
2174 /**
2175 * gtk_file_chooser_set_show_hidden:
2176 * @chooser: a #GtkFileChooser
2177 * @show_hidden: %TRUE if hidden files and folders should be displayed.
2178 *
2179 * Sets whether hidden files and folders are displayed in the file selector.
2180 *
2181 * Since: 2.6
2182 **/
2183 void
gtk_file_chooser_set_show_hidden(GtkFileChooser * chooser,gboolean show_hidden)2184 gtk_file_chooser_set_show_hidden (GtkFileChooser *chooser,
2185 gboolean show_hidden)
2186 {
2187 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2188
2189 g_object_set (chooser, "show-hidden", show_hidden, NULL);
2190 }
2191
2192 /**
2193 * gtk_file_chooser_get_show_hidden:
2194 * @chooser: a #GtkFileChooser
2195 *
2196 * Gets whether hidden files and folders are displayed in the file selector.
2197 * See gtk_file_chooser_set_show_hidden().
2198 *
2199 * Returns: %TRUE if hidden files and folders are displayed.
2200 *
2201 * Since: 2.6
2202 **/
2203 gboolean
gtk_file_chooser_get_show_hidden(GtkFileChooser * chooser)2204 gtk_file_chooser_get_show_hidden (GtkFileChooser *chooser)
2205 {
2206 gboolean show_hidden;
2207
2208 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2209
2210 g_object_get (chooser, "show-hidden", &show_hidden, NULL);
2211
2212 return show_hidden;
2213 }
2214
2215 /**
2216 * gtk_file_chooser_set_do_overwrite_confirmation:
2217 * @chooser: a #GtkFileChooser
2218 * @do_overwrite_confirmation: whether to confirm overwriting in save mode
2219 *
2220 * Sets whether a file chooser in %GTK_FILE_CHOOSER_ACTION_SAVE mode will present
2221 * a confirmation dialog if the user types a file name that already exists. This
2222 * is %FALSE by default.
2223 *
2224 * If set to %TRUE, the @chooser will emit the
2225 * #GtkFileChooser::confirm-overwrite signal when appropriate.
2226 *
2227 * If all you need is the stock confirmation dialog, set this property to %TRUE.
2228 * You can override the way confirmation is done by actually handling the
2229 * #GtkFileChooser::confirm-overwrite signal; please refer to its documentation
2230 * for the details.
2231 *
2232 * Since: 2.8
2233 **/
2234 void
gtk_file_chooser_set_do_overwrite_confirmation(GtkFileChooser * chooser,gboolean do_overwrite_confirmation)2235 gtk_file_chooser_set_do_overwrite_confirmation (GtkFileChooser *chooser,
2236 gboolean do_overwrite_confirmation)
2237 {
2238 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2239
2240 g_object_set (chooser, "do-overwrite-confirmation", do_overwrite_confirmation, NULL);
2241 }
2242
2243 /**
2244 * gtk_file_chooser_get_do_overwrite_confirmation:
2245 * @chooser: a #GtkFileChooser
2246 *
2247 * Queries whether a file chooser is set to confirm for overwriting when the user
2248 * types a file name that already exists.
2249 *
2250 * Returns: %TRUE if the file chooser will present a confirmation dialog;
2251 * %FALSE otherwise.
2252 *
2253 * Since: 2.8
2254 **/
2255 gboolean
gtk_file_chooser_get_do_overwrite_confirmation(GtkFileChooser * chooser)2256 gtk_file_chooser_get_do_overwrite_confirmation (GtkFileChooser *chooser)
2257 {
2258 gboolean do_overwrite_confirmation;
2259
2260 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2261
2262 g_object_get (chooser, "do-overwrite-confirmation", &do_overwrite_confirmation, NULL);
2263
2264 return do_overwrite_confirmation;
2265 }
2266
2267 /**
2268 * gtk_file_chooser_add_choice:
2269 * @chooser: a #GtkFileChooser
2270 * @id: id for the added choice
2271 * @label: user-visible label for the added choice
2272 * @options: (nullable) (array zero-terminated=1): ids for the options of the choice, or %NULL for a boolean choice
2273 * @option_labels: (nullable) (array zero-terminated=1): user-visible labels for the options, must be the same length as @options
2274 *
2275 * Adds a 'choice' to the file chooser. This is typically implemented
2276 * as a combobox or, for boolean choices, as a checkbutton. You can select
2277 * a value using gtk_file_chooser_set_choice() before the dialog is shown,
2278 * and you can obtain the user-selected value in the ::response signal handler
2279 * using gtk_file_chooser_get_choice().
2280 *
2281 * Compare gtk_file_chooser_set_extra_widget().
2282 *
2283 * Since: 3.22
2284 */
2285 void
gtk_file_chooser_add_choice(GtkFileChooser * chooser,const char * id,const char * label,const char ** options,const char ** option_labels)2286 gtk_file_chooser_add_choice (GtkFileChooser *chooser,
2287 const char *id,
2288 const char *label,
2289 const char **options,
2290 const char **option_labels)
2291 {
2292 GtkFileChooserIface *iface = GTK_FILE_CHOOSER_GET_IFACE (chooser);
2293
2294 if (iface->add_choice)
2295 iface->add_choice (chooser, id, label, options, option_labels);
2296 }
2297
2298 /**
2299 * gtk_file_chooser_remove_choice:
2300 * @chooser: a #GtkFileChooser
2301 * @id: the ID of the choice to remove
2302 *
2303 * Removes a 'choice' that has been added with gtk_file_chooser_add_choice().
2304 *
2305 * Since: 3.22
2306 */
2307 void
gtk_file_chooser_remove_choice(GtkFileChooser * chooser,const char * id)2308 gtk_file_chooser_remove_choice (GtkFileChooser *chooser,
2309 const char *id)
2310 {
2311 GtkFileChooserIface *iface = GTK_FILE_CHOOSER_GET_IFACE (chooser);
2312
2313 if (iface->remove_choice)
2314 iface->remove_choice (chooser, id);
2315 }
2316
2317 /**
2318 * gtk_file_chooser_set_choice:
2319 * @chooser: a #GtkFileChooser
2320 * @id: the ID of the choice to set
2321 * @option: the ID of the option to select
2322 *
2323 * Selects an option in a 'choice' that has been added with
2324 * gtk_file_chooser_add_choice(). For a boolean choice, the
2325 * possible options are "true" and "false".
2326 *
2327 * Since: 3.22
2328 */
2329 void
gtk_file_chooser_set_choice(GtkFileChooser * chooser,const char * id,const char * option)2330 gtk_file_chooser_set_choice (GtkFileChooser *chooser,
2331 const char *id,
2332 const char *option)
2333 {
2334 GtkFileChooserIface *iface = GTK_FILE_CHOOSER_GET_IFACE (chooser);
2335
2336 if (iface->set_choice)
2337 iface->set_choice (chooser, id, option);
2338 }
2339
2340 /**
2341 * gtk_file_chooser_get_choice:
2342 * @chooser: a #GtkFileChooser
2343 * @id: the ID of the choice to get
2344 *
2345 * Gets the currently selected option in the 'choice' with the given ID.
2346 *
2347 * Returns: the ID of the currenly selected option
2348 * Since: 3.22
2349 */
2350 const char *
gtk_file_chooser_get_choice(GtkFileChooser * chooser,const char * id)2351 gtk_file_chooser_get_choice (GtkFileChooser *chooser,
2352 const char *id)
2353 {
2354 GtkFileChooserIface *iface = GTK_FILE_CHOOSER_GET_IFACE (chooser);
2355
2356 if (iface->get_choice)
2357 return iface->get_choice (chooser, id);
2358
2359 return NULL;
2360 }
2361
2362