Pileus Git - ~andy/gtk/blob - gtk/gtkfilechooser.c

   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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #include "gtkfilechooser.h"
  22 #include "gtkfilechooserprivate.h"
  23 #include "gtkfilesystem.h"
  24 #include "gtkintl.h"
  25 #include "gtktypebuiltins.h"
  26
  27 static void gtk_file_chooser_class_init (gpointer g_iface);
  28
  29 static GtkFilePath *gtk_file_chooser_get_path         (GtkFileChooser *chooser);
  30
  31 GType
  32 gtk_file_chooser_get_type (void)
  33 {
  34   static GType file_chooser_type = 0;
  35
  36   if (!file_chooser_type)
  37     {
  38       static const GTypeInfo file_chooser_info =
  39       {
  40         sizeof (GtkFileChooserIface),  /* class_size */
  41         NULL,                          /* base_init */
  42         NULL,                          /* base_finalize */
  43         (GClassInitFunc)gtk_file_chooser_class_init, /* class_init */
  44       };
  45
  46       file_chooser_type = g_type_register_static (G_TYPE_INTERFACE,
  47                                                   "GtkFileChooser",
  48                                                   &file_chooser_info, 0);
  49
  50       g_type_interface_add_prerequisite (file_chooser_type, GTK_TYPE_WIDGET);
  51     }
  52
  53   return file_chooser_type;
  54 }
  55
  56 static void
  57 gtk_file_chooser_class_init (gpointer g_iface)
  58 {
  59   GType iface_type = G_TYPE_FROM_INTERFACE (g_iface);
  60
  61   g_signal_new ("current-folder-changed",
  62                 iface_type,
  63                 G_SIGNAL_RUN_LAST,
  64                 G_STRUCT_OFFSET (GtkFileChooserIface, current_folder_changed),
  65                 NULL, NULL,
  66                 g_cclosure_marshal_VOID__VOID,
  67                 G_TYPE_NONE, 0);
  68   g_signal_new ("selection-changed",
  69                 iface_type,
  70                 G_SIGNAL_RUN_LAST,
  71                 G_STRUCT_OFFSET (GtkFileChooserIface, selection_changed),
  72                 NULL, NULL,
  73                 g_cclosure_marshal_VOID__VOID,
  74                 G_TYPE_NONE, 0);
  75   g_signal_new ("update-preview",
  76                 iface_type,
  77                 G_SIGNAL_RUN_LAST,
  78                 G_STRUCT_OFFSET (GtkFileChooserIface, update_preview),
  79                 NULL, NULL,
  80                 g_cclosure_marshal_VOID__VOID,
  81                 G_TYPE_NONE, 0);
  82   g_signal_new ("file-activated",
  83                 iface_type,
  84                 G_SIGNAL_RUN_LAST,
  85                 G_STRUCT_OFFSET (GtkFileChooserIface, file_activated),
  86                 NULL, NULL,
  87                 g_cclosure_marshal_VOID__VOID,
  88                 G_TYPE_NONE, 0);
  89
  90   g_object_interface_install_property (g_iface,
  91                                        g_param_spec_enum ("action",
  92                                                           _("Action"),
  93                                                           _("The type of operation that the file selector is performing"),
  94                                                           GTK_TYPE_FILE_CHOOSER_ACTION,
  95                                                           GTK_FILE_CHOOSER_ACTION_OPEN,
  96                                                           G_PARAM_READWRITE));
  97   g_object_interface_install_property (g_iface,
  98                                        g_param_spec_object ("file-system",
  99                                                             _("File System"),
 100                                                             _("File system object to use"),
 101                                                             GTK_TYPE_FILE_SYSTEM,
 102                                                             G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
 103   g_object_interface_install_property (g_iface,
 104                                        g_param_spec_object ("filter",
 105                                                             _("Filter"),
 106                                                             _("The current filter for selecting which files are displayed"),
 107                                                             GTK_TYPE_FILE_FILTER,
 108                                                             G_PARAM_READWRITE));
 109   g_object_interface_install_property (g_iface,
 110                                        g_param_spec_boolean ("folder-mode",
 111                                                              _("Folder Mode"),
 112                                                              _("Whether to select folders rather than files"),
 113                                                              FALSE,
 114                                                              G_PARAM_READWRITE));
 115   g_object_interface_install_property (g_iface,
 116                                        g_param_spec_boolean ("local-only",
 117                                                              _("Local Only"),
 118                                                              _("Whether the selected file(s) should be limited to local file: URLs"),
 119                                                              TRUE,
 120                                                              G_PARAM_READWRITE));
 121   g_object_interface_install_property (g_iface,
 122                                        g_param_spec_object ("preview-widget",
 123                                                             _("Preview widget"),
 124                                                             _("Application supplied widget for custom previews."),
 125                                                             GTK_TYPE_WIDGET,
 126                                                             G_PARAM_READWRITE));
 127   g_object_interface_install_property (g_iface,
 128                                        g_param_spec_boolean ("preview-widget-active",
 129                                                              _("Preview Widget Active"),
 130                                                              _("Whether the application supplied widget for custom previews should be shown."),
 131                                                              TRUE,
 132                                                              G_PARAM_READWRITE));
 133   g_object_interface_install_property (g_iface,
 134                                        g_param_spec_object ("extra-widget",
 135                                                             _("Extra widget"),
 136                                                             _("Application supplied widget for extra options."),
 137                                                             GTK_TYPE_WIDGET,
 138                                                             G_PARAM_READWRITE));
 139   g_object_interface_install_property (g_iface,
 140                                        g_param_spec_boolean ("select-multiple",
 141                                                              _("Select Multiple"),
 142                                                              _("Whether to allow multiple files to be selected"),
 143                                                              FALSE,
 144                                                              G_PARAM_READWRITE));
 145
 146   g_object_interface_install_property (g_iface,
 147                                        g_param_spec_boolean ("show-hidden",
 148                                                              _("Show Hidden"),
 149                                                              _("Whether the hidden files and folders should be displayed"),
 150                                                              FALSE,
 151                                                              G_PARAM_READWRITE));
 152 }
 153
 154 /**
 155  * gtk_file_chooser_error_quark:
 156  *
 157  * Registers an error quark for #GtkFileChooser if necessary.
 158  *
 159  * Return value: The error quark used for #GtkFileChooser errors.
 160  *
 161  * Since: 2.4
 162  **/
 163 GQuark
 164 gtk_file_chooser_error_quark (void)
 165 {
 166   static GQuark quark = 0;
 167   if (quark == 0)
 168     quark = g_quark_from_static_string ("gtk-file-chooser-error-quark");
 169   return quark;
 170 }
 171
 172 /**
 173  * gtk_file_chooser_set_action:
 174  * @chooser: a #GtkFileChooser
 175  * @action: the action that the file selector is performing
 176  *
 177  * Sets the type of operation that that the chooser is performing; the
 178  * user interface is adapted to suit the selected action. For example,
 179  * an option to create a new folder might be shown if the action is
 180  * %GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is
 181  * %GTK_FILE_CHOOSER_ACTION_OPEN.
 182  *
 183  * Since: 2.4
 184  **/
 185 void
 186 gtk_file_chooser_set_action (GtkFileChooser       *chooser,
 187                              GtkFileChooserAction  action)
 188 {
 189   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 190
 191   g_object_set (chooser, "action", action, NULL);
 192 }
 193
 194 /**
 195  * gtk_file_chooser_get_action:
 196  * @chooser: a #GtkFileChooser
 197  *
 198  * Gets the type of operation that the file chooser is performing; see
 199  * gtk_file_chooser_set_action().
 200  *
 201  * Return value: the action that the file selector is performing
 202  *
 203  * Since: 2.4
 204  **/
 205 GtkFileChooserAction
 206 gtk_file_chooser_get_action (GtkFileChooser *chooser)
 207 {
 208   GtkFileChooserAction action;
 209
 210   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
 211
 212   g_object_get (chooser, "action", &action, NULL);
 213
 214   return action;
 215 }
 216
 217 /**
 218  * gtk_file_chooser_set_folder_mode:
 219  * @chooser: a #GtkFileChooser
 220  * @folder_mode: %TRUE if the file chooser is used to select folders
 221  *               rather than files.
 222  *
 223  * Sets whether the file chooser is used to select folders
 224  * rather than files. If in folder mode, only folders are displayed
 225  * to the use, and not the individual files inside the folders
 226  * and the user selects a single folder rather than one or
 227  * more files.
 228  *
 229  * Since: 2.4
 230  **/
 231 void
 232 gtk_file_chooser_set_folder_mode (GtkFileChooser *chooser,
 233                                   gboolean        folder_mode)
 234 {
 235   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 236
 237   g_object_set (chooser, "folder-mode", folder_mode, NULL);
 238 }
 239
 240 /**
 241  * gtk_file_chooser_get_folder_mode:
 242  * @chooser: a #GtkFileChooser
 243  *
 244  * Gets whether the file chooser is used to select folders
 245  * rather than files. See gtk_file_chooser_set_folder_mode()
 246  *
 247  * Return value: %TRUE if the file chooser is used to select
 248  *               folders rather than files.
 249  *
 250  * Since: 2.4
 251  **/
 252 gboolean
 253 gtk_file_chooser_get_folder_mode (GtkFileChooser *chooser)
 254 {
 255   gboolean folder_mode;
 256
 257   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
 258
 259   g_object_get (chooser, "folder-mode", &folder_mode, NULL);
 260
 261   return folder_mode;
 262 }
 263
 264 /**
 265  * gtk_file_chooser_set_local_only:
 266  * @chooser: a #GtkFileChooser
 267  * @local_only: %TRUE if only local files can be selected
 268  *
 269  * Sets whether only local files can be selected in the
 270  * file selector. If @local_only is %TRUE (the default),
 271  * then the selected file are files are guaranteed to be
 272  * accessible through the operating systems native file
 273  * file system and therefore the application only
 274  * needs to worry about the filename functions in
 275  * #GtkFileChooser, like gtk_file_chooser_get_filename(),
 276  * rather than the URI functions like
 277  * gtk_file_chooser_get_uri(),
 278  *
 279  * Since: 2.4
 280  **/
 281 void
 282 gtk_file_chooser_set_local_only (GtkFileChooser *chooser,
 283                                  gboolean        local_only)
 284 {
 285   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 286
 287   g_object_set (chooser, "local-only", local_only, NULL);
 288 }
 289
 290 /**
 291  * gtk_file_chooser_get_local_only:
 292  * @chooser: a #GtkFileChoosre
 293  *
 294  * Gets whether only local files can be selected in the
 295  * file selector. See gtk_file_chooser_set_local_only()
 296  *
 297  * Return value: %TRUE if only local files can be selected.
 298  *
 299  * Since: 2.4
 300  **/
 301 gboolean
 302 gtk_file_chooser_get_local_only (GtkFileChooser *chooser)
 303 {
 304   gboolean local_only;
 305
 306   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
 307
 308   g_object_get (chooser, "local-only", &local_only, NULL);
 309
 310   return local_only;
 311 }
 312
 313 /**
 314  * gtk_file_chooser_set_select_multiple:
 315  * @chooser: a #GtkFileChooser
 316  * @select_multiple: %TRUE if multiple files can be selected.
 317  *
 318  * Sets whether multiple files can be selected in the file
 319  * selector. If the file selector if in folder mode (see
 320  * gtk_file_selector_set_folder_mode()) then only one folder
 321  * can be selected, without regard to this setting.
 322  *
 323  * Since: 2.4
 324  **/
 325 void
 326 gtk_file_chooser_set_select_multiple (GtkFileChooser *chooser,
 327                                       gboolean        select_multiple)
 328 {
 329   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 330
 331   g_object_set (chooser, "select-multiple", select_multiple, NULL);
 332 }
 333
 334 /**
 335  * gtk_file_chooser_get_select_multiple:
 336  * @chooser: a #GtkFileChooser
 337  *
 338  * Gets whether multiple files can be selected in the file
 339  * selector. See gtk_file_chooser_set_select_multiple().
 340  *
 341  * Return value: %TRUE if multiple files can be selected.
 342  *
 343  * Since: 2.4
 344  **/
 345 gboolean
 346 gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser)
 347 {
 348   gboolean select_multiple;
 349
 350   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
 351
 352   g_object_get (chooser, "select-multiple", &select_multiple, NULL);
 353
 354   return select_multiple;
 355 }
 356
 357 /**
 358  * gtk_file_chooser_get_filename:
 359  * @chooser: a #GtkFileChooser
 360  *
 361  * Gets the filename for the currently selected file in
 362  * the file selector. If multiple files are selected,
 363  * one of the filenames will be returned at random.
 364  *
 365  * Return value: The currently selected filename, or %NULL
 366  *  if no file is selected, or the selected file can't
 367  *  be represented with a local filename. Free with g_free().
 368  *
 369  * Since: 2.4
 370  **/
 371 gchar *
 372 gtk_file_chooser_get_filename (GtkFileChooser *chooser)
 373 {
 374   GtkFileSystem *file_system;
 375   GtkFilePath *path;
 376   gchar *result = NULL;
 377
 378   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 379
 380   file_system = _gtk_file_chooser_get_file_system (chooser);
 381   path = gtk_file_chooser_get_path (chooser);
 382   if (path)
 383     {
 384       result = gtk_file_system_path_to_filename (file_system, path);
 385       gtk_file_path_free (path);
 386     }
 387
 388   return result;
 389 }
 390
 391 /**
 392  * gtk_file_chooser_set_filename:
 393  * @chooser: a #GtkFileChooser
 394  * @filename: the filename to set as current
 395  *
 396  * Sets @filename as the current filename for the the file chooser;
 397  * If the file name isn't in the current folder of @chooser, then the
 398  * current folder of @chooser will be changed to the folder containing
 399  * @filename. This is equivalent to a sequence of
 400  * gtk_file_chooser_unselect_all() followed by gtk_file_chooser_select_filename().
 401  *
 402  * Note that the file must exist, or nothing will be done except
 403  * for the directory change. To pre-enter a filename for the user, as in
 404  * a save-as dialog, use gtk_file_chooser_set_current_name()
 405  *
 406  * Since: 2.4
 407  **/
 408 void
 409 gtk_file_chooser_set_filename (GtkFileChooser *chooser,
 410                                const gchar    *filename)
 411 {
 412   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 413
 414   gtk_file_chooser_unselect_all (chooser);
 415   gtk_file_chooser_select_filename (chooser, filename);
 416 }
 417
 418 /**
 419  * gtk_file_chooser_select_filename:
 420  * @chooser: a #GtkFileChooser
 421  * @filename: the filename to select
 422  *
 423  * Selects a filename. If the file name isn't in the current
 424  * folder of @chooser, then the current folder of @chooser will
 425  * be changed to the folder containing @filename.
 426  *
 427  * Since: 2.4
 428  **/
 429 void
 430 gtk_file_chooser_select_filename (GtkFileChooser *chooser,
 431                                   const gchar    *filename)
 432 {
 433   GtkFileSystem *file_system;
 434   GtkFilePath *path;
 435
 436   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 437   g_return_if_fail (filename != NULL);
 438
 439   file_system = _gtk_file_chooser_get_file_system (chooser);
 440
 441   path = gtk_file_system_filename_to_path (file_system, filename);
 442   if (path)
 443     {
 444       _gtk_file_chooser_select_path (chooser, path);
 445       gtk_file_path_free (path);
 446     }
 447 }
 448
 449 /**
 450  * gtk_file_chooser_unselect_filename:
 451  * @chooser: a #GtkFileChooser
 452  * @filename: the filename to unselect
 453  *
 454  * Unselects a currently selected filename. If the filename
 455  * is not in the current directory, does not exist, or
 456  * is otherwise not currently selected, does nothing.
 457  *
 458  * Since: 2.4
 459  **/
 460 void
 461 gtk_file_chooser_unselect_filename (GtkFileChooser *chooser,
 462                                     const char     *filename)
 463 {
 464   GtkFileSystem *file_system;
 465   GtkFilePath *path;
 466
 467   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 468   g_return_if_fail (filename != NULL);
 469
 470   file_system = _gtk_file_chooser_get_file_system (chooser);
 471
 472   path = gtk_file_system_filename_to_path (file_system, filename);
 473   if (path)
 474     {
 475       _gtk_file_chooser_unselect_path (chooser, path);
 476       gtk_file_path_free (path);
 477     }
 478 }
 479
 480 /* Converts a list of GtkFilePath* to a list of strings using the specified function */
 481 static GSList *
 482 file_paths_to_strings (GtkFileSystem *fs,
 483                        GSList        *paths,
 484                        gchar *      (*convert_func) (GtkFileSystem *fs, const GtkFilePath *path))
 485 {
 486   GSList *strings;
 487
 488   strings = NULL;
 489
 490   for (; paths; paths = paths->next)
 491     {
 492       GtkFilePath *path;
 493       gchar *string;
 494
 495       path = paths->data;
 496       string = (* convert_func) (fs, path);
 497
 498       if (string)
 499         strings = g_slist_prepend (strings, string);
 500     }
 501
 502   return g_slist_reverse (strings);
 503 }
 504
 505 /**
 506  * gtk_file_chooser_get_filenames:
 507  * @chooser: a #GtkFileChooser
 508  *
 509  * Lists all the selected files and subfolders in the current folder of
 510  * @chooser. The returned names are full absolute paths. If files in the current
 511  * folder cannot be represented as local filenames they will be ignored. (See
 512  * gtk_file_chooser_get_uris())
 513  *
 514  * Return value: a #GSList containing the filenames of all selected
 515  *   files and subfolders in the current folder. Free the returned list
 516  *   with g_slist_free(), and the filenames with g_free().
 517  *
 518  * Since: 2.4
 519  **/
 520 GSList *
 521 gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
 522 {
 523   GtkFileSystem *file_system;
 524   GSList *paths;
 525   GSList *result;
 526
 527   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 528
 529   file_system = _gtk_file_chooser_get_file_system (chooser);
 530   paths = _gtk_file_chooser_get_paths (chooser);
 531
 532   result = file_paths_to_strings (file_system, paths, gtk_file_system_path_to_filename);
 533   gtk_file_paths_free (paths);
 534   return result;
 535 }
 536
 537 /**
 538  * gtk_file_chooser_set_current_folder:
 539  * @chooser: a #GtkFileChooser
 540  * @filename: the full path of the new current folder
 541  *
 542  * Sets the current folder for @chooser from a local filename.
 543  * The user will be shown the full contents of the current folder,
 544  * plus user interface elements for navigating to other folders.
 545  *
 546  * Since: 2.4
 547  **/
 548 void
 549 gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
 550                                      const gchar    *filename)
 551 {
 552   GtkFileSystem *file_system;
 553   GtkFilePath *path;
 554
 555   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 556   g_return_if_fail (filename != NULL);
 557
 558   file_system = _gtk_file_chooser_get_file_system (chooser);
 559
 560   path = gtk_file_system_filename_to_path (file_system, filename);
 561   if (path)
 562     {
 563       _gtk_file_chooser_set_current_folder_path (chooser, path);
 564       gtk_file_path_free (path);
 565     }
 566 }
 567
 568 /**
 569  * gtk_file_chooser_get_current_folder:
 570  * @chooser: a #GtkFileChooser
 571  *
 572  * Gets the current folder of @chooser as a local filename.
 573  * See gtk_file_chooser_set_current_folder().
 574  *
 575  * Return value: the full path of the current folder, or %NULL
 576  *  if the current path cannot be represented as a local filename.
 577  *  Free with g_free().
 578  *
 579  * Since: 2.4
 580  **/
 581 gchar *
 582 gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
 583 {
 584   GtkFileSystem *file_system;
 585   GtkFilePath *path;
 586   gchar *filename;
 587
 588   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 589
 590   file_system = _gtk_file_chooser_get_file_system (chooser);
 591
 592   path = _gtk_file_chooser_get_current_folder_path (chooser);
 593   filename = gtk_file_system_path_to_filename (file_system, path);
 594   gtk_file_path_free (path);
 595
 596   return filename;
 597 }
 598
 599 /**
 600  * gtk_file_chooser_set_current_name:
 601  * @chooser: a #GtkFileChooser
 602  * @name: the filename to use, as a UTF-8 string
 603  *
 604  * Sets the current name in the file selector, as if entered
 605  * by the user. Note that the name passed in here is a UTF-8
 606  * string rather than a filename. This function is meant for
 607  * such uses as a suggested name in a "Save As..." dialog.
 608  *
 609  * If you want to preselect a particular existing file, you
 610  * should use gtk_file_chooser_set_filename() instead.
 611  *
 612  * Since: 2.4
 613  **/
 614 void
 615 gtk_file_chooser_set_current_name  (GtkFileChooser *chooser,
 616                                     const gchar    *name)
 617 {
 618   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 619   g_return_if_fail (name != NULL);
 620
 621   GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_name (chooser, name);
 622 }
 623
 624 /**
 625  * gtk_file_chooser_get_uri:
 626  * @chooser: a #GtkFileChooser
 627  *
 628  * Gets the URI for the currently selected file in
 629  * the file selector. If multiple files are selected,
 630  * one of the filenames will be returned at random.
 631  *
 632  * Return value: The currently selected URI, or %NULL
 633  *  if no file is selected. Free with g_free()
 634  *
 635  * Since: 2.4
 636  **/
 637 gchar *
 638 gtk_file_chooser_get_uri (GtkFileChooser *chooser)
 639 {
 640   GtkFileSystem *file_system;
 641   GtkFilePath *path;
 642   gchar *result = NULL;
 643
 644   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 645
 646   file_system = _gtk_file_chooser_get_file_system (chooser);
 647   path = gtk_file_chooser_get_path (chooser);
 648   if (path)
 649     {
 650       result = gtk_file_system_path_to_uri (file_system, path);
 651       gtk_file_path_free (path);
 652     }
 653
 654   return result;
 655 }
 656
 657 /**
 658  * gtk_file_chooser_set_uri:
 659  * @chooser: a #GtkFileChooser
 660  * @uri: the URI to set as current
 661  *
 662  * Sets the file referred to by @uri as the current file for the the
 663  * file chooser; If the file name isn't in the current folder of @chooser,
 664  * then the current folder of @chooser will be changed to the folder containing
 665  * @uri. This is equivalent to a sequence of gtk_file_chooser_unselect_all()
 666  * followed by gtk_file_chooser_select_uri().
 667  *
 668  * Note that the file must exist, or nothing will be done except
 669  * for the directory change. To pre-enter a filename for the user, as in
 670  * a save-as dialog, use gtk_file_chooser_set_current_name()
 671  *
 672  * Since: 2.4
 673  **/
 674 void
 675 gtk_file_chooser_set_uri (GtkFileChooser *chooser,
 676                           const char     *uri)
 677 {
 678   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 679
 680   gtk_file_chooser_unselect_all (chooser);
 681   gtk_file_chooser_select_uri (chooser, uri);
 682 }
 683
 684 /**
 685  * gtk_file_chooser_select_uri:
 686  * @chooser: a #GtkFileChooser
 687  * @uri: the URI to select
 688  *
 689  * Selects the file to by @uri. If the URI doesn't refer to a
 690  * file in the current folder of @chooser, then the current folder of
 691  * @chooser will be changed to the folder containing @filename.
 692  *
 693  * Since: 2.4
 694  **/
 695 void
 696 gtk_file_chooser_select_uri (GtkFileChooser *chooser,
 697                              const char     *uri)
 698 {
 699   GtkFileSystem *file_system;
 700   GtkFilePath *path;
 701
 702   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 703   g_return_if_fail (uri != NULL);
 704
 705   file_system = _gtk_file_chooser_get_file_system (chooser);
 706
 707   path = gtk_file_system_uri_to_path (file_system, uri);
 708   if (path)
 709     {
 710       _gtk_file_chooser_select_path (chooser, path);
 711       gtk_file_path_free (path);
 712     }
 713 }
 714
 715 /**
 716  * gtk_file_chooser_unselect_uri:
 717  * @chooser: a #GtkFileChooser
 718  * @uri: the URI to unselect
 719  *
 720  * Unselects the file referred to by @uri. If the file
 721  * is not in the current directory, does not exist, or
 722  * is otherwise not currently selected, does nothing.
 723  *
 724  * Since: 2.4
 725  **/
 726 void
 727 gtk_file_chooser_unselect_uri (GtkFileChooser *chooser,
 728                                const char     *uri)
 729 {
 730   GtkFileSystem *file_system;
 731   GtkFilePath *path;
 732
 733   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 734   g_return_if_fail (uri != NULL);
 735
 736   file_system = _gtk_file_chooser_get_file_system (chooser);
 737
 738   path = gtk_file_system_uri_to_path (file_system, uri);
 739   if (path)
 740     {
 741       _gtk_file_chooser_unselect_path (chooser, path);
 742       gtk_file_path_free (path);
 743     }
 744 }
 745
 746 /**
 747  * gtk_file_chooser_select_all:
 748  * @chooser: a #GtkFileChooser
 749  *
 750  * Selects all the files in the current folder of a file chooser.
 751  *
 752  * Since: 2.4
 753  **/
 754 void
 755 gtk_file_chooser_select_all (GtkFileChooser *chooser)
 756 {
 757   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 758
 759   GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_all (chooser);
 760 }
 761
 762 /**
 763  * gtk_file_chooser_unselect_all:
 764  * @chooser: a #GtkFileChooser
 765  *
 766  * Unselects all the files in the current folder of a file chooser.
 767  *
 768  * Since: 2.4
 769  **/
 770 void
 771 gtk_file_chooser_unselect_all (GtkFileChooser *chooser)
 772 {
 773
 774   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 775
 776   GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_all (chooser);
 777 }
 778
 779 /**
 780  * gtk_file_chooser_get_uris:
 781  * @chooser: a #GtkFileChooser
 782  *
 783  * Lists all the selected files and subfolders in the current folder of
 784  * @chooser. The returned names are full absolute URIs.
 785  *
 786  * Return value: a #GSList containing the URIs of all selected
 787  *   files and subfolders in the current folder. Free the returned list
 788  *   with g_slist_free(), and the filenames with g_free().
 789  *
 790  * Since: 2.4
 791  **/
 792 GSList *
 793 gtk_file_chooser_get_uris (GtkFileChooser *chooser)
 794 {
 795   GtkFileSystem *file_system;
 796   GSList *paths;
 797   GSList *result;
 798
 799   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 800
 801   file_system = _gtk_file_chooser_get_file_system (chooser);
 802   paths = _gtk_file_chooser_get_paths (chooser);
 803
 804   result = file_paths_to_strings (file_system, paths, gtk_file_system_path_to_uri);
 805   gtk_file_paths_free (paths);
 806   return result;
 807 }
 808
 809 /**
 810  * gtk_file_chooser_set_current_folder_uri:
 811  * @chooser: a #GtkFileChooser
 812  * @uri: the URI for the new current folder
 813  *
 814  * Sets the current folder for @chooser from an URI.
 815  * The user will be shown the full contents of the current folder,
 816  * plus user interface elements for navigating to other folders.
 817  *
 818  * Since: 2.4
 819  **/
 820 void
 821 gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser,
 822                                          const gchar    *uri)
 823 {
 824   GtkFileSystem *file_system;
 825   GtkFilePath *path;
 826
 827   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 828   g_return_if_fail (uri != NULL);
 829
 830   file_system = _gtk_file_chooser_get_file_system (chooser);
 831
 832   path = gtk_file_system_uri_to_path (file_system, uri);
 833   if (path)
 834     {
 835       _gtk_file_chooser_set_current_folder_path (chooser, path);
 836       gtk_file_path_free (path);
 837     }
 838 }
 839
 840 /**
 841  * gtk_file_chooser_get_current_folder_uri:
 842  * @chooser: a #GtkFileChooser
 843  *
 844  * Gets the current folder of @chooser as an URI.
 845  * See gtk_file_chooser_set_current_folder_uri().
 846  *
 847  * Return value: the URI for the current folder.
 848  *  Free with g_free().
 849  *
 850  * Since: 2.4
 851  */
 852 gchar *
 853 gtk_file_chooser_get_current_folder_uri (GtkFileChooser *chooser)
 854 {
 855   GtkFileSystem *file_system;
 856   GtkFilePath *path;
 857   gchar *uri;
 858
 859   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 860
 861   file_system = _gtk_file_chooser_get_file_system (chooser);
 862
 863   path = _gtk_file_chooser_get_current_folder_path (chooser);
 864   uri = gtk_file_system_path_to_uri (file_system, path);
 865   gtk_file_path_free (path);
 866
 867   return uri;
 868 }
 869
 870 /**
 871  * _gtk_file_chooser_set_current_folder_path:
 872  * @chooser: a #GtkFileChooser
 873  * @path: the #GtkFilePath for the new folder
 874  *
 875  * Sets the current folder for @chooser from a #GtkFilePath.
 876  * Internal function, see gtk_file_chooser_set_current_folder_uri().
 877  *
 878  * Since: 2.4
 879  **/
 880 void
 881 _gtk_file_chooser_set_current_folder_path (GtkFileChooser    *chooser,
 882                                            const GtkFilePath *path)
 883 {
 884   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 885   g_return_if_fail (path != NULL);
 886
 887   GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_folder (chooser, path);
 888 }
 889
 890 /**
 891  * _gtk_file_chooser_get_current_folder_path:
 892  * @chooser: a #GtkFileChooser
 893  *
 894  * Gets the current folder of @chooser as #GtkFilePath.
 895  * See gtk_file_chooser_get_current_folder_uri().
 896  *
 897  * Return value: the #GtkFilePath for the current folder.
 898  * Free with gtk_file_path_free().
 899  *
 900  * Since: 2.4
 901  */
 902 GtkFilePath *
 903 _gtk_file_chooser_get_current_folder_path (GtkFileChooser *chooser)
 904 {
 905   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 906
 907   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_folder (chooser);
 908 }
 909
 910 /**
 911  * _gtk_file_chooser_select_path:
 912  * @chooser: a #GtkFileChooser
 913  * @path: the path to select
 914  *
 915  * Selects the file referred to by @path. An internal function. See
 916  * _gtk_file_chooser_select_uri().
 917  *
 918  * Since: 2.4
 919  **/
 920 void
 921 _gtk_file_chooser_select_path (GtkFileChooser    *chooser,
 922                                const GtkFilePath *path)
 923 {
 924   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 925
 926   GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_path (chooser, path);
 927 }
 928
 929 /**
 930  * _gtk_file_chooser_unselect_path:
 931  * @chooser: a #GtkFileChooser
 932  * @path: the filename to path
 933  *
 934  * Unselects the file referred to by @path. An internal
 935  * function. See _gtk_file_chooser_unselect_uri().
 936  *
 937  * Since: 2.4
 938  **/
 939 void
 940 _gtk_file_chooser_unselect_path (GtkFileChooser    *chooser,
 941                                  const GtkFilePath *path)
 942 {
 943   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 944
 945   GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_path (chooser, path);
 946 }
 947
 948 /**
 949  * _gtk_file_chooser_get_paths:
 950  * @chooser: a #GtkFileChooser
 951  *
 952  * Lists all the selected files and subfolders in the current folder of @chooser
 953  * as #GtkFilePath. An internal function, see gtk_file_chooser_get_uris().
 954  *
 955  * Return value: a #GSList containing a #GtkFilePath for each selected
 956  *   file and subfolder in the current folder.  Free the returned list
 957  *   with g_slist_free(), and the paths with gtk_file_path_free().
 958  *
 959  * Since: 2.4
 960  **/
 961 GSList *
 962 _gtk_file_chooser_get_paths (GtkFileChooser *chooser)
 963 {
 964   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 965
 966   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_paths (chooser);
 967 }
 968
 969 static GtkFilePath *
 970 gtk_file_chooser_get_path (GtkFileChooser *chooser)
 971 {
 972   GSList *list;
 973   GtkFilePath *result = NULL;
 974
 975   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 976
 977   list = _gtk_file_chooser_get_paths (chooser);
 978   if (list)
 979     {
 980       result = list->data;
 981       list = g_slist_delete_link (list, list);
 982       gtk_file_paths_free (list);
 983     }
 984
 985   return result;
 986 }
 987
 988 /**
 989  * _gtk_file_chooser_get_file_system:
 990  * @chooser: a #GtkFileChooser
 991  *
 992  * Gets the #GtkFileSystem of @chooser; this is an internal
 993  * implementation detail, used for conversion between paths
 994  * and filenames and URIs.
 995  *
 996  * Return value: the file system for @chooser.
 997  *
 998  * Since: 2.4
 999  **/
1000 GtkFileSystem *
1001 _gtk_file_chooser_get_file_system (GtkFileChooser *chooser)
1002 {
1003   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1004
1005   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_file_system (chooser);
1006 }
1007
1008 /* Preview widget
1009  */
1010 /**
1011  * gtk_file_chooser_set_preview_widget:
1012  * @chooser: a #GtkFileChooser
1013  * @preview_widget: widget for displaying preview.
1014  *
1015  * Sets an application-supplied widget to use to display a custom preview
1016  * of the currently selected file. To implement a preview, after setting the
1017  * preview widget, you connect to the ::selection-changed
1018  * signal, and call gtk_file_chooser_get_preview_filename() or
1019  * gtk_file_chooser_get_preview_uri() on each change. If you can
1020  * display a preview of the new file, update your widget and
1021  * set the preview active using gtk_file_chooser_set_preview_widget_active().
1022  * Otherwise, set the preview inactive.
1023  *
1024  * When there is no application-supplied preview widget, or the
1025  * application-supplied preview widget is not active, the file chooser
1026  * may display an internally generated preview of the current file or
1027  * it may display no preview at all.
1028  *
1029  * Since: 2.4
1030  **/
1031 void
1032 gtk_file_chooser_set_preview_widget (GtkFileChooser *chooser,
1033                                      GtkWidget      *preview_widget)
1034 {
1035   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1036
1037   g_object_set (chooser, "preview-widget", preview_widget, NULL);
1038 }
1039
1040 /**
1041  * gtk_file_chooser_get_preview_widget:
1042  * @chooser: a #GtkFileChooser
1043  *
1044  * Gets the current preview widget; see
1045  * gtk_file_chooser_set_preview_widget().
1046  *
1047  * Return value: the current preview widget, or %NULL
1048  *
1049  * Since: 2.4
1050  **/
1051 GtkWidget *
1052 gtk_file_chooser_get_preview_widget (GtkFileChooser *chooser)
1053 {
1054   GtkWidget *preview_widget;
1055
1056   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1057
1058   g_object_get (chooser, "preview-widget", &preview_widget, NULL);
1059
1060   /* Horrid hack; g_object_get() refs returned objects but
1061    * that contradicts the memory management conventions
1062    * for accessors.
1063    */
1064   if (preview_widget)
1065     g_object_unref (preview_widget);
1066
1067   return preview_widget;
1068 }
1069
1070 /**
1071  * gtk_file_chooser_set_preview_widget_active:
1072  * @chooser: a #GtkFileChooser
1073  * @active: whether to display the user-specified preview widget
1074  *
1075  * Sets whether the preview widget set by
1076  * gtk_file_chooser_set_preview_widget_active() should be shown for the
1077  * current filename. When @active is set to false, the file chooser
1078  * may display an internally generated preview of the current file
1079  * or it may display no preview at all. See
1080  * gtk_file_chooser_set_preview_widget() for more details.
1081  *
1082  * Since: 2.4
1083  **/
1084 void
1085 gtk_file_chooser_set_preview_widget_active (GtkFileChooser *chooser,
1086                                             gboolean        active)
1087 {
1088   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1089
1090   g_object_set (chooser, "preview-widget-active", active, NULL);
1091 }
1092
1093 /**
1094  * gtk_file_chooser_get_preview_widget_active:
1095  * @chooser: a #GtkFileChooser
1096  *
1097  * Gets whether the preview widget set by
1098  * gtk_file_chooser_set_preview_widget_active() should be shown for the
1099  * current filename. See gtk_file_chooser_set_preview_widget_active().
1100  *
1101  * Return value: %TRUE if the preview widget is active for the
1102  *  current filename.
1103  *
1104  * Since: 2.4
1105  **/
1106 gboolean
1107 gtk_file_chooser_get_preview_widget_active (GtkFileChooser *chooser)
1108 {
1109   gboolean active;
1110
1111   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1112
1113   g_object_get (chooser, "preview-widget-active", &active, NULL);
1114
1115   return active;
1116 }
1117
1118 /**
1119  * gtk_file_chooser_get_preview_filename:
1120  * @chooser: a #GtkFileChooser
1121  *
1122  * Gets the filename that should be previewed in a custom preview
1123  * Internal function, see gtk_file_chooser_get_preview_uri().
1124  *
1125  * Return value: the #GtkFilePath for the file to preview, or %NULL if no file
1126  *  is selected. Free with gtk_file_path_free().
1127  *
1128  * Since: 2.4
1129  **/
1130 GtkFilePath *
1131 _gtk_file_chooser_get_preview_path (GtkFileChooser *chooser)
1132 {
1133   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1134
1135   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_preview_path (chooser);
1136 }
1137
1138 /**
1139  * _gtk_file_chooser_add_shortcut_folder:
1140  * @chooser: a #GtkFileChooser
1141  * @path: path of the folder to add
1142  * @error: location to store error, or %NULL
1143  *
1144  * Adds a folder to be displayed with the shortcut folders in a file chooser.
1145  * Internal function, see gtk_file_chooser_add_shortcut_folder().
1146  *
1147  * Return value: %TRUE if the folder could be added successfully, %FALSE
1148  * otherwise.
1149  *
1150  * Since: 2.4
1151  **/
1152 gboolean
1153 _gtk_file_chooser_add_shortcut_folder (GtkFileChooser    *chooser,
1154                                        const GtkFilePath *path,
1155                                        GError           **error)
1156 {
1157   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1158   g_return_val_if_fail (path != NULL, FALSE);
1159
1160   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_shortcut_folder (chooser, path, error);
1161 }
1162
1163 /**
1164  * _gtk_file_chooser_remove_shortcut_folder:
1165  * @chooser: a #GtkFileChooser
1166  * @path: path of the folder to remove
1167  * @error: location to store error, or %NULL
1168  *
1169  * Removes a folder from the shortcut folders in a file chooser.  Internal
1170  * function, see gtk_file_chooser_remove_shortcut_folder().
1171  *
1172  * Return value: %TRUE if the folder could be removed successfully, %FALSE
1173  * otherwise.
1174  *
1175  * Since: 2.4
1176  **/
1177 gboolean
1178 _gtk_file_chooser_remove_shortcut_folder (GtkFileChooser    *chooser,
1179                                           const GtkFilePath *path,
1180                                           GError           **error)
1181 {
1182   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1183   g_return_val_if_fail (path != NULL, FALSE);
1184
1185   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_shortcut_folder (chooser, path, error);
1186 }
1187
1188 /**
1189  * gtk_file_chooser_get_preview_filename:
1190  * @chooser: a #GtkFileChooser
1191  *
1192  * Gets the filename that should be previewed in a custom preview
1193  * widget. See gtk_file_chooser_set_preview_widget().
1194  *
1195  * Return value: the filename to preview, or %NULL if no file
1196  *  is selected, or if the selected file cannot be represented
1197  *  as a local filename. Free with g_free()
1198  *
1199  * Since: 2.4
1200  **/
1201 char *
1202 gtk_file_chooser_get_preview_filename (GtkFileChooser *chooser)
1203 {
1204   GtkFileSystem *file_system;
1205   GtkFilePath *path;
1206   gchar *result = NULL;
1207
1208   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1209
1210   file_system = _gtk_file_chooser_get_file_system (chooser);
1211   path = _gtk_file_chooser_get_preview_path (chooser);
1212   if (path)
1213     {
1214       result = gtk_file_system_path_to_filename (file_system, path);
1215       gtk_file_path_free (path);
1216     }
1217
1218   return result;
1219 }
1220
1221 /**
1222  * gtk_file_chooser_get_preview_uri:
1223  * @chooser: a #GtkFileChooser
1224  *
1225  * Gets the URI that should be previewed in a custom preview
1226  * widget. See gtk_file_chooser_set_preview_widget().
1227  *
1228  * Return value: the URI for the file to preview, or %NULL if no file is
1229  * selected. Free with g_free().
1230  *
1231  * Since: 2.4
1232  **/
1233 char *
1234 gtk_file_chooser_get_preview_uri (GtkFileChooser *chooser)
1235 {
1236   GtkFileSystem *file_system;
1237   GtkFilePath *path;
1238   gchar *result = NULL;
1239
1240   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1241
1242   file_system = _gtk_file_chooser_get_file_system (chooser);
1243   path = _gtk_file_chooser_get_preview_path (chooser);
1244   if (path)
1245     {
1246       result = gtk_file_system_path_to_uri (file_system, path);
1247       gtk_file_path_free (path);
1248     }
1249
1250   return result;
1251 }
1252
1253 /**
1254  * gtk_file_chooser_set_extra_widget:
1255  * @chooser: a #GtkFileChooser
1256  * @extra_widget: widget for extra options
1257  *
1258  * Sets an application-supplied widget to provide extra options to the user.
1259  *
1260  * Since: 2.4
1261  **/
1262 void
1263 gtk_file_chooser_set_extra_widget (GtkFileChooser *chooser,
1264                                    GtkWidget      *extra_widget)
1265 {
1266   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1267
1268   g_object_set (chooser, "extra-widget", extra_widget, NULL);
1269 }
1270
1271 /**
1272  * gtk_file_chooser_get_extra_widget:
1273  * @chooser: a #GtkFileChooser
1274  *
1275  * Gets the current preview widget; see
1276  * gtk_file_chooser_set_extra_widget().
1277  *
1278  * Return value: the current extra widget, or %NULL
1279  *
1280  * Since: 2.4
1281  **/
1282 GtkWidget *
1283 gtk_file_chooser_get_extra_widget (GtkFileChooser *chooser)
1284 {
1285   GtkWidget *extra_widget;
1286
1287   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1288
1289   g_object_get (chooser, "extra-widget", &extra_widget, NULL);
1290
1291   /* Horrid hack; g_object_get() refs returned objects but
1292    * that contradicts the memory management conventions
1293    * for accessors.
1294    */
1295   if (extra_widget)
1296     g_object_unref (extra_widget);
1297
1298   return extra_widget;
1299 }
1300
1301 /**
1302  * gtk_file_chooser_add_filter:
1303  * @chooser: a #GtkFileChooser
1304  * @filter: a #GtkFileFilter
1305  *
1306  * Adds @filter to the list of filters that the user can select between.
1307  * When a filter is selected, only files that are passed by that
1308  * filter are displayed.
1309  *
1310  * Since: 2.4
1311  **/
1312 void
1313 gtk_file_chooser_add_filter (GtkFileChooser *chooser,
1314                              GtkFileFilter  *filter)
1315 {
1316   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1317
1318   GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_filter (chooser, filter);
1319 }
1320
1321 /**
1322  * gtk_file_chooser_remove_filter:
1323  * @chooser: a #GtkFileChooser
1324  * @filter: a #GtkFileFilter
1325  *
1326  * Removes @filter from the list of filters that the user can select between.
1327  *
1328  * Since: 2.4
1329  **/
1330 void
1331 gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
1332                                 GtkFileFilter  *filter)
1333 {
1334   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1335
1336   GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_filter (chooser, filter);
1337 }
1338
1339 /**
1340  * gtk_file_chooser_list_filters:
1341  * @chooser: a #GtkFileChooser
1342  *
1343  * Lists the current set of user-selectable filters; see
1344  * gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter().
1345  *
1346  * Return value: a #GSList containing the current set of
1347  *  user selectable filters. The contents of the list are
1348  *  owned by GTK+, but you must free the list itself with
1349  *  g_slist_free() when you are done with it.
1350  *
1351  * Since: 2.4
1352  **/
1353 GSList *
1354 gtk_file_chooser_list_filters  (GtkFileChooser *chooser)
1355 {
1356   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1357
1358   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->list_filters (chooser);
1359 }
1360
1361 /**
1362  * gtk_file_chooser_set_filter:
1363  * @chooser: a #GtkFileChooser
1364  * @filter: a #GtkFileFilter
1365  *
1366  * Sets the current filter; only the files that pass the
1367  * filter will be displayed. If the user-selectable list of filters
1368  * is non-empty, then the filter should be one of the filters
1369  * in that list. Setting the current filter when the list of
1370  * filters is empty is useful if you want to restrict the displayed
1371  * set of files without letting the user change it.
1372  *
1373  * Since: 2.4
1374  **/
1375 void
1376 gtk_file_chooser_set_filter (GtkFileChooser *chooser,
1377                              GtkFileFilter  *filter)
1378 {
1379   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1380   g_return_if_fail (GTK_IS_FILE_FILTER (filter));
1381
1382   g_object_set (chooser, "filter", filter, NULL);
1383 }
1384
1385 /**
1386  * gtk_file_chooser_get_filter:
1387  * @chooser: a #GtkFileChooser
1388  *
1389  * Gets the current filter; see gtk_file_chooser_set_filter().
1390  *
1391  * Return value: the current filter, or %NULL
1392  *
1393  * Since: 2.4
1394  **/
1395 GtkFileFilter *
1396 gtk_file_chooser_get_filter (GtkFileChooser *chooser)
1397 {
1398   GtkFileFilter *filter;
1399
1400   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1401
1402   g_object_get (chooser, "filter", &filter, NULL);
1403   /* Horrid hack; g_object_get() refs returned objects but
1404    * that contradicts the memory management conventions
1405    * for accessors.
1406    */
1407   if (filter)
1408     g_object_unref (filter);
1409
1410   return filter;
1411 }
1412
1413 /**
1414  * gtk_file_chooser_add_shortcut_folder:
1415  * @chooser: a #GtkFileChooser
1416  * @folder: filename of the folder to add
1417  * @error: location to store error, or %NULL
1418  *
1419  * Adds a folder to be displayed with the shortcut folders in a file chooser.
1420  * Note that shortcut folders do not get saved, as they are provided by the
1421  * application.  For example, you can use this to add a
1422  * "/usr/share/mydrawprogram/Clipart" folder to the volume list.
1423  *
1424  * Return value: %TRUE if the folder could be added successfully, %FALSE
1425  * otherwise.  In the latter case, the @error will be set as appropriate.
1426  *
1427  * Since: 2.4
1428  **/
1429 gboolean
1430 gtk_file_chooser_add_shortcut_folder (GtkFileChooser    *chooser,
1431                                       const char        *folder,
1432                                       GError           **error)
1433 {
1434   GtkFilePath *path;
1435   gboolean result;
1436
1437   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1438   g_return_val_if_fail (folder != NULL, FALSE);
1439
1440   path = gtk_file_system_filename_to_path (_gtk_file_chooser_get_file_system (chooser), folder);
1441   if (!path)
1442     {
1443       g_set_error (error,
1444                    GTK_FILE_CHOOSER_ERROR,
1445                    GTK_FILE_CHOOSER_ERROR_BAD_FILENAME,
1446                    _("Invalid filename: %s"),
1447                    folder);
1448       return FALSE;
1449     }
1450
1451   result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_shortcut_folder (chooser, path, error);
1452
1453   gtk_file_path_free (path);
1454
1455   return result;
1456 }
1457
1458 /**
1459  * gtk_file_chooser_remove_shortcut_folder:
1460  * @chooser: a #GtkFileChooser
1461  * @folder: filename of the folder to remove
1462  * @error: location to store error, or %NULL
1463  *
1464  * Removes a folder from a file chooser's list of shortcut folders.
1465  *
1466  * Return value: %TRUE if the operation succeeds, %FALSE otherwise.
1467  * In the latter case, the @error will be set as appropriate.
1468  *
1469  * See also: gtk_file_chooser_add_shortcut_folder()
1470  *
1471  * Since: 2.4
1472  **/
1473 gboolean
1474 gtk_file_chooser_remove_shortcut_folder (GtkFileChooser    *chooser,
1475                                          const char        *folder,
1476                                          GError           **error)
1477 {
1478   GtkFilePath *path;
1479   gboolean result;
1480
1481   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1482   g_return_val_if_fail (folder != NULL, FALSE);
1483
1484   path = gtk_file_system_filename_to_path (_gtk_file_chooser_get_file_system (chooser), folder);
1485   if (!path)
1486     {
1487       g_set_error (error,
1488                    GTK_FILE_CHOOSER_ERROR,
1489                    GTK_FILE_CHOOSER_ERROR_BAD_FILENAME,
1490                    _("Invalid filename: %s"),
1491                    folder);
1492       return FALSE;
1493     }
1494
1495   result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_shortcut_folder (chooser, path, error);
1496
1497   gtk_file_path_free (path);
1498
1499   return result;
1500 }
1501
1502 /**
1503  * gtk_file_chooser_list_shortcut_folders:
1504  * @chooser: a #GtkFileChooser
1505  *
1506  * Queries the list of shortcut folders in the file chooser, as set by
1507  * gtk_file_chooser_set_shortcut_folders().
1508  *
1509  * Return value: A list of folder filenames, or %NULL if there are no shortcut
1510  * folders.  Free the returned list with g_slist_free(), and the filenames with
1511  * g_free().
1512  *
1513  * Since: 2.4
1514  **/
1515 GSList *
1516 gtk_file_chooser_list_shortcut_folders (GtkFileChooser *chooser)
1517 {
1518   GSList *folders;
1519   GSList *result;
1520
1521   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1522
1523   folders = GTK_FILE_CHOOSER_GET_IFACE (chooser)->list_shortcut_folders (chooser);
1524
1525   result = file_paths_to_strings (_gtk_file_chooser_get_file_system (chooser),
1526                                   folders,
1527                                   gtk_file_system_path_to_filename);
1528   gtk_file_paths_free (folders);
1529   return result;
1530 }
1531
1532 /**
1533  * gtk_file_chooser_add_shortcut_folder_uri:
1534  * @chooser: a #GtkFileChooser
1535  * @uri: URI of the folder to add
1536  * @error: location to store error, or %NULL
1537  *
1538  * Adds a folder URI to be displayed with the shortcut folders in a file
1539  * chooser.  Note that shortcut folders do not get saved, as they are provided
1540  * by the application.  For example, you can use this to add a
1541  * "file:///usr/share/mydrawprogram/Clipart" folder to the volume list.
1542  *
1543  * Return value: %TRUE if the folder could be added successfully, %FALSE
1544  * otherwise.  In the latter case, the @error will be set as appropriate.
1545  *
1546  * Since: 2.4
1547  **/
1548 gboolean
1549 gtk_file_chooser_add_shortcut_folder_uri (GtkFileChooser    *chooser,
1550                                           const char        *uri,
1551                                           GError           **error)
1552 {
1553   GtkFilePath *path;
1554   gboolean result;
1555
1556   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1557   g_return_val_if_fail (uri != NULL, FALSE);
1558
1559   path = gtk_file_system_uri_to_path (_gtk_file_chooser_get_file_system (chooser), uri);
1560   if (!path)
1561     {
1562       g_set_error (error,
1563                    GTK_FILE_CHOOSER_ERROR,
1564                    GTK_FILE_CHOOSER_ERROR_BAD_FILENAME,
1565                    _("Invalid filename: %s"),
1566                    uri);
1567       return FALSE;
1568     }
1569
1570   result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_shortcut_folder (chooser, path, error);
1571
1572   gtk_file_path_free (path);
1573
1574   return result;
1575 }
1576
1577 /**
1578  * gtk_file_chooser_remove_shortcut_folder_uri:
1579  * @chooser: a #GtkFileChooser
1580  * @uri: URI of the folder to remove
1581  * @error: location to store error, or %NULL
1582  *
1583  * Removes a folder URI from a file chooser's list of shortcut folders.
1584  *
1585  * Return value: %TRUE if the operation succeeds, %FALSE otherwise.
1586  * In the latter case, the @error will be set as appropriate.
1587  *
1588  * See also: gtk_file_chooser_add_shortcut_folder_uri()
1589  *
1590  * Since: 2.4
1591  **/
1592 gboolean
1593 gtk_file_chooser_remove_shortcut_folder_uri (GtkFileChooser    *chooser,
1594                                              const char        *uri,
1595                                              GError           **error)
1596 {
1597   GtkFilePath *path;
1598   gboolean result;
1599
1600   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1601   g_return_val_if_fail (uri != NULL, FALSE);
1602
1603   path = gtk_file_system_filename_to_path (_gtk_file_chooser_get_file_system (chooser), uri);
1604   if (!path)
1605     {
1606       g_set_error (error,
1607                    GTK_FILE_CHOOSER_ERROR,
1608                    GTK_FILE_CHOOSER_ERROR_BAD_FILENAME,
1609                    _("Invalid filename: %s"),
1610                    uri);
1611       return FALSE;
1612     }
1613
1614   result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_shortcut_folder (chooser, path, error);
1615
1616   gtk_file_path_free (path);
1617
1618   return result;
1619 }
1620
1621 /**
1622  * gtk_file_chooser_list_shortcut_folder_uris:
1623  * @chooser: a #GtkFileChooser
1624  *
1625  * Queries the list of shortcut folders in the file chooser, as set by
1626  * gtk_file_chooser_set_shortcut_folder_uris().
1627  *
1628  * Return value: A list of folder URIs, or %NULL if there are no shortcut
1629  * folders.  Free the returned list with g_slist_free(), and the URIs with
1630  * g_free().
1631  *
1632  * Since: 2.4
1633  **/
1634 GSList *
1635 gtk_file_chooser_list_shortcut_folder_uris (GtkFileChooser *chooser)
1636 {
1637   GSList *folders;
1638   GSList *result;
1639
1640   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1641
1642   folders = GTK_FILE_CHOOSER_GET_IFACE (chooser)->list_shortcut_folders (chooser);
1643
1644   result = file_paths_to_strings (_gtk_file_chooser_get_file_system (chooser),
1645                                   folders,
1646                                   gtk_file_system_path_to_uri);
1647   gtk_file_paths_free (folders);
1648   return result;
1649 }