Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkfilechooser.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkFileChooser
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8     <para>
   9       #GtkFileChooser is an interface that can be implemented by file
  10       selection widgets.  In GTK+, the main objects that implement
  11       this interface are #GtkFileChooserWidget and
  12       #GtkFileChooserDialog.  You do not need to write an object that
  13       implements the #GtkFileChooser interface unless you are trying
  14       to adapt an existing file selector to expose a standard
  15       programming interface.
  16     </para>
  17
  18     <refsect2 id="gtkfilechooser-preview">
  19       <title>Adding a Preview Widget</title>
  20
  21       <para>
  22         You can add a custom preview widget to a file chooser and then
  23         get notification about when the preview needs to be updated.
  24         To install a preview widget, use
  25         gtk_file_chooser_set_preview_widget().  Then, connect to the
  26         #GtkFileChooser::update-preview signal to get notified when
  27         you need to update the contents of the preview.
  28       </para>
  29
  30       <para>
  31         Your callback should use
  32         gtk_file_chooser_get_preview_filename() to see what needs
  33         previewing.  Once you have generated the preview for the
  34         corresponding file, you must call
  35         gtk_file_chooser_set_preview_widget_active() with a boolean
  36         flag that indicates whether your callback could successfully
  37         generate a preview.
  38       </para>
  39
  40       <example id="example-gtkfilechooser-preview">
  41         <title>Sample Usage</title>
  42
  43         <programlisting>
  44 {
  45   GtkImage *preview;
  46
  47   ...
  48
  49   preview = gtk_image_new (<!-- -->);
  50
  51   gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
  52   g_signal_connect (my_file_chooser, "update-preview",
  53                     G_CALLBACK (update_preview_cb), preview);
  54 }
  55
  56 static void
  57 update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
  58 {
  59   GtkWidget *preview;
  60   char *filename;
  61   GdkPixbuf *pixbuf;
  62   gboolean have_preview;
  63
  64   preview = GTK_WIDGET (data);
  65   filename = gtk_file_chooser_get_preview_filename (file_chooser);
  66
  67   pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
  68   have_preview = (pixbuf != NULL);
  69   g_free (filename);
  70
  71   gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
  72   if (pixbuf)
  73     gdk_pixbuf_unref (pixbuf);
  74
  75   gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
  76 }
  77         </programlisting>
  78       </example>
  79     </refsect2>
  80
  81     <refsect2 id="gtkfilechooser-extra">
  82       <title>Adding Extra Widgets</title>
  83
  84       <para>
  85         You can add extra widgets to a file chooser to provide options
  86         that are not present in the default design.  For example, you
  87         can add a toggle button to give the user the option to open a
  88         file in read-only mode.  You can use
  89         gtk_file_chooser_set_extra_widget() to insert additional
  90         widgets in a file chooser.
  91       </para>
  92
  93       <example id="example-gtkfilechooser-extra">
  94         <title>Sample Usage</title>
  95
  96         <programlisting>
  97 {
  98   GtkWidget *toggle;
  99
 100   ...
 101
 102   toggle = gtk_check_button_new_with_label ("Open file read-only");
 103   gtk_widget_show (toggle);
 104   gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
 105 }
 106         </programlisting>
 107       </example>
 108
 109       <note>
 110         <para>
 111           If you want to set more than one extra widget in the file
 112           chooser, you can a container such as a GtkVBox or a GtkTable
 113           and include your widgets in it.  Then, set the container as
 114           the whole extra widget.
 115         </para>
 116       </note>
 117     </refsect2>
 118
 119 <!-- ##### SECTION See_Also ##### -->
 120     <para>
 121       #GtkFileChooserDialog, #GtkFileChooserWidget
 122     </para>
 123
 124 <!-- ##### STRUCT GtkFileChooser ##### -->
 125 <para>
 126
 127 </para>
 128
 129
 130 <!-- ##### SIGNAL GtkFileChooser::current-folder-changed ##### -->
 131 <para>
 132
 133 </para>
 134
 135 @filechooser: the object which received the signal.
 136
 137 <!-- ##### SIGNAL GtkFileChooser::file-activated ##### -->
 138 <para>
 139
 140 </para>
 141
 142 @filechooser: the object which received the signal.
 143
 144 <!-- ##### SIGNAL GtkFileChooser::selection-changed ##### -->
 145 <para>
 146
 147 </para>
 148
 149 @filechooser: the object which received the signal.
 150
 151 <!-- ##### SIGNAL GtkFileChooser::update-preview ##### -->
 152 <para>
 153
 154 </para>
 155
 156 @filechooser: the object which received the signal.
 157
 158 <!-- ##### ARG GtkFileChooser:action ##### -->
 159 <para>
 160
 161 </para>
 162
 163 <!-- ##### ARG GtkFileChooser:extra-widget ##### -->
 164 <para>
 165
 166 </para>
 167
 168 <!-- ##### ARG GtkFileChooser:file-system-backend ##### -->
 169 <para>
 170
 171 </para>
 172
 173 <!-- ##### ARG GtkFileChooser:filter ##### -->
 174 <para>
 175
 176 </para>
 177
 178 <!-- ##### ARG GtkFileChooser:local-only ##### -->
 179 <para>
 180
 181 </para>
 182
 183 <!-- ##### ARG GtkFileChooser:preview-widget ##### -->
 184 <para>
 185
 186 </para>
 187
 188 <!-- ##### ARG GtkFileChooser:preview-widget-active ##### -->
 189 <para>
 190
 191 </para>
 192
 193 <!-- ##### ARG GtkFileChooser:select-multiple ##### -->
 194 <para>
 195
 196 </para>
 197
 198 <!-- ##### ARG GtkFileChooser:show-hidden ##### -->
 199 <para>
 200
 201 </para>
 202
 203 <!-- ##### ARG GtkFileChooser:use-preview-label ##### -->
 204 <para>
 205
 206 </para>
 207
 208 <!-- ##### ENUM GtkFileChooserAction ##### -->
 209     <para>
 210       Describes whether a #GtkFileChooser is being used to open
 211       existing files or to save to a possibly new file.
 212     </para>
 213
 214 @GTK_FILE_CHOOSER_ACTION_OPEN: Indicates open mode.  The file chooser
 215     will only let the user pick an existing file.
 216 @GTK_FILE_CHOOSER_ACTION_SAVE: Indicates save mode.  The file chooser
 217     will let the user pick an existing file, or type in a new
 218     filename.
 219 @GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER: Indicates an Open mode for
 220     selecting folders.  The file chooser will let the user pick an
 221     existing folder.
 222 @GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER: Indicates a mode for creating a
 223     new folder.  The file chooser will let the user name an existing or
 224     new folder.
 225
 226 <!-- ##### MACRO GTK_FILE_CHOOSER_ERROR ##### -->
 227     <para>
 228       Used to get the #GError quark for #GtkFileChooser errors.
 229     </para>
 230
 231
 232
 233 <!-- ##### ENUM GtkFileChooserError ##### -->
 234     <para>
 235       These identify the various errors that can occur while calling
 236       #GtkFileChooser functions.
 237     </para>
 238
 239 @GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist.
 240 @GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename.
 241
 242 <!-- ##### FUNCTION gtk_file_chooser_error_quark ##### -->
 243 <para>
 244
 245 </para>
 246
 247 @Returns:
 248
 249
 250 <!-- ##### FUNCTION gtk_file_chooser_set_action ##### -->
 251 <para>
 252
 253 </para>
 254
 255 @chooser:
 256 @action:
 257
 258
 259 <!-- ##### FUNCTION gtk_file_chooser_get_action ##### -->
 260 <para>
 261
 262 </para>
 263
 264 @chooser:
 265 @Returns:
 266
 267
 268 <!-- ##### FUNCTION gtk_file_chooser_set_local_only ##### -->
 269 <para>
 270
 271 </para>
 272
 273 @chooser:
 274 @local_only:
 275 <!-- # Unused Parameters # -->
 276 @files_only:
 277
 278
 279 <!-- ##### FUNCTION gtk_file_chooser_get_local_only ##### -->
 280 <para>
 281
 282 </para>
 283
 284 @chooser:
 285 @Returns:
 286
 287
 288 <!-- ##### FUNCTION gtk_file_chooser_set_select_multiple ##### -->
 289 <para>
 290
 291 </para>
 292
 293 @chooser:
 294 @select_multiple:
 295
 296
 297 <!-- ##### FUNCTION gtk_file_chooser_get_select_multiple ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @chooser:
 303 @Returns:
 304
 305
 306 <!-- ##### FUNCTION gtk_file_chooser_set_current_name ##### -->
 307 <para>
 308
 309 </para>
 310
 311 @chooser:
 312 @name:
 313
 314
 315 <!-- ##### FUNCTION gtk_file_chooser_get_filename ##### -->
 316 <para>
 317
 318 </para>
 319
 320 @chooser:
 321 @Returns:
 322
 323
 324 <!-- ##### FUNCTION gtk_file_chooser_set_filename ##### -->
 325 <para>
 326
 327 </para>
 328
 329 @chooser:
 330 @filename:
 331
 332
 333 <!-- ##### FUNCTION gtk_file_chooser_select_filename ##### -->
 334 <para>
 335
 336 </para>
 337
 338 @chooser:
 339 @filename:
 340
 341
 342 <!-- ##### FUNCTION gtk_file_chooser_unselect_filename ##### -->
 343 <para>
 344
 345 </para>
 346
 347 @chooser:
 348 @filename:
 349
 350
 351 <!-- ##### FUNCTION gtk_file_chooser_select_all ##### -->
 352 <para>
 353
 354 </para>
 355
 356 @chooser:
 357
 358
 359 <!-- ##### FUNCTION gtk_file_chooser_unselect_all ##### -->
 360 <para>
 361
 362 </para>
 363
 364 @chooser:
 365
 366
 367 <!-- ##### FUNCTION gtk_file_chooser_get_filenames ##### -->
 368 <para>
 369
 370 </para>
 371
 372 @chooser:
 373 @Returns:
 374
 375
 376 <!-- ##### FUNCTION gtk_file_chooser_set_current_folder ##### -->
 377 <para>
 378
 379 </para>
 380
 381 @chooser:
 382 @filename:
 383
 384
 385 <!-- ##### FUNCTION gtk_file_chooser_get_current_folder ##### -->
 386 <para>
 387
 388 </para>
 389
 390 @chooser:
 391 @Returns:
 392
 393
 394 <!-- ##### FUNCTION gtk_file_chooser_get_uri ##### -->
 395 <para>
 396
 397 </para>
 398
 399 @chooser:
 400 @Returns:
 401
 402
 403 <!-- ##### FUNCTION gtk_file_chooser_set_uri ##### -->
 404 <para>
 405
 406 </para>
 407
 408 @chooser:
 409 @uri:
 410
 411
 412 <!-- ##### FUNCTION gtk_file_chooser_select_uri ##### -->
 413 <para>
 414
 415 </para>
 416
 417 @chooser:
 418 @uri:
 419
 420
 421 <!-- ##### FUNCTION gtk_file_chooser_unselect_uri ##### -->
 422 <para>
 423
 424 </para>
 425
 426 @chooser:
 427 @uri:
 428
 429
 430 <!-- ##### FUNCTION gtk_file_chooser_get_uris ##### -->
 431 <para>
 432
 433 </para>
 434
 435 @chooser:
 436 @Returns:
 437
 438
 439 <!-- ##### FUNCTION gtk_file_chooser_set_current_folder_uri ##### -->
 440 <para>
 441
 442 </para>
 443
 444 @chooser:
 445 @uri:
 446
 447
 448 <!-- ##### FUNCTION gtk_file_chooser_get_current_folder_uri ##### -->
 449 <para>
 450
 451 </para>
 452
 453 @chooser:
 454 @Returns:
 455
 456
 457 <!-- ##### FUNCTION gtk_file_chooser_set_preview_widget ##### -->
 458 <para>
 459
 460 </para>
 461
 462 @chooser:
 463 @preview_widget:
 464
 465
 466 <!-- ##### FUNCTION gtk_file_chooser_get_preview_widget ##### -->
 467 <para>
 468
 469 </para>
 470
 471 @chooser:
 472 @Returns:
 473
 474
 475 <!-- ##### FUNCTION gtk_file_chooser_set_preview_widget_active ##### -->
 476 <para>
 477
 478 </para>
 479
 480 @chooser:
 481 @active:
 482
 483
 484 <!-- ##### FUNCTION gtk_file_chooser_get_preview_widget_active ##### -->
 485 <para>
 486
 487 </para>
 488
 489 @chooser:
 490 @Returns:
 491
 492
 493 <!-- ##### FUNCTION gtk_file_chooser_get_preview_filename ##### -->
 494 <para>
 495
 496 </para>
 497
 498 @chooser:
 499 @Returns:
 500 <!-- # Unused Parameters # -->
 501 @file_chooser:
 502
 503
 504 <!-- ##### FUNCTION gtk_file_chooser_get_preview_uri ##### -->
 505 <para>
 506
 507 </para>
 508
 509 @chooser:
 510 @Returns:
 511 <!-- # Unused Parameters # -->
 512 @file_chooser:
 513
 514
 515 <!-- ##### FUNCTION gtk_file_chooser_set_extra_widget ##### -->
 516 <para>
 517
 518 </para>
 519
 520 @chooser:
 521 @extra_widget:
 522
 523
 524 <!-- ##### FUNCTION gtk_file_chooser_get_extra_widget ##### -->
 525 <para>
 526
 527 </para>
 528
 529 @chooser:
 530 @Returns:
 531
 532
 533 <!-- ##### FUNCTION gtk_file_chooser_add_filter ##### -->
 534 <para>
 535
 536 </para>
 537
 538 @chooser:
 539 @filter:
 540
 541
 542 <!-- ##### FUNCTION gtk_file_chooser_remove_filter ##### -->
 543 <para>
 544
 545 </para>
 546
 547 @chooser:
 548 @filter:
 549
 550
 551 <!-- ##### FUNCTION gtk_file_chooser_list_filters ##### -->
 552 <para>
 553
 554 </para>
 555
 556 @chooser:
 557 @Returns:
 558
 559
 560 <!-- ##### FUNCTION gtk_file_chooser_set_filter ##### -->
 561 <para>
 562
 563 </para>
 564
 565 @chooser:
 566 @filter:
 567
 568
 569 <!-- ##### FUNCTION gtk_file_chooser_get_filter ##### -->
 570 <para>
 571
 572 </para>
 573
 574 @chooser:
 575 @Returns:
 576
 577
 578 <!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder ##### -->
 579 <para>
 580
 581 </para>
 582
 583 @chooser:
 584 @folder:
 585 @error:
 586 @Returns:
 587
 588
 589 <!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder ##### -->
 590 <para>
 591
 592 </para>
 593
 594 @chooser:
 595 @folder:
 596 @error:
 597 @Returns:
 598
 599
 600 <!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folders ##### -->
 601 <para>
 602
 603 </para>
 604
 605 @chooser:
 606 @Returns:
 607
 608
 609 <!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder_uri ##### -->
 610 <para>
 611
 612 </para>
 613
 614 @chooser:
 615 @uri:
 616 @error:
 617 @Returns:
 618 <!-- # Unused Parameters # -->
 619 @folder:
 620
 621
 622 <!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder_uri ##### -->
 623 <para>
 624
 625 </para>
 626
 627 @chooser:
 628 @uri:
 629 @error:
 630 @Returns:
 631 <!-- # Unused Parameters # -->
 632 @folder:
 633
 634
 635 <!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folder_uris ##### -->
 636 <para>
 637
 638 </para>
 639
 640 @chooser:
 641 @Returns:
 642
 643
 644
 645 <!--
 646 Local variables:
 647 mode: sgml
 648 sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
 649 End:
 650 -->
 651
 652