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