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