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

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

30
static void gtk_file_chooser_class_init (gpointer g_iface);
Owen Taylor's avatar
Owen Taylor committed
31 32 33 34 35 36 37 38

GType
gtk_file_chooser_get_type (void)
{
  static GType file_chooser_type = 0;

  if (!file_chooser_type)
    {
Matthias Clasen's avatar
Matthias Clasen committed
39 40 41
      file_chooser_type = g_type_register_static_simple (G_TYPE_INTERFACE,
							 I_("GtkFileChooser"),
							 sizeof (GtkFileChooserIface),
42
							 (GClassInitFunc) gtk_file_chooser_class_init,
Matthias Clasen's avatar
Matthias Clasen committed
43 44
							 0, NULL, 0);
      
45
      g_type_interface_add_prerequisite (file_chooser_type, GTK_TYPE_WIDGET);
Owen Taylor's avatar
Owen Taylor committed
46 47 48 49 50
    }

  return file_chooser_type;
}

51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
static gboolean
confirm_overwrite_accumulator (GSignalInvocationHint *ihint,
			       GValue                *return_accu,
			       const GValue          *handler_return,
			       gpointer               dummy)
{
  gboolean continue_emission;
  GtkFileChooserConfirmation conf;

  conf = g_value_get_enum (handler_return);
  g_value_set_enum (return_accu, conf);
  continue_emission = (conf == GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM);

  return continue_emission;
}

Owen Taylor's avatar
Owen Taylor committed
67
static void
68
gtk_file_chooser_class_init (gpointer g_iface)
Owen Taylor's avatar
Owen Taylor committed
69
{
70
  GType iface_type = G_TYPE_FROM_INTERFACE (g_iface);
Owen Taylor's avatar
Owen Taylor committed
71

72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
  /**
   * GtkFileChooser::current-folder-changed
   * @chooser: the object which received the signal.
   *
   * This signal is emitted when the current folder in a #GtkFileChooser
   * changes.  This can happen due to the user performing some action that
   * changes folders, such as selecting a bookmark or visiting a folder on the
   * file list.  It can also happen as a result of calling a function to
   * explicitly change the current folder in a file chooser.
   *
   * Normally you do not need to connect to this signal, unless you need to keep
   * track of which folder a file chooser is showing.
   *
   * See also:  gtk_file_chooser_set_current_folder(),
   * gtk_file_chooser_get_current_folder(),
   * gtk_file_chooser_set_current_folder_uri(),
   * gtk_file_chooser_get_current_folder_uri().
   */
Matthias Clasen's avatar
Matthias Clasen committed
90
  g_signal_new (I_("current-folder-changed"),
91 92 93 94 95 96
		iface_type,
		G_SIGNAL_RUN_LAST,
		G_STRUCT_OFFSET (GtkFileChooserIface, current_folder_changed),
		NULL, NULL,
		g_cclosure_marshal_VOID__VOID,
		G_TYPE_NONE, 0);
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116

  /**
   * GtkFileChooser::selection-changed
   * @chooser: the object which received the signal.
   *
   * This signal is emitted when there is a change in the set of selected files
   * in a #GtkFileChooser.  This can happen when the user modifies the selection
   * with the mouse or the keyboard, or when explicitly calling functions to
   * change the selection.
   *
   * Normally you do not need to connect to this signal, as it is easier to wait
   * for the file chooser to finish running, and then to get the list of
   * selected files using the functions mentioned below.
   *
   * See also: gtk_file_chooser_select_filename(),
   * gtk_file_chooser_unselect_filename(), gtk_file_chooser_get_filename(),
   * gtk_file_chooser_get_filenames(), gtk_file_chooser_select_uri(),
   * gtk_file_chooser_unselect_uri(), gtk_file_chooser_get_uri(),
   * gtk_file_chooser_get_uris().
   */
Matthias Clasen's avatar
Matthias Clasen committed
117
  g_signal_new (I_("selection-changed"),
118 119 120 121 122 123
		iface_type,
		G_SIGNAL_RUN_LAST,
		G_STRUCT_OFFSET (GtkFileChooserIface, selection_changed),
		NULL, NULL,
		g_cclosure_marshal_VOID__VOID,
		G_TYPE_NONE, 0);
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139

  /**
   * GtkFileChooser::update-preview
   * @chooser: the object which received the signal.
   *
   * This signal is emitted when the preview in a file chooser should be
   * regenerated.  For example, this can happen when the currently selected file
   * changes.  You should use this signal if you want your file chooser to have
   * a preview widget.
   *
   * Once you have installed a preview widget with
   * gtk_file_chooser_set_preview_widget(), you should update it when this
   * signal is emitted.  You can use the functions
   * gtk_file_chooser_get_preview_filename() or
   * gtk_file_chooser_get_preview_uri() to get the name of the file to preview.
   * Your widget may not be able to preview all kinds of files; your callback
140
   * must call gtk_file_chooser_set_preview_widget_active() to inform the file
141 142 143 144 145 146 147 148 149 150
   * chooser about whether the preview was generated successfully or not.
   *
   * Please see the example code in <xref linkend="gtkfilechooser-preview"/>.
   *
   * See also: gtk_file_chooser_set_preview_widget(),
   * gtk_file_chooser_set_preview_widget_active(),
   * gtk_file_chooser_set_use_preview_label(),
   * gtk_file_chooser_get_preview_filename(),
   * gtk_file_chooser_get_preview_uri().
   */
Matthias Clasen's avatar
Matthias Clasen committed
151
  g_signal_new (I_("update-preview"),
152 153 154 155 156 157
		iface_type,
		G_SIGNAL_RUN_LAST,
		G_STRUCT_OFFSET (GtkFileChooserIface, update_preview),
		NULL, NULL,
		g_cclosure_marshal_VOID__VOID,
		G_TYPE_NONE, 0);
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174

  /**
   * GtkFileChooser::file-activated
   * @chooser: the object which received the signal.
   *
   * This signal is emitted when the user "activates" a file in the file
   * chooser.  This can happen by double-clicking on a file in the file list, or
   * by pressing <keycap>Enter</keycap>.
   *
   * Normally you do not need to connect to this signal.  It is used internally
   * by #GtkFileChooserDialog to know when to activate the default button in the
   * dialog.
   *
   * See also: gtk_file_chooser_get_filename(),
   * gtk_file_chooser_get_filenames(), gtk_file_chooser_get_uri(),
   * gtk_file_chooser_get_uris().
   */
Matthias Clasen's avatar
Matthias Clasen committed
175
  g_signal_new (I_("file-activated"),
176 177 178 179 180 181
		iface_type,
		G_SIGNAL_RUN_LAST,
		G_STRUCT_OFFSET (GtkFileChooserIface, file_activated),
		NULL, NULL,
		g_cclosure_marshal_VOID__VOID,
		G_TYPE_NONE, 0);
182

183
  /* Documented in the docbook files */
Matthias Clasen's avatar
Matthias Clasen committed
184
  g_signal_new (I_("confirm-overwrite"),
185 186 187 188 189 190
		iface_type,
		G_SIGNAL_RUN_LAST,
		G_STRUCT_OFFSET (GtkFileChooserIface, confirm_overwrite),
		confirm_overwrite_accumulator, NULL,
		_gtk_marshal_ENUM__VOID,
		GTK_TYPE_FILE_CHOOSER_CONFIRMATION, 0);
191 192 193
  
  g_object_interface_install_property (g_iface,
				       g_param_spec_enum ("action",
194 195
							  P_("Action"),
							  P_("The type of operation that the file selector is performing"),
196 197
							  GTK_TYPE_FILE_CHOOSER_ACTION,
							  GTK_FILE_CHOOSER_ACTION_OPEN,
198
							  GTK_PARAM_READWRITE));
199
  g_object_interface_install_property (g_iface,
200 201 202 203
				       g_param_spec_string ("file-system-backend",
							    P_("File System Backend"),
							    P_("Name of file system backend to use"),
							    NULL, 
204
							    GTK_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
205 206
  g_object_interface_install_property (g_iface,
				       g_param_spec_object ("filter",
207 208
							    P_("Filter"),
							    P_("The current filter for selecting which files are displayed"),
209
							    GTK_TYPE_FILE_FILTER,
210
							    GTK_PARAM_READWRITE));
211 212
  g_object_interface_install_property (g_iface,
				       g_param_spec_boolean ("local-only",
213 214
							     P_("Local Only"),
							     P_("Whether the selected file(s) should be limited to local file: URLs"),
215
							     TRUE,
216
							     GTK_PARAM_READWRITE));
217 218
  g_object_interface_install_property (g_iface,
				       g_param_spec_object ("preview-widget",
219 220
							    P_("Preview widget"),
							    P_("Application supplied widget for custom previews."),
221
							    GTK_TYPE_WIDGET,
222
							    GTK_PARAM_READWRITE));
223 224
  g_object_interface_install_property (g_iface,
				       g_param_spec_boolean ("preview-widget-active",
225 226
							     P_("Preview Widget Active"),
							     P_("Whether the application supplied widget for custom previews should be shown."),
227
							     TRUE,
228
							     GTK_PARAM_READWRITE));
229 230 231 232 233
  g_object_interface_install_property (g_iface,
				       g_param_spec_boolean ("use-preview-label",
							     P_("Use Preview Label"),
							     P_("Whether to display a stock label with the name of the previewed file."),
							     TRUE,
234
							     GTK_PARAM_READWRITE));
235 236
  g_object_interface_install_property (g_iface,
				       g_param_spec_object ("extra-widget",
237 238
							    P_("Extra widget"),
							    P_("Application supplied widget for extra options."),
239
							    GTK_TYPE_WIDGET,
240
							    GTK_PARAM_READWRITE));
241 242
  g_object_interface_install_property (g_iface,
				       g_param_spec_boolean ("select-multiple",
243 244
							     P_("Select Multiple"),
							     P_("Whether to allow multiple files to be selected"),
245
							     FALSE,
246
							     GTK_PARAM_READWRITE));
247 248 249
  
  g_object_interface_install_property (g_iface,
				       g_param_spec_boolean ("show-hidden",
250 251
							     P_("Show Hidden"),
							     P_("Whether the hidden files and folders should be displayed"),
252
							     FALSE,
253
							     GTK_PARAM_READWRITE));
254

255 256 257 258 259 260 261 262 263
  /**
   * GtkFileChooser:do-overwrite-confirmation:
   * 
   * Whether a file chooser in %GTK_FILE_CHOOSER_ACTION_SAVE mode
   * will present an overwrite confirmation dialog if the user
   * selects a file name that already exists.
   *
   * Since: 2.8
   */
264 265 266
  g_object_interface_install_property (g_iface,
				       g_param_spec_boolean ("do-overwrite-confirmation",
							     P_("Do overwrite confirmation"),
267
							     P_("Whether a file chooser in save mode "
268
								"will present an overwrite confirmation dialog "
269
								"if necessary."),
270 271
							     FALSE,
							     GTK_PARAM_READWRITE));
272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287

  /**
   * GtkFileChooser:create-folders:
   * 
   * Whether a file chooser not in %GTK_FILE_CHOOSER_ACTION_OPEN mode
   * will offer the user to create new folders.
   *
   * Since: 2.18
   */
  g_object_interface_install_property (g_iface,
				       g_param_spec_boolean ("create-folders",
							     P_("Allow folders creation"),
							     P_("Whether a file chooser not in open mode "
								"will offer the user to create new folders."),
							     TRUE,
							     GTK_PARAM_READWRITE));
Owen Taylor's avatar
Owen Taylor committed
288 289
}

290 291 292 293 294 295
/**
 * gtk_file_chooser_error_quark:
 *
 * Registers an error quark for #GtkFileChooser if necessary.
 * 
 * Return value: The error quark used for #GtkFileChooser errors.
296 297
 *
 * Since: 2.4
298 299 300 301
 **/
GQuark
gtk_file_chooser_error_quark (void)
{
302
  return g_quark_from_static_string ("gtk-file-chooser-error-quark");
303 304
}

305 306 307 308 309
/**
 * gtk_file_chooser_set_action:
 * @chooser: a #GtkFileChooser
 * @action: the action that the file selector is performing
 * 
310
 * Sets the type of operation that the chooser is performing; the
311 312 313 314
 * user interface is adapted to suit the selected action. For example,
 * an option to create a new folder might be shown if the action is
 * %GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is
 * %GTK_FILE_CHOOSER_ACTION_OPEN.
315 316
 *
 * Since: 2.4
317
 **/
Owen Taylor's avatar
Owen Taylor committed
318 319 320 321 322 323 324 325 326
void
gtk_file_chooser_set_action (GtkFileChooser       *chooser,
			     GtkFileChooserAction  action)
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));

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

327 328 329 330 331 332 333 334
/**
 * gtk_file_chooser_get_action:
 * @chooser: a #GtkFileChooser
 * 
 * Gets the type of operation that the file chooser is performing; see
 * gtk_file_chooser_set_action().
 * 
 * Return value: the action that the file selector is performing
335 336
 *
 * Since: 2.4
337
 **/
Owen Taylor's avatar
Owen Taylor committed
338 339 340 341 342 343 344 345 346 347 348 349
GtkFileChooserAction
gtk_file_chooser_get_action (GtkFileChooser *chooser)
{
  GtkFileChooserAction action;
  
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);

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

  return action;
}

350 351 352 353 354 355 356 357 358 359 360 361 362 363
/**
 * gtk_file_chooser_set_local_only:
 * @chooser: a #GtkFileChooser
 * @local_only: %TRUE if only local files can be selected
 * 
 * Sets whether only local files can be selected in the
 * file selector. If @local_only is %TRUE (the default),
 * then the selected file are files are guaranteed to be
 * accessible through the operating systems native file
 * file system and therefore the application only
 * needs to worry about the filename functions in
 * #GtkFileChooser, like gtk_file_chooser_get_filename(),
 * rather than the URI functions like
 * gtk_file_chooser_get_uri(),
364 365
 *
 * Since: 2.4
366
 **/
Owen Taylor's avatar
Owen Taylor committed
367 368 369 370 371 372
void
gtk_file_chooser_set_local_only (GtkFileChooser *chooser,
				 gboolean        local_only)
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));

373
  g_object_set (chooser, "local-only", local_only, NULL);
Owen Taylor's avatar
Owen Taylor committed
374 375
}

376 377 378 379 380 381 382 383
/**
 * gtk_file_chooser_get_local_only:
 * @chooser: a #GtkFileChoosre
 * 
 * Gets whether only local files can be selected in the
 * file selector. See gtk_file_chooser_set_local_only()
 * 
 * Return value: %TRUE if only local files can be selected.
384 385
 *
 * Since: 2.4
386
 **/
Owen Taylor's avatar
Owen Taylor committed
387 388 389 390 391 392 393
gboolean
gtk_file_chooser_get_local_only (GtkFileChooser *chooser)
{
  gboolean local_only;
  
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);

394
  g_object_get (chooser, "local-only", &local_only, NULL);
Owen Taylor's avatar
Owen Taylor committed
395 396 397 398

  return local_only;
}

399 400 401 402 403
/**
 * gtk_file_chooser_set_select_multiple:
 * @chooser: a #GtkFileChooser
 * @select_multiple: %TRUE if multiple files can be selected.
 * 
404 405
 * Sets whether multiple files can be selected in the file selector.  This is
 * only relevant if the action is set to be GTK_FILE_CHOOSER_ACTION_OPEN or
Matthias Clasen's avatar
Matthias Clasen committed
406
 * GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.  
407 408
 *
 * Since: 2.4
409
 **/
Owen Taylor's avatar
Owen Taylor committed
410 411 412 413 414 415
void
gtk_file_chooser_set_select_multiple (GtkFileChooser *chooser,
				      gboolean        select_multiple)
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));

416
  g_object_set (chooser, "select-multiple", select_multiple, NULL);
Owen Taylor's avatar
Owen Taylor committed
417 418
}

419 420 421 422 423 424 425 426
/**
 * gtk_file_chooser_get_select_multiple:
 * @chooser: a #GtkFileChooser
 * 
 * Gets whether multiple files can be selected in the file
 * selector. See gtk_file_chooser_set_select_multiple().
 * 
 * Return value: %TRUE if multiple files can be selected.
427 428
 *
 * Since: 2.4
429
 **/
Owen Taylor's avatar
Owen Taylor committed
430 431 432 433 434 435 436
gboolean
gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser)
{
  gboolean select_multiple;
  
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);

437
  g_object_get (chooser, "select-multiple", &select_multiple, NULL);
Owen Taylor's avatar
Owen Taylor committed
438 439 440 441

  return select_multiple;
}

442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484
/**
 * gtk_file_chooser_set_create_folders:
 * @chooser: a #GtkFileChooser
 * @create_folders: %TRUE if the New Folder button should be displayed
 * 
 * Sets whether file choser will offer to create new folders.
 * This is only relevant if the action is not set to be 
 * GTK_FILE_CHOOSER_ACTION_OPEN.
 *
 * Since: 2.18
 **/
void
gtk_file_chooser_set_create_folders (GtkFileChooser *chooser,
				     gboolean        create_folders)
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));

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

/**
 * gtk_file_chooser_get_create_folders:
 * @chooser: a #GtkFileChooser
 * 
 * Gets whether file choser will offer to create new folders.
 * See gtk_file_chooser_set_create_folders().
 * 
 * Return value: %TRUE if the New Folder button should be displayed.
 *
 * Since: 2.18
 **/
gboolean
gtk_file_chooser_get_create_folders (GtkFileChooser *chooser)
{
  gboolean create_folders;
  
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);

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

  return create_folders;
}

485 486 487 488 489 490 491
/**
 * gtk_file_chooser_get_filename:
 * @chooser: a #GtkFileChooser
 * 
 * Gets the filename for the currently selected file in
 * the file selector. If multiple files are selected,
 * one of the filenames will be returned at random.
492 493 494
 *
 * If the file chooser is in folder mode, this function returns the selected
 * folder.
495 496 497
 * 
 * Return value: The currently selected filename, or %NULL
 *  if no file is selected, or the selected file can't
498
 *  be represented with a local filename. Free with g_free().
499 500
 *
 * Since: 2.4
501
 **/
502
gchar *
Owen Taylor's avatar
Owen Taylor committed
503 504
gtk_file_chooser_get_filename (GtkFileChooser *chooser)
{
505
  GFile *file;
Owen Taylor's avatar
Owen Taylor committed
506
  gchar *result = NULL;
507

Owen Taylor's avatar
Owen Taylor committed
508 509
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

510 511 512
  file = gtk_file_chooser_get_file (chooser);

  if (file)
Owen Taylor's avatar
Owen Taylor committed
513
    {
514
      result = g_file_get_path (file);
515
      g_object_unref (file);
Owen Taylor's avatar
Owen Taylor committed
516 517 518 519 520
    }

  return result;
}

521 522 523 524 525
/**
 * gtk_file_chooser_set_filename:
 * @chooser: a #GtkFileChooser
 * @filename: the filename to set as current
 * 
526 527 528 529 530 531 532 533 534
 * Sets @filename as the current filename for the file chooser, by changing
 * to the file's parent folder and actually selecting the file in list.  If
 * the @chooser is in #GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name
 * will also appear in the dialog's file name entry.
 *
 * If the file name isn't in the current folder of @chooser, then the current
 * folder of @chooser will be changed to the folder containing @filename. This
 * is equivalent to a sequence of gtk_file_chooser_unselect_all() followed by
 * gtk_file_chooser_select_filename().
535 536
 *
 * Note that the file must exist, or nothing will be done except
537 538
 * for the directory change.
 *
Matthias Clasen's avatar
Matthias Clasen committed
539 540 541 542 543 544 545 546
 * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
 * you should use this function if you already have a file name to which the 
 * user may save; for example, when the user opens an existing file and then 
 * does <guimenuitem>File/Save As...</guimenuitem> on it.  If you don't have 
 * a file name already &mdash; for example, if the user just created a new 
 * file and is saving it for the first time, do not call this function.  
 * Instead, use something similar to this:
 * |[
547 548
 * if (document_is_new)
 *   {
Matthias Clasen's avatar
Matthias Clasen committed
549
 *     /&ast; the user just created a new document &ast;/
550 551 552 553 554
 *     gtk_file_chooser_set_current_folder (chooser, default_folder_for_saving);
 *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
 *   }
 * else
 *   {
Matthias Clasen's avatar
Matthias Clasen committed
555
 *     /&ast; the user edited an existing document &ast;/ 
556 557
 *     gtk_file_chooser_set_filename (chooser, existing_filename);
 *   }
Matthias Clasen's avatar
Matthias Clasen committed
558
 * ]|
559
 * 
560 561 562
 * Return value: %TRUE if both the folder could be changed and the file was
 * selected successfully, %FALSE otherwise.
 *
563
 * Since: 2.4
564
 **/
565
gboolean
Owen Taylor's avatar
Owen Taylor committed
566
gtk_file_chooser_set_filename (GtkFileChooser *chooser,
567
			       const gchar    *filename)
Owen Taylor's avatar
Owen Taylor committed
568
{
569
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
570 571

  gtk_file_chooser_unselect_all (chooser);
572
  return gtk_file_chooser_select_filename (chooser, filename);
Owen Taylor's avatar
Owen Taylor committed
573 574
}

575 576 577 578 579 580 581 582
/**
 * gtk_file_chooser_select_filename:
 * @chooser: a #GtkFileChooser
 * @filename: the filename to select
 * 
 * Selects a filename. If the file name isn't in the current
 * folder of @chooser, then the current folder of @chooser will
 * be changed to the folder containing @filename.
583
 *
584 585 586
 * Return value: %TRUE if both the folder could be changed and the file was
 * selected successfully, %FALSE otherwise.
 *
587
 * Since: 2.4
588
 **/
589
gboolean
Owen Taylor's avatar
Owen Taylor committed
590
gtk_file_chooser_select_filename (GtkFileChooser *chooser,
591
				  const gchar    *filename)
Owen Taylor's avatar
Owen Taylor committed
592
{
593
  GFile *file;
594
  gboolean result;
595
  
596 597
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
  g_return_val_if_fail (filename != NULL, FALSE);
598

599
  file = g_file_new_for_path (filename);
600
  result = gtk_file_chooser_select_file (chooser, file, NULL);
601
  g_object_unref (file);
602 603

  return result;
Owen Taylor's avatar
Owen Taylor committed
604 605
}

606 607 608 609 610 611 612 613
/**
 * gtk_file_chooser_unselect_filename:
 * @chooser: a #GtkFileChooser
 * @filename: the filename to unselect
 * 
 * Unselects a currently selected filename. If the filename
 * is not in the current directory, does not exist, or
 * is otherwise not currently selected, does nothing.
614 615
 *
 * Since: 2.4
616
 **/
Owen Taylor's avatar
Owen Taylor committed
617 618 619 620
void
gtk_file_chooser_unselect_filename (GtkFileChooser *chooser,
				    const char     *filename)
{
621 622
  GFile *file;

Owen Taylor's avatar
Owen Taylor committed
623 624
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
  g_return_if_fail (filename != NULL);
625

626
  file = g_file_new_for_path (filename);
627
  gtk_file_chooser_unselect_file (chooser, file);
628
  g_object_unref (file);
Owen Taylor's avatar
Owen Taylor committed
629 630
}

631
/* Converts a list of GFile* to a list of strings using the specified function */
632
static GSList *
633 634
files_to_strings (GSList  *files,
		  gchar * (*convert_func) (GFile *file))
635 636 637 638 639
{
  GSList *strings;

  strings = NULL;

640
  for (; files; files = files->next)
641
    {
642
      GFile *file;
643 644
      gchar *string;

645 646
      file = files->data;
      string = (* convert_func) (file);
647 648 649 650 651 652 653 654

      if (string)
	strings = g_slist_prepend (strings, string);
    }

  return g_slist_reverse (strings);
}

655 656 657 658
/**
 * gtk_file_chooser_get_filenames:
 * @chooser: a #GtkFileChooser
 * 
659 660 661 662
 * Lists all the selected files and subfolders in the current folder of
 * @chooser. The returned names are full absolute paths. If files in the current
 * folder cannot be represented as local filenames they will be ignored. (See
 * gtk_file_chooser_get_uris())
663 664
 *
 * Return value: (element-type utf8) (transfer full): a #GSList containing the filenames of all selected
665
 *   files and subfolders in the current folder. Free the returned list
666
 *   with g_slist_free(), and the filenames with g_free().
667 668
 *
 * Since: 2.4
669
 **/
Owen Taylor's avatar
Owen Taylor committed
670 671 672
GSList *
gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
{
673
  GSList *files, *result;
674
  
Owen Taylor's avatar
Owen Taylor committed
675 676
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

677
  files = gtk_file_chooser_get_files (chooser);
678 679 680 681

  result = files_to_strings (files, g_file_get_path);
  g_slist_foreach (files, (GFunc) g_object_unref, NULL);
  g_slist_free (files);
682

683
  return result;
Owen Taylor's avatar
Owen Taylor committed
684 685
}

686 687 688 689 690 691 692 693
/**
 * gtk_file_chooser_set_current_folder:
 * @chooser: a #GtkFileChooser
 * @filename: the full path of the new current folder
 * 
 * Sets the current folder for @chooser from a local filename.
 * The user will be shown the full contents of the current folder,
 * plus user interface elements for navigating to other folders.
694
 *
695 696 697
 * Return value: %TRUE if the folder could be changed successfully, %FALSE
 * otherwise.
 *
698
 * Since: 2.4
699
 **/
700
gboolean
Owen Taylor's avatar
Owen Taylor committed
701 702 703
gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
				     const gchar    *filename)
{
704
  GFile *file;
705
  gboolean result;
706
  
707 708
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
  g_return_val_if_fail (filename != NULL, FALSE);
709

710
  file = g_file_new_for_path (filename);
711
  result = gtk_file_chooser_set_current_folder_file (chooser, file, NULL);
712
  g_object_unref (file);
713 714

  return result;
Owen Taylor's avatar
Owen Taylor committed
715 716
}

717 718 719 720 721 722
/**
 * gtk_file_chooser_get_current_folder:
 * @chooser: a #GtkFileChooser
 * 
 * Gets the current folder of @chooser as a local filename.
 * See gtk_file_chooser_set_current_folder().
723 724 725 726 727 728 729 730
 *
 * Note that this is the folder that the file chooser is currently displaying
 * (e.g. "/home/username/Documents"), which is <emphasis>not the same</emphasis>
 * as the currently-selected folder if the chooser is in
 * #GTK_FILE_CHOOSER_SELECT_FOLDER mode
 * (e.g. "/home/username/Documents/selected-folder/".  To get the
 * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the
 * usual way to get the selection.
731
 * 
Federico Mena Quintero's avatar
Federico Mena Quintero committed
732 733 734 735 736
 * Return value: the full path of the current folder, or %NULL if the current
 * path cannot be represented as a local filename.  Free with g_free().  This
 * function will also return %NULL if the file chooser was unable to load the
 * last folder that was requested from it; for example, as would be for calling
 * gtk_file_chooser_set_current_folder() on a nonexistent folder.
737 738
 *
 * Since: 2.4
739
 **/
Owen Taylor's avatar
Owen Taylor committed
740 741 742
gchar *
gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
{
743
  GFile *file;
744 745
  gchar *filename;
  
Owen Taylor's avatar
Owen Taylor committed
746 747
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

748
  file = gtk_file_chooser_get_current_folder_file (chooser);
749
  if (!file)
750 751
    return NULL;

752 753
  filename = g_file_get_path (file);
  g_object_unref (file);
754 755

  return filename;
Owen Taylor's avatar
Owen Taylor committed
756 757
}

758 759 760 761 762 763 764 765 766 767
/**
 * gtk_file_chooser_set_current_name:
 * @chooser: a #GtkFileChooser
 * @name: the filename to use, as a UTF-8 string
 * 
 * Sets the current name in the file selector, as if entered
 * by the user. Note that the name passed in here is a UTF-8
 * string rather than a filename. This function is meant for
 * such uses as a suggested name in a "Save As..." dialog.
 *
768 769 770 771
 * If you want to preselect a particular existing file, you should use
 * gtk_file_chooser_set_filename() or gtk_file_chooser_set_uri() instead.
 * Please see the documentation for those functions for an example of using
 * gtk_file_chooser_set_current_name() as well.
772 773
 *
 * Since: 2.4
774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792
 **/
void
gtk_file_chooser_set_current_name  (GtkFileChooser *chooser,
				    const gchar    *name)
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
  g_return_if_fail (name != NULL);
  
  GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_name (chooser, name);
}

/**
 * gtk_file_chooser_get_uri:
 * @chooser: a #GtkFileChooser
 * 
 * Gets the URI for the currently selected file in
 * the file selector. If multiple files are selected,
 * one of the filenames will be returned at random.
 * 
793 794 795
 * If the file chooser is in folder mode, this function returns the selected
 * folder.
 * 
796 797
 * Return value: The currently selected URI, or %NULL
 *  if no file is selected. Free with g_free()
798 799
 *
 * Since: 2.4
800
 **/
Owen Taylor's avatar
Owen Taylor committed
801 802 803
gchar *
gtk_file_chooser_get_uri (GtkFileChooser *chooser)
{
804
  GFile *file;
Owen Taylor's avatar
Owen Taylor committed
805 806 807 808
  gchar *result = NULL;
  
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

809 810
  file = gtk_file_chooser_get_file (chooser);
  if (file)
Owen Taylor's avatar
Owen Taylor committed
811
    {
812 813
      result = g_file_get_uri (file);
      g_object_unref (file);
Owen Taylor's avatar
Owen Taylor committed
814 815 816 817 818
    }

  return result;
}

819 820 821 822 823
/**
 * gtk_file_chooser_set_uri:
 * @chooser: a #GtkFileChooser
 * @uri: the URI to set as current
 * 
824 825 826 827
 * Sets the file referred to by @uri as the current file for the file chooser,
 * by changing to the URI's parent folder and actually selecting the URI in the
 * list.  If the @chooser is #GTK_FILE_CHOOSER_ACTION_SAVE mode, the URI's base
 * name will also appear in the dialog's file name entry.
828
 *
829 830 831 832 833
 * If the URI isn't in the current folder of @chooser, then the current folder
 * of @chooser will be changed to the folder containing @uri. This is equivalent
 * to a sequence of gtk_file_chooser_unselect_all() followed by
 * gtk_file_chooser_select_uri().
 *
Matthias Clasen's avatar
Matthias Clasen committed
834 835 836 837 838 839 840 841 842 843
 * Note that the URI must exist, or nothing will be done except for the 
 * directory change.
 * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
 * you should use this function if you already have a file name to which the 
 * user may save; for example, when the user opens an existing file and then 
 * does <guimenuitem>File/Save As...</guimenuitem> on it.  If you don't have 
 * a file name already &mdash; for example, if the user just created a new 
 * file and is saving it for the first time, do not call this function.  
 * Instead, use something similar to this:
 * |[
844 845
 * if (document_is_new)
 *   {
Matthias Clasen's avatar
Matthias Clasen committed
846
 *     /&ast; the user just created a new document &ast;/
847 848 849 850 851
 *     gtk_file_chooser_set_current_folder_uri (chooser, default_folder_for_saving);
 *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
 *   }
 * else
 *   {
Matthias Clasen's avatar
Matthias Clasen committed
852
 *     /&ast; the user edited an existing document &ast;/ 
853 854
 *     gtk_file_chooser_set_uri (chooser, existing_uri);
 *   }
Matthias Clasen's avatar
Matthias Clasen committed
855
 * ]|
856
 *
857 858 859
 * Return value: %TRUE if both the folder could be changed and the URI was
 * selected successfully, %FALSE otherwise.
 *
860
 * Since: 2.4
861
 **/
862
gboolean
Owen Taylor's avatar
Owen Taylor committed
863 864 865
gtk_file_chooser_set_uri (GtkFileChooser *chooser,
			  const char     *uri)
{
866
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
867 868

  gtk_file_chooser_unselect_all (chooser);
869
  return gtk_file_chooser_select_uri (chooser, uri);
Owen Taylor's avatar
Owen Taylor committed
870 871
}

872 873 874 875 876 877 878 879
/**
 * gtk_file_chooser_select_uri:
 * @chooser: a #GtkFileChooser
 * @uri: the URI to select
 * 
 * Selects the file to by @uri. If the URI doesn't refer to a
 * file in the current folder of @chooser, then the current folder of
 * @chooser will be changed to the folder containing @filename.
880
 *
881 882 883
 * Return value: %TRUE if both the folder could be changed and the URI was
 * selected successfully, %FALSE otherwise.
 *
884
 * Since: 2.4
885
 **/
886
gboolean
Owen Taylor's avatar
Owen Taylor committed
887 888 889
gtk_file_chooser_select_uri (GtkFileChooser *chooser,
			     const char     *uri)
{
890
  GFile *file;
891
  gboolean result;
Owen Taylor's avatar
Owen Taylor committed
892
  
893 894
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
  g_return_val_if_fail (uri != NULL, FALSE);
895

896
  file = g_file_new_for_uri (uri);
897
  result = gtk_file_chooser_select_file (chooser, file, NULL);
898
  g_object_unref (file);
899 900

  return result;
Owen Taylor's avatar
Owen Taylor committed
901 902
}

903 904 905 906 907 908 909 910
/**
 * gtk_file_chooser_unselect_uri:
 * @chooser: a #GtkFileChooser
 * @uri: the URI to unselect
 * 
 * Unselects the file referred to by @uri. If the file
 * is not in the current directory, does not exist, or
 * is otherwise not currently selected, does nothing.
911 912
 *
 * Since: 2.4
913
 **/
Owen Taylor's avatar
Owen Taylor committed
914 915 916 917
void
gtk_file_chooser_unselect_uri (GtkFileChooser *chooser,
			       const char     *uri)
{
918 919
  GFile *file;

920 921 922
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
  g_return_if_fail (uri != NULL);

923
  file = g_file_new_for_uri (uri);
924
  gtk_file_chooser_unselect_file (chooser, file);
925
  g_object_unref (file);
Owen Taylor's avatar
Owen Taylor committed
926 927
}

928 929 930 931 932
/**
 * gtk_file_chooser_select_all:
 * @chooser: a #GtkFileChooser
 * 
 * Selects all the files in the current folder of a file chooser.
Matthias Clasen's avatar
Matthias Clasen committed
933 934
 *
 * Since: 2.4
935
 **/
Owen Taylor's avatar
Owen Taylor committed
936 937 938 939 940 941 942 943
void
gtk_file_chooser_select_all (GtkFileChooser *chooser)
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
  
  GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_all (chooser);
}

944 945 946 947 948
/**
 * gtk_file_chooser_unselect_all:
 * @chooser: a #GtkFileChooser
 * 
 * Unselects all the files in the current folder of a file chooser.
Matthias Clasen's avatar
Matthias Clasen committed
949 950
 *
 * Since: 2.4
951
 **/
Owen Taylor's avatar
Owen Taylor committed
952 953 954 955 956 957 958 959 960
void
gtk_file_chooser_unselect_all (GtkFileChooser *chooser)
{

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

961
/**
962
 * gtk_file_chooser_get_uris:
963 964
 * @chooser: a #GtkFileChooser
 * 
965
 * Lists all the selected files and subfolders in the current folder of
966
 * @chooser. The returned names are full absolute URIs.
967 968
 *
 * Return value: (element-type utf8) (transfer full): a #GSList containing the URIs of all selected
969
 *   files and subfolders in the current folder. Free the returned list
970
 *   with g_slist_free(), and the filenames with g_free().
971 972
 *
 * Since: 2.4
973
 **/
Owen Taylor's avatar
Owen Taylor committed
974 975 976
GSList *
gtk_file_chooser_get_uris (GtkFileChooser *chooser)
{
977
  GSList *files, *result;
Owen Taylor's avatar
Owen Taylor committed
978
  
979 980
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

981
  files = gtk_file_chooser_get_files (chooser);
982 983 984 985

  result = files_to_strings (files, g_file_get_uri);
  g_slist_foreach (files, (GFunc) g_object_unref, NULL);
  g_slist_free (files);
986

987
  return result;
Owen Taylor's avatar
Owen Taylor committed
988 989
}

990 991 992 993 994 995 996 997
/**
 * gtk_file_chooser_set_current_folder_uri:
 * @chooser: a #GtkFileChooser
 * @uri: the URI for the new current folder
 * 
 * Sets the current folder for @chooser from an URI.
 * The user will be shown the full contents of the current folder,
 * plus user interface elements for navigating to other folders.
998
 *
999 1000 1001
 * Return value: %TRUE if the folder could be changed successfully, %FALSE
 * otherwise.
 *
1002
 * Since: 2.4
1003
 **/
1004
gboolean
Owen Taylor's avatar
Owen Taylor committed
1005 1006 1007
gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser,
					 const gchar    *uri)
{
1008
  GFile *file;
1009
  gboolean result;
1010
  
1011 1012
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
  g_return_val_if_fail (uri != NULL, FALSE);
Owen Taylor's avatar
Owen Taylor committed
1013

1014
  file = g_file_new_for_uri (uri);
1015
  result = gtk_file_chooser_set_current_folder_file (chooser, file, NULL);
1016
  g_object_unref (file);
1017 1018

  return result;
1019
}
Owen Taylor's avatar
Owen Taylor committed
1020

1021 1022 1023 1024 1025 1026
/**
 * gtk_file_chooser_get_current_folder_uri:
 * @chooser: a #GtkFileChooser
 * 
 * Gets the current folder of @chooser as an URI.
 * See gtk_file_chooser_set_current_folder_uri().
1027 1028 1029 1030 1031 1032 1033 1034
 *
 * Note that this is the folder that the file chooser is currently displaying
 * (e.g. "file:///home/username/Documents"), which is <emphasis>not the same</emphasis>
 * as the currently-selected folder if the chooser is in
 * #GTK_FILE_CHOOSER_SELECT_FOLDER mode
 * (e.g. "file:///home/username/Documents/selected-folder/".  To get the
 * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the
 * usual way to get the selection.
1035
 * 
Federico Mena Quintero's avatar
Federico Mena Quintero committed
1036 1037 1038 1039
 * Return value: the URI for the current folder.  Free with g_free().  This
 * function will also return %NULL if the file chooser was unable to load the
 * last folder that was requested from it; for example, as would be for calling
 * gtk_file_chooser_set_current_folder_uri() on a nonexistent folder.
1040 1041
 *
 * Since: 2.4
1042
 */
Owen Taylor's avatar
Owen Taylor committed
1043 1044
gchar *
gtk_file_chooser_get_current_folder_uri (GtkFileChooser *chooser)
1045
{
1046
  GFile *file;
1047 1048 1049 1050
  gchar *uri;
  
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

1051
  file = gtk_file_chooser_get_current_folder_file (chooser);
1052
  if (!file)
1053 1054
    return NULL;

1055 1056
  uri = g_file_get_uri (file);
  g_object_unref (file);
1057 1058 1059 1060

  return uri;
}

1061
/**
1062
 * gtk_file_chooser_set_current_folder_file:
1063
 * @chooser: a #GtkFileChooser
1064
 * @file: the #GFile for the new folder
1065
 * @error: location to store error, or %NULL.
1066
 * 
1067
 * Sets the current folder for @chooser from a #GFile.
1068
 * Internal function, see gtk_file_chooser_set_current_folder_uri().
1069
 *
1070 1071 1072
 * Return value: %TRUE if the folder could be changed successfully, %FALSE
 * otherwise.
 *
1073
 * Since: 2.14
1074
 **/
1075
gboolean
1076 1077 1078
gtk_file_chooser_set_current_folder_file (GtkFileChooser  *chooser,
                                          GFile           *file,
                                          GError         **error)
1079
{
1080
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1081
  g_return_val_if_fail (G_IS_FILE (file), FALSE);
1082
  g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1083

1084
  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_folder (chooser, file, error);
1085 1086
}

1087
/**
1088
 * gtk_file_chooser_get_current_folder_file:
1089 1090
 * @chooser: a #GtkFileChooser
 * 
1091
 * Gets the current folder of @chooser as #GFile.
1092 1093
 * See gtk_file_chooser_get_current_folder_uri().
 * 
1094
 * Return value: the #GFile for the current folder.
1095
 *
1096
 * Since: 2.14
1097
 */
1098
GFile *
1099
gtk_file_chooser_get_current_folder_file (GtkFileChooser *chooser)
Owen Taylor's avatar
Owen Taylor committed
1100 1101 1102 1103 1104 1105
{
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

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

1106
/**
1107
 * gtk_file_chooser_select_file:
1108
 * @chooser: a #GtkFileChooser
1109
 * @file: the file to select
1110
 * @error: location to store error, or %NULL
1111
 * 
1112
 * Selects the file referred to by @file. An internal function. See
1113
 * _gtk_file_chooser_select_uri().
1114
 *
1115 1116 1117
 * Return value: %TRUE if both the folder could be changed and the path was
 * selected successfully, %FALSE otherwise.
 *
1118
 * Since: 2.14
1119
 **/
1120
gboolean
1121 1122 1123
gtk_file_chooser_select_file (GtkFileChooser  *chooser,
                              GFile           *file,
                              GError         **error)
1124
{
1125
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1126
  g_return_val_if_fail (G_IS_FILE (file), FALSE);
1127
  g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1128

1129
  return GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_file (chooser, file, error);
1130 1131
}

1132
/**
1133
 * gtk_file_chooser_unselect_file:
1134
 * @chooser: a #GtkFileChooser
1135
 * @file: a #GFile
1136
 * 
1137 1138
 * Unselects the file referred to by @file. If the file is not in the current
 * directory, does not exist, or is otherwise not currently selected, does nothing.
1139
 *
1140
 * Since: 2.14
1141
 **/
1142
void
1143 1144
gtk_file_chooser_unselect_file (GtkFileChooser *chooser,
                                GFile          *file)
1145 1146
{
  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1147
  g_return_if_fail (G_IS_FILE (file));
1148

1149
  GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_file (chooser, file);
1150 1151
}

1152
/**
1153
 * gtk_file_chooser_get_files:
1154 1155
 * @chooser: a #GtkFileChooser
 * 
1156
 * Lists all the selected files and subfolders in the current folder of @chooser
1157
 * as #GFile. An internal function, see gtk_file_chooser_get_uris().
1158 1159
 *
 * Return value: (element-type utf8) (transfer full): a #GSList containing a #GFile for each selected
1160
 *   file and subfolder in the current folder.  Free the returned list
1161
 *   with g_slist_free(), and the files with g_object_unref().
1162
 *
1163
 * Since: 2.14
1164
 **/
1165
GSList *
1166
gtk_file_chooser_get_files (GtkFileChooser *chooser)
1167 1168 1169
{
  g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);

1170