gtkfilechooser.c 27 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GTK - The GIMP Toolkit
Owen Taylor's avatar
Owen Taylor committed
2 3 4 5 6 7 8 9 10 11 12 13 14 15
 * gtkfilechooser.c: Abstract interface for file selector GUIs
 * Copyright (C) 2003, Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
Javier Jardón's avatar
Javier Jardón committed
16
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
Owen Taylor's avatar
Owen Taylor committed
17 18
 */

19
#include "config.h"
Owen Taylor's avatar
Owen Taylor committed
20
#include "gtkfilechooser.h"
21
#include "gtkfilechooserprivate.h"
22
#include "gtkintl.h"
23
#include "gtktypebuiltins.h"
24
#include "gtkprivate.h"
25
#include "gtkmarshalers.h"
Owen Taylor's avatar
Owen Taylor committed
26

27 28

/**
Matthias Clasen's avatar
Matthias Clasen committed
29 30 31 32 33 34 35 36 37 38 39 40 41
 * GtkFileChooser:
 *
 * `GtkFileChooser` is an interface that can be implemented by file
 * selection widgets.
 *
 * In GTK, the main objects that implement this interface are
 * [class@Gtk.FileChooserWidget] and [class@Gtk.FileChooserDialog].
 *
 * You do not need to write an object that implements the `GtkFileChooser`
 * interface unless you are trying to adapt an existing file selector to
 * expose a standard programming interface.
 *
 * `GtkFileChooser` allows for shortcuts to various places in the filesystem.
42
 * In the default implementation these are displayed in the left pane. It
43
 * may be a bit confusing at first that these shortcuts come from various
44
 * sources and in various flavours, so lets explain the terminology here:
Matthias Clasen's avatar
Matthias Clasen committed
45 46
 *
 * - Bookmarks: are created by the user, by dragging folders from the
William Jon McCann's avatar
William Jon McCann committed
47
 *   right pane to the left pane, or by using the “Add”. Bookmarks
Matthias Clasen's avatar
Matthias Clasen committed
48 49 50 51 52 53 54
 *   can be renamed and deleted by the user.
 *
 * - Shortcuts: can be provided by the application. For example, a Paint
 *   program may want to add a shortcut for a Clipart folder. Shortcuts
 *   cannot be modified by the user.
 *
 * - Volumes: are provided by the underlying filesystem abstraction. They are
William Jon McCann's avatar
William Jon McCann committed
55
 *   the “roots” of the filesystem.
Matthias Clasen's avatar
Matthias Clasen committed
56
 *
57
 * # File Names and Encodings
Matthias Clasen's avatar
Matthias Clasen committed
58
 *
Matthias Clasen's avatar
Matthias Clasen committed
59 60
 * When the user is finished selecting files in a `GtkFileChooser`, your
 * program can get the selected filenames as `GFile`s.
Matthias Clasen's avatar
Matthias Clasen committed
61
 *
Matthias Clasen's avatar
Matthias Clasen committed
62
 * # Adding options
Matthias Clasen's avatar
Matthias Clasen committed
63
 *
64
 * You can add extra widgets to a file chooser to provide options
65
 * that are not present in the default design, by using
Matthias Clasen's avatar
Matthias Clasen committed
66
 * [method@Gtk.FileChooser.add_choice]. Each choice has an identifier and
67 68 69 70
 * a user visible label; additionally, each choice can have multiple
 * options. If a choice has no option, it will be rendered as a
 * check button with the given label; if a choice has options, it will
 * be rendered as a combo box.
71 72 73
 */


74
typedef GtkFileChooserIface GtkFileChooserInterface;
75
G_DEFINE_INTERFACE (GtkFileChooser, gtk_file_chooser, G_TYPE_OBJECT);
Owen Taylor's avatar
Owen Taylor committed
76 77

static void
78
gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
Owen Taylor's avatar
Owen Taylor committed
79
{
Matthias Clasen's avatar
Matthias Clasen committed
80 81 82 83 84
  /**
   * GtkFileChooser:action: (attributes org.gtk.Property.get=gtk_file_chooser_get_action org.gtk.Property.set=gtk_file_chooser_set_action)
   *
   * The type of operation that the file chooser is performing.
   */
85
  g_object_interface_install_property (iface,
86 87 88 89 90 91
                                       g_param_spec_enum ("action",
                                                          P_("Action"),
                                                          P_("The type of operation that the file selector is performing"),
                                                          GTK_TYPE_FILE_CHOOSER_ACTION,
                                                          GTK_FILE_CHOOSER_ACTION_OPEN,
                                                          GTK_PARAM_READWRITE));
Matthias Clasen's avatar
Matthias Clasen committed
92 93 94 95 96 97 98


  /**
   * GtkFileChooser:filter: (attributes org.gtk.Property.get=gtk_file_chooser_get_filter org.gtk.Property.set=gtk_file_chooser_set_filter)
   *
   * The current filter for selecting files that are displayed.
   */
99
  g_object_interface_install_property (iface,
100 101 102 103 104
                                       g_param_spec_object ("filter",
                                                            P_("Filter"),
                                                            P_("The current filter for selecting which files are displayed"),
                                                            GTK_TYPE_FILE_FILTER,
                                                            GTK_PARAM_READWRITE));
Matthias Clasen's avatar
Matthias Clasen committed
105 106 107 108 109 110

  /**
   * GtkFileChooser:select-multiple: (attributes org.gtk.Property.get=gtk_file_chooser_get_select_multiple org.gtk.Property.set=gtk_file_chooser_set_select_multiple)
   *
   * Whether to allow multiple files to be selected.
   */
111
  g_object_interface_install_property (iface,
112 113 114 115 116
                                       g_param_spec_boolean ("select-multiple",
                                                             P_("Select Multiple"),
                                                             P_("Whether to allow multiple files to be selected"),
                                                             FALSE,
                                                             GTK_PARAM_READWRITE));
117

118
  /**
Matthias Clasen's avatar
Matthias Clasen committed
119
   * GtkFileChooser:filters: (attributes org.gtk.Property.get=gtk_file_chooser_get_filters)
120
   *
Matthias Clasen's avatar
Matthias Clasen committed
121
   * A `GListModel` containing the filters that have been
122 123 124 125 126 127 128 129 130 131 132
   * added with gtk_file_chooser_add_filter().
   *
   * The returned object should not be modified. It may
   * or may not be updated for later changes.
   */
  g_object_interface_install_property (iface,
                                       g_param_spec_object ("filters",
                                                          P_("Filters"),
                                                          P_("List model of filters"),
                                                          G_TYPE_LIST_MODEL,
                                                          GTK_PARAM_READABLE));
133 134

  /**
Matthias Clasen's avatar
Matthias Clasen committed
135
   * GtkFileChooser:shortcut-folders: (attributes org.gtk.Property.get=gtk_file_chooser_get_shortcut_folders)
136
   *
Matthias Clasen's avatar
Matthias Clasen committed
137
   * A `GListModel` containing the shortcut folders that have been
138
   * added with gtk_file_chooser_add_shortcut_folder().
139 140 141 142 143 144 145 146 147 148
   *
   * The returned object should not be modified. It may
   * or may not be updated for later changes.
   */
  g_object_interface_install_property (iface,
                                       g_param_spec_object ("shortcut-folders",
                                                          P_("Shortcut Folders"),
                                                          P_("List model of shortcut folders"),
                                                          G_TYPE_LIST_MODEL,
                                                          GTK_PARAM_READABLE));
149

150
  /**
Matthias Clasen's avatar
Matthias Clasen committed
151 152
   * GtkFileChooser:create-folders: (attributes org.gtk.Property.get=gtk_file_chooser_get_create_folders org.gtk.Property.set=gtk_file_chooser_set_create_folders)
   *
153 154 155
   * Whether a file chooser not in %GTK_FILE_CHOOSER_ACTION_OPEN mode
   * will offer the user to create new folders.
   */
156
  g_object_interface_install_property (iface,
157 158 159 160 161 162
                                       g_param_spec_boolean ("create-folders",
                                                             P_("Allow folder creation"),
                                                             P_("Whether a file chooser not in open mode "
                                                                "will offer the user to create new folders."),
                                                             TRUE,
                                                             GTK_PARAM_READWRITE));
Owen Taylor's avatar
Owen Taylor committed
163 164
}

165 166 167
/**
 * gtk_file_chooser_error_quark:
 *
Matthias Clasen's avatar
Matthias Clasen committed
168
 * Registers an error quark for `GtkFileChooser` errors.
169
 * 
Matthias Clasen's avatar
Matthias Clasen committed
170
 * Returns: The error quark used for `GtkFileChooser` errors.
171 172 173 174
 **/
GQuark
gtk_file_chooser_error_quark (void)
{
175
  return g_quark_from_static_string ("gtk-file-chooser-error-quark");
176 177
}

178
/**
Matthias Clasen's avatar
Matthias Clasen committed
179 180
 * gtk_file_chooser_set_action: (attributes org.gtk.Method.set_property=action)
 * @chooser: a `GtkFileChooser`
181
 * @action: the action that the file selector is performing
Matthias Clasen's avatar
Matthias Clasen committed
182 183 184 185 186 187 188 189
 *
 * Sets the type of operation that the chooser is performing.
 *
 * The user interface is adapted to suit the selected action.
 *
 * For example, an option to create a new folder might be shown
 * if the action is %GTK_FILE_CHOOSER_ACTION_SAVE but not if the
 * action is %GTK_FILE_CHOOSER_ACTION_OPEN.
190
 **/
Owen Taylor's avatar
Owen Taylor committed
191 192
void
gtk_file_chooser_set_action (GtkFileChooser       *chooser,
193
                             GtkFileChooserAction  action)
Owen Taylor's avatar
Owen Taylor committed
194 195 196 197 198 199
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));

  g_object_set (chooser, "action", action, NULL);
}

200
/**
Matthias Clasen's avatar
Matthias Clasen committed
201 202 203 204 205
 * gtk_file_chooser_get_action: (attributes org.gtk.Method.get_property=action)
 * @chooser: a `GtkFileChooser`
 *
 * Gets the type of operation that the file chooser is performing.
 *
206
 * Returns: the action that the file selector is performing
Matthias Clasen's avatar
Matthias Clasen committed
207
 */
Owen Taylor's avatar
Owen Taylor committed
208 209 210 211 212 213 214 215 216 217 218 219
GtkFileChooserAction
gtk_file_chooser_get_action (GtkFileChooser *chooser)
{
  GtkFileChooserAction action;
  
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);

  g_object_get (chooser, "action", &action, NULL);

  return action;
}

220
/**
Matthias Clasen's avatar
Matthias Clasen committed
221 222
 * gtk_file_chooser_set_select_multiple: (attributes org.gtk.Method.set_property=select-multiple)
 * @chooser: a `GtkFileChooser`
223
 * @select_multiple: %TRUE if multiple files can be selected.
Matthias Clasen's avatar
Matthias Clasen committed
224 225 226 227 228
 *
 * Sets whether multiple files can be selected in the file chooser.
 *
 * This is only relevant if the action is set to be
 * %GTK_FILE_CHOOSER_ACTION_OPEN or
229
 * %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
Matthias Clasen's avatar
Matthias Clasen committed
230
 */
Owen Taylor's avatar
Owen Taylor committed
231 232
void
gtk_file_chooser_set_select_multiple (GtkFileChooser *chooser,
233
                                      gboolean        select_multiple)
Owen Taylor's avatar
Owen Taylor committed
234 235 236
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));

237
  g_object_set (chooser, "select-multiple", select_multiple, NULL);
Owen Taylor's avatar
Owen Taylor committed
238 239
}

240
/**
Matthias Clasen's avatar
Matthias Clasen committed
241 242 243
 * gtk_file_chooser_get_select_multiple: (attributes org.gtk.Method.get_property=select-multiple)
 * @chooser: a `GtkFileChooser`
 *
244
 * Gets whether multiple files can be selected in the file
Matthias Clasen's avatar
Matthias Clasen committed
245 246
 * chooser.
 *
247
 * Returns: %TRUE if multiple files can be selected.
Matthias Clasen's avatar
Matthias Clasen committed
248
 */
Owen Taylor's avatar
Owen Taylor committed
249 250 251 252 253 254 255
gboolean
gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser)
{
  gboolean select_multiple;
  
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);

256
  g_object_get (chooser, "select-multiple", &select_multiple, NULL);
Owen Taylor's avatar
Owen Taylor committed
257 258 259 260

  return select_multiple;
}

261
/**
Matthias Clasen's avatar
Matthias Clasen committed
262 263
 * gtk_file_chooser_set_create_folders: (attributes org.gtk.Method.set_property=create-folders)
 * @chooser: a `GtkFileChooser`
264
 * @create_folders: %TRUE if the Create Folder button should be displayed
Matthias Clasen's avatar
Matthias Clasen committed
265
 *
266
 * Sets whether file chooser will offer to create new folders.
Matthias Clasen's avatar
Matthias Clasen committed
267 268
 *
 * This is only relevant if the action is not set to be
269
 * %GTK_FILE_CHOOSER_ACTION_OPEN.
Matthias Clasen's avatar
Matthias Clasen committed
270
 */
271 272
void
gtk_file_chooser_set_create_folders (GtkFileChooser *chooser,
273
                                     gboolean        create_folders)
274 275 276 277 278 279 280
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));

  g_object_set (chooser, "create-folders", create_folders, NULL);
}

/**
Matthias Clasen's avatar
Matthias Clasen committed
281 282 283
 * gtk_file_chooser_get_create_folders: (attributes org.gtk.Method.get_property=create-folders)
 * @chooser: a `GtkFileChooser`
 *
284
 * Gets whether file chooser will offer to create new folders.
Matthias Clasen's avatar
Matthias Clasen committed
285
 *
286
 * Returns: %TRUE if the Create Folder button should be displayed.
Matthias Clasen's avatar
Matthias Clasen committed
287
 */
288 289 290 291 292 293 294 295 296 297 298 299
gboolean
gtk_file_chooser_get_create_folders (GtkFileChooser *chooser)
{
  gboolean create_folders;
  
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);

  g_object_get (chooser, "create-folders", &create_folders, NULL);

  return create_folders;
}

300 301
/**
 * gtk_file_chooser_set_current_name:
Matthias Clasen's avatar
Matthias Clasen committed
302
 * @chooser: a `GtkFileChooser`
303
 * @name: (type utf8): the filename to use, as a UTF-8 string
Matthias Clasen's avatar
Matthias Clasen committed
304
 *
305
 * Sets the current name in the file selector, as if entered
Matthias Clasen's avatar
Matthias Clasen committed
306 307 308 309 310 311
 * by the user.
 *
 * Note that the name passed in here is a UTF-8 string rather
 * than a filename. This function is meant for such uses as a
 * suggested name in a “Save As...” dialog.  You can pass
 * “Untitled.doc” or a similarly suitable suggestion for the @name.
312
 *
Matthias Clasen's avatar
Matthias Clasen committed
313 314
 * If you want to preselect a particular existing file, you should
 * use [method@Gtk.FileChooser.set_file] instead.
315
 *
Matthias Clasen's avatar
Matthias Clasen committed
316 317
 * Please see the documentation for those functions for an example
 * of using [method@Gtk.FileChooser.set_current_name] as well.
318 319 320
 **/
void
gtk_file_chooser_set_current_name  (GtkFileChooser *chooser,
Benjamin Otte's avatar
Benjamin Otte committed
321
                                    const char     *name)
322 323 324 325 326 327 328
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
  g_return_if_fail (name != NULL);
  
  GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_name (chooser, name);
}

329 330
/**
 * gtk_file_chooser_get_current_name:
Matthias Clasen's avatar
Matthias Clasen committed
331
 * @chooser: a `GtkFileChooser`
332
 *
Matthias Clasen's avatar
Matthias Clasen committed
333
 * Gets the current name in the file selector, as entered by the user.
334
 *
Matthias Clasen's avatar
Matthias Clasen committed
335 336
 * This is meant to be used in save dialogs, to get the currently typed
 * filename when the file itself does not exist yet.
337
 *
Matthias Clasen's avatar
Matthias Clasen committed
338 339 340 341 342 343
 * Returns: The raw text from the file chooser’s “Name” entry. Free with
 *   g_free(). Note that this string is not a full pathname or URI; it is
 *   whatever the contents of the entry are. Note also that this string is
 *   in UTF-8 encoding, which is not necessarily the system’s encoding for
 *   filenames.
 */
Benjamin Otte's avatar
Benjamin Otte committed
344
char *
345 346
gtk_file_chooser_get_current_name (GtkFileChooser *chooser)
{
347
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
348 349 350 351

  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_name (chooser);
}

Owen Taylor's avatar
Owen Taylor committed
352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368
void
gtk_file_chooser_select_all (GtkFileChooser *chooser)
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
  
  GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_all (chooser);
}

void
gtk_file_chooser_unselect_all (GtkFileChooser *chooser)
{

  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
  
  GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_all (chooser);
}

369
/**
370
 * gtk_file_chooser_set_current_folder:
Matthias Clasen's avatar
Matthias Clasen committed
371 372
 * @chooser: a `GtkFileChooser`
 * @file: the `GFile` for the new folder
Matthias Clasen's avatar
Matthias Clasen committed
373
 * @error: location to store error
Matthias Clasen's avatar
Matthias Clasen committed
374
 *
Matthias Clasen's avatar
Matthias Clasen committed
375
 * Sets the current folder for @chooser from a `GFile`.
376
 *
377
 * Returns: %TRUE if the folder could be changed successfully, %FALSE
Matthias Clasen's avatar
Matthias Clasen committed
378 379
 *   otherwise.
 */
380
gboolean
381 382 383
gtk_file_chooser_set_current_folder (GtkFileChooser  *chooser,
                                     GFile           *file,
                                     GError         **error)
384
{
385
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
386
  g_return_val_if_fail (G_IS_FILE (file), FALSE);
387
  g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
388

389
  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_folder (chooser, file, error);
390 391
}

392
/**
393
 * gtk_file_chooser_get_current_folder:
Matthias Clasen's avatar
Matthias Clasen committed
394
 * @chooser: a `GtkFileChooser`
Matthias Clasen's avatar
Matthias Clasen committed
395
 *
Matthias Clasen's avatar
Matthias Clasen committed
396
 * Gets the current folder of @chooser as `GFile`.
Matthias Clasen's avatar
Matthias Clasen committed
397
 *
Matthias Clasen's avatar
Matthias Clasen committed
398
 * Returns: (transfer full): the `GFile` for the current folder.
399
 */
400
GFile *
401
gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
Owen Taylor's avatar
Owen Taylor committed
402 403 404
{
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

Matthias Clasen's avatar
Matthias Clasen committed
405
  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_folder (chooser);
Owen Taylor's avatar
Owen Taylor committed
406 407
}

408
gboolean
409 410 411
gtk_file_chooser_select_file (GtkFileChooser  *chooser,
                              GFile           *file,
                              GError         **error)
412
{
413
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
414
  g_return_val_if_fail (G_IS_FILE (file), FALSE);
415
  g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
416

417
  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_file (chooser, file, error);
418 419 420
}

void
421 422
gtk_file_chooser_unselect_file (GtkFileChooser *chooser,
                                GFile          *file)
423 424
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
425
  g_return_if_fail (G_IS_FILE (file));
426

427
  GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_file (chooser, file);
428 429
}

430
/**
431
 * gtk_file_chooser_get_files:
Matthias Clasen's avatar
Matthias Clasen committed
432
 * @chooser: a `GtkFileChooser`
433
 *
434
 * Lists all the selected files and subfolders in the current folder
Matthias Clasen's avatar
Matthias Clasen committed
435
 * of @chooser as `GFile`.
436
 *
Matthias Clasen's avatar
Matthias Clasen committed
437 438 439
 * Returns: (transfer full): a list model containing a `GFile` for each
 *   selected file and subfolder in the current folder. Free the returned
 *   list with g_object_unref().
440 441
 */
GListModel *
442
gtk_file_chooser_get_files (GtkFileChooser *chooser)
443 444 445
{
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

446
  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_files (chooser);
447 448
}

449 450
/**
 * gtk_file_chooser_set_file:
Matthias Clasen's avatar
Matthias Clasen committed
451 452
 * @chooser: a `GtkFileChooser`
 * @file: the `GFile` to set as current
Matthias Clasen's avatar
Matthias Clasen committed
453
 * @error: (nullable): location to store the error
454
 *
Matthias Clasen's avatar
Matthias Clasen committed
455 456 457 458 459
 * Sets @file as the current filename for the file chooser.
 *
 * This includes changing to the file’s parent folder and actually selecting
 * the file in list. If the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode,
 * the file’s base name will also appear in the dialog’s file name entry.
460
 *
461
 * If the file name isn’t in the current folder of @chooser, then the current
462
 * folder of @chooser will be changed to the folder containing @file.
463 464 465 466
 *
 * Note that the file must exist, or nothing will be done except
 * for the directory change.
 *
Matthias Clasen's avatar
Matthias Clasen committed
467 468 469 470 471 472
 * If you are implementing a save dialog, you should use this function if
 * you already have a file name to which the user may save; for example,
 * when the user opens an existing file and then does “Save As…”. If you
 * don’t have a file name already — for example, if the user just created
 * a new file and is saving it for the first time, do not call this function.
 *
473
 * Instead, use something similar to this:
Matthias Clasen's avatar
Matthias Clasen committed
474 475
 *
 * ```c
476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495
 * static void
 * prepare_file_chooser (GtkFileChooser *chooser,
 *                       GFile          *existing_file)
 * {
 *   gboolean document_is_new = (existing_file == NULL);
 *
 *   if (document_is_new)
 *     {
 *       GFile *default_file_for_saving = g_file_new_for_path ("./out.txt");
 *       // the user just created a new document
 *       gtk_file_chooser_set_current_folder (chooser, default_file_for_saving, NULL);
 *       gtk_file_chooser_set_current_name (chooser, "Untitled document");
 *       g_object_unref (default_file_for_saving);
 *     }
 *   else
 *     {
 *       // the user edited an existing document
 *       gtk_file_chooser_set_file (chooser, existing_file, NULL);
 *     }
 * }
Matthias Clasen's avatar
Matthias Clasen committed
496
 * ```
497
 *
Matthias Clasen's avatar
Matthias Clasen committed
498 499
 * Returns: Not useful
 */
500 501 502 503 504 505 506 507 508 509 510 511 512 513 514
gboolean
gtk_file_chooser_set_file (GtkFileChooser  *chooser,
                           GFile           *file,
                           GError         **error)
{
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
  g_return_val_if_fail (G_IS_FILE (file), FALSE);
  g_return_val_if_fail (error == NULL || *error == NULL, FALSE);

  gtk_file_chooser_unselect_all (chooser);
  return gtk_file_chooser_select_file (chooser, file, error);
}

/**
 * gtk_file_chooser_get_file:
Matthias Clasen's avatar
Matthias Clasen committed
515
 * @chooser: a `GtkFileChooser`
516
 *
Matthias Clasen's avatar
Matthias Clasen committed
517 518
 * Gets the `GFile` for the currently selected file in
 * the file selector.
519
 *
Matthias Clasen's avatar
Matthias Clasen committed
520 521
 * If multiple files are selected, one of the files will be
 * returned at random.
522
 *
Matthias Clasen's avatar
Matthias Clasen committed
523 524 525 526 527 528
 * If the file chooser is in folder mode, this function returns
 * the selected folder.
 *
 * Returns: (transfer full): a selected `GFile`. You own the
 *   returned file; use g_object_unref() to release it.
 */
529
GFile *
530
gtk_file_chooser_get_file (GtkFileChooser *chooser)
531
{
532
  GListModel *list;
533
  GFile *result = NULL;
534

535 536
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

537
  list = gtk_file_chooser_get_files (chooser);
538 539 540
  if (g_list_model_get_n_items (list) > 0)
    result = g_list_model_get_item (list, 0);
  g_object_unref (list);
541 542 543 544

  return result;
}

545
/**
546
 * gtk_file_chooser_add_shortcut_folder:
Matthias Clasen's avatar
Matthias Clasen committed
547 548
 * @chooser: a `GtkFileChooser`
 * @folder: a `GFile` for the folder to add
Matthias Clasen's avatar
Matthias Clasen committed
549
 * @error: location to store error
Matthias Clasen's avatar
Matthias Clasen committed
550 551 552 553 554 555 556
 *
 * Adds a folder to be displayed with the shortcut folders
 * in a file chooser.
 *
 * Returns: %TRUE if the folder could be added successfully,
 *   %FALSE otherwise.
 */
557
gboolean
558 559 560
gtk_file_chooser_add_shortcut_folder (GtkFileChooser  *chooser,
                                      GFile           *folder,
                                      GError         **error)
561 562
{
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
563
  g_return_val_if_fail (G_IS_FILE (folder), FALSE);
564

565
  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_shortcut_folder (chooser, folder, error);
566 567 568
}

/**
569
 * gtk_file_chooser_remove_shortcut_folder:
Matthias Clasen's avatar
Matthias Clasen committed
570 571
 * @chooser: a `GtkFileChooser`
 * @folder: a `GFile` for the folder to remove
Matthias Clasen's avatar
Matthias Clasen committed
572
 * @error: location to store error
Matthias Clasen's avatar
Matthias Clasen committed
573
 *
574
 * Removes a folder from the shortcut folders in a file chooser.
Matthias Clasen's avatar
Matthias Clasen committed
575 576 577 578
 *
 * Returns: %TRUE if the folder could be removed successfully,
 *   %FALSE otherwise.
 */
579
gboolean
580 581 582
gtk_file_chooser_remove_shortcut_folder (GtkFileChooser  *chooser,
                                         GFile           *folder,
                                         GError         **error)
583 584
{
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
585
  g_return_val_if_fail (G_IS_FILE (folder), FALSE);
586

587
  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_shortcut_folder (chooser, folder, error);
Owen Taylor's avatar
Owen Taylor committed
588
}
Owen Taylor's avatar
Owen Taylor committed
589 590 591

/**
 * gtk_file_chooser_add_filter:
Matthias Clasen's avatar
Matthias Clasen committed
592 593 594
 * @chooser: a `GtkFileChooser`
 * @filter: (transfer none): a `GtkFileFilter`
 *
Owen Taylor's avatar
Owen Taylor committed
595
 * Adds @filter to the list of filters that the user can select between.
Matthias Clasen's avatar
Matthias Clasen committed
596
 *
Owen Taylor's avatar
Owen Taylor committed
597
 * When a filter is selected, only files that are passed by that
Matthias Clasen's avatar
Matthias Clasen committed
598 599
 * filter are displayed.
 *
600 601
 * Note that the @chooser takes ownership of the filter if it is floating,
 * so you have to ref and sink it if you want to keep a reference.
Matthias Clasen's avatar
Matthias Clasen committed
602
 */
Owen Taylor's avatar
Owen Taylor committed
603 604
void
gtk_file_chooser_add_filter (GtkFileChooser *chooser,
605
                             GtkFileFilter  *filter)
Owen Taylor's avatar
Owen Taylor committed
606 607 608 609 610 611 612
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));

  GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_filter (chooser, filter);
}

/**
613
 * gtk_file_chooser_remove_filter:
Matthias Clasen's avatar
Matthias Clasen committed
614 615 616
 * @chooser: a `GtkFileChooser`
 * @filter: a `GtkFileFilter`
 *
Owen Taylor's avatar
Owen Taylor committed
617
 * Removes @filter from the list of filters that the user can select between.
Matthias Clasen's avatar
Matthias Clasen committed
618
 */
Owen Taylor's avatar
Owen Taylor committed
619 620
void
gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
621
                                GtkFileFilter  *filter)
Owen Taylor's avatar
Owen Taylor committed
622 623 624 625 626 627 628
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));

  GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_filter (chooser, filter);
}

/**
Matthias Clasen's avatar
Matthias Clasen committed
629 630 631 632 633 634 635
 * gtk_file_chooser_get_filters: (attributes org.gtk.Method.get_property=filters)
 * @chooser: a `GtkFileChooser`
 *
 * Gets the current set of user-selectable filters, as a list model.
 *
 * See [method@Gtk.FileChooser.add_filter] and
 * [method@Gtk.FileChooser.remove_filter] for changing individual filters.
636
 *
637 638 639
 * You should not modify the returned list model. Future changes to
 * @chooser may or may not affect the returned model.
 *
Matthias Clasen's avatar
Matthias Clasen committed
640 641 642
 * Returns: (transfer full): a `GListModel` containing the current set
 *   of user-selectable filters.
 */
643 644
GListModel *
gtk_file_chooser_get_filters (GtkFileChooser *chooser)
Owen Taylor's avatar
Owen Taylor committed
645 646 647
{
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

648
  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_filters (chooser);
Owen Taylor's avatar
Owen Taylor committed
649 650 651
}

/**
Matthias Clasen's avatar
Matthias Clasen committed
652 653 654 655 656 657 658 659 660 661 662 663
 * gtk_file_chooser_set_filter: (attributes org.gtk.Method.set_property=filter)
 * @chooser: a `GtkFileChooser`
 * @filter: a `GtkFileFilter`
 *
 * Sets the current filter.
 *
 * Only the files that pass the filter will be displayed.
 * If the user-selectable list of filters is non-empty, then
 * the filter should be one of the filters in that list.
 *
 * Setting the current filter when the list of filters is
 * empty is useful if you want to restrict the displayed
Owen Taylor's avatar
Owen Taylor committed
664
 * set of files without letting the user change it.
Matthias Clasen's avatar
Matthias Clasen committed
665
 */
Owen Taylor's avatar
Owen Taylor committed
666 667
void
gtk_file_chooser_set_filter (GtkFileChooser *chooser,
668
                             GtkFileFilter  *filter)
Owen Taylor's avatar
Owen Taylor committed
669 670 671 672 673 674 675 676
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
  g_return_if_fail (GTK_IS_FILE_FILTER (filter));

  g_object_set (chooser, "filter", filter, NULL);
}

/**
Matthias Clasen's avatar
Matthias Clasen committed
677 678
 * gtk_file_chooser_get_filter: (attributes org.gtk.Method.get_property=filter)
 * @chooser: a `GtkFileChooser`
Matthias Clasen's avatar
Matthias Clasen committed
679
 *
Matthias Clasen's avatar
Matthias Clasen committed
680
 * Gets the current filter.
Matthias Clasen's avatar
Matthias Clasen committed
681
 *
Matthias Clasen's avatar
Matthias Clasen committed
682
 * Returns: (nullable) (transfer none): the current filter
Matthias Clasen's avatar
Matthias Clasen committed
683
 */
Owen Taylor's avatar
Owen Taylor committed
684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700
GtkFileFilter *
gtk_file_chooser_get_filter (GtkFileChooser *chooser)
{
  GtkFileFilter *filter;
  
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

  g_object_get (chooser, "filter", &filter, NULL);
  /* Horrid hack; g_object_get() refs returned objects but
   * that contradicts the memory management conventions
   * for accessors.
   */
  if (filter)
    g_object_unref (filter);

  return filter;
}
701 702

/**
Matthias Clasen's avatar
Matthias Clasen committed
703 704 705 706
 * gtk_file_chooser_get_shortcut_folders: (attributes org.gtk.Method.get_property=shortcut-folders)
 * @chooser: a `GtkFileChooser`
 *
 * Queries the list of shortcut folders in the file chooser.
707
 *
708 709 710
 * You should not modify the returned list model. Future changes to
 * @chooser may or may not affect the returned model.
 *
Matthias Clasen's avatar
Matthias Clasen committed
711
 * Returns: (transfer full): A list model of `GFile`s
712
 */
713 714
GListModel *
gtk_file_chooser_get_shortcut_folders (GtkFileChooser *chooser)
715 716 717
{
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

718
  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_shortcut_folders (chooser);
719
}
720

721 722
/**
 * gtk_file_chooser_add_choice:
Matthias Clasen's avatar
Matthias Clasen committed
723
 * @chooser: a `GtkFileChooser`
724 725
 * @id: id for the added choice
 * @label: user-visible label for the added choice
726 727
 * @options: (nullable) (array zero-terminated=1): ids for the options of the choice, or %NULL for a boolean choice
 * @option_labels: (nullable) (array zero-terminated=1): user-visible labels for the options, must be the same length as @options
728
 *
Matthias Clasen's avatar
Matthias Clasen committed
729 730 731 732 733 734 735 736
 * Adds a 'choice' to the file chooser.
 *
 * This is typically implemented as a combobox or, for boolean choices,
 * as a checkbutton. You can select a value using
 * [method@Gtk.FileChooser.set_choice] before the dialog is shown,
 * and you can obtain the user-selected value in the
 * [signal@Gtk.Dialog::response] signal handler using
 * [method@Gtk.FileChooser.get_choice].
737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752
 */
void
gtk_file_chooser_add_choice (GtkFileChooser  *chooser,
                             const char      *id,
                             const char      *label,
                             const char     **options,
                             const char     **option_labels)
{
  GtkFileChooserIface *iface = GTK_FILE_CHOOSER_GET_IFACE (chooser);

  if (iface->add_choice)
    iface->add_choice (chooser, id, label, options, option_labels);
}

/**
 * gtk_file_chooser_remove_choice:
Matthias Clasen's avatar
Matthias Clasen committed
753
 * @chooser: a `GtkFileChooser`
754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769
 * @id: the ID of the choice to remove
 *
 * Removes a 'choice' that has been added with gtk_file_chooser_add_choice().
 */
void
gtk_file_chooser_remove_choice (GtkFileChooser  *chooser,
                                const char      *id)
{
  GtkFileChooserIface *iface = GTK_FILE_CHOOSER_GET_IFACE (chooser);

  if (iface->remove_choice)
    iface->remove_choice (chooser, id);
}

/**
 * gtk_file_chooser_set_choice:
Matthias Clasen's avatar
Matthias Clasen committed
770
 * @chooser: a `GtkFileChooser`
771
 * @id: the ID of the choice to set
772
 * @option: the ID of the option to select
773 774
 *
 * Selects an option in a 'choice' that has been added with
Matthias Clasen's avatar
Matthias Clasen committed
775 776 777
 * gtk_file_chooser_add_choice().
 *
 * For a boolean choice, the possible options are "true" and "false".
778 779 780 781 782 783 784 785 786 787 788 789 790 791
 */
void
gtk_file_chooser_set_choice (GtkFileChooser  *chooser,
                             const char      *id,
                             const char      *option)
{
  GtkFileChooserIface *iface = GTK_FILE_CHOOSER_GET_IFACE (chooser);

  if (iface->set_choice)
    iface->set_choice (chooser, id, option);
}

/**
 * gtk_file_chooser_get_choice:
Matthias Clasen's avatar
Matthias Clasen committed
792
 * @chooser: a `GtkFileChooser`
793 794 795 796
 * @id: the ID of the choice to get
 *
 * Gets the currently selected option in the 'choice' with the given ID.
 *
Yuri Chornoivan's avatar
Yuri Chornoivan committed
797
 * Returns: the ID of the currently selected option
798 799 800 801 802 803 804 805 806 807 808 809
 */
const char *
gtk_file_chooser_get_choice (GtkFileChooser  *chooser,
                             const char      *id)
{
  GtkFileChooserIface *iface = GTK_FILE_CHOOSER_GET_IFACE (chooser);

  if (iface->get_choice)
    return iface->get_choice (chooser, id);

  return NULL;
}