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 @Returns:
 332
 333
 334 <!-- ##### FUNCTION gtk_file_chooser_select_filename ##### -->
 335 <para>
 336
 337 </para>
 338
 339 @chooser:
 340 @filename:
 341 @Returns:
 342
 343
 344 <!-- ##### FUNCTION gtk_file_chooser_unselect_filename ##### -->
 345 <para>
 346
 347 </para>
 348
 349 @chooser:
 350 @filename:
 351
 352
 353 <!-- ##### FUNCTION gtk_file_chooser_select_all ##### -->
 354 <para>
 355
 356 </para>
 357
 358 @chooser:
 359
 360
 361 <!-- ##### FUNCTION gtk_file_chooser_unselect_all ##### -->
 362 <para>
 363
 364 </para>
 365
 366 @chooser:
 367
 368
 369 <!-- ##### FUNCTION gtk_file_chooser_get_filenames ##### -->
 370 <para>
 371
 372 </para>
 373
 374 @chooser:
 375 @Returns:
 376
 377
 378 <!-- ##### FUNCTION gtk_file_chooser_set_current_folder ##### -->
 379 <para>
 380
 381 </para>
 382
 383 @chooser:
 384 @filename:
 385 @Returns:
 386
 387
 388 <!-- ##### FUNCTION gtk_file_chooser_get_current_folder ##### -->
 389 <para>
 390
 391 </para>
 392
 393 @chooser:
 394 @Returns:
 395
 396
 397 <!-- ##### FUNCTION gtk_file_chooser_get_uri ##### -->
 398 <para>
 399
 400 </para>
 401
 402 @chooser:
 403 @Returns:
 404
 405
 406 <!-- ##### FUNCTION gtk_file_chooser_set_uri ##### -->
 407 <para>
 408
 409 </para>
 410
 411 @chooser:
 412 @uri:
 413 @Returns:
 414
 415
 416 <!-- ##### FUNCTION gtk_file_chooser_select_uri ##### -->
 417 <para>
 418
 419 </para>
 420
 421 @chooser:
 422 @uri:
 423 @Returns:
 424
 425
 426 <!-- ##### FUNCTION gtk_file_chooser_unselect_uri ##### -->
 427 <para>
 428
 429 </para>
 430
 431 @chooser:
 432 @uri:
 433
 434
 435 <!-- ##### FUNCTION gtk_file_chooser_get_uris ##### -->
 436 <para>
 437
 438 </para>
 439
 440 @chooser:
 441 @Returns:
 442
 443
 444 <!-- ##### FUNCTION gtk_file_chooser_set_current_folder_uri ##### -->
 445 <para>
 446
 447 </para>
 448
 449 @chooser:
 450 @uri:
 451 @Returns:
 452
 453
 454 <!-- ##### FUNCTION gtk_file_chooser_get_current_folder_uri ##### -->
 455 <para>
 456
 457 </para>
 458
 459 @chooser:
 460 @Returns:
 461
 462
 463 <!-- ##### FUNCTION gtk_file_chooser_set_preview_widget ##### -->
 464 <para>
 465
 466 </para>
 467
 468 @chooser:
 469 @preview_widget:
 470
 471
 472 <!-- ##### FUNCTION gtk_file_chooser_get_preview_widget ##### -->
 473 <para>
 474
 475 </para>
 476
 477 @chooser:
 478 @Returns:
 479
 480
 481 <!-- ##### FUNCTION gtk_file_chooser_set_preview_widget_active ##### -->
 482 <para>
 483
 484 </para>
 485
 486 @chooser:
 487 @active:
 488
 489
 490 <!-- ##### FUNCTION gtk_file_chooser_get_preview_widget_active ##### -->
 491 <para>
 492
 493 </para>
 494
 495 @chooser:
 496 @Returns:
 497
 498
 499 <!-- ##### FUNCTION gtk_file_chooser_set_use_preview_label ##### -->
 500 <para>
 501
 502 </para>
 503
 504 @chooser:
 505 @use_label:
 506
 507
 508 <!-- ##### FUNCTION gtk_file_chooser_get_use_preview_label ##### -->
 509 <para>
 510
 511 </para>
 512
 513 @chooser:
 514 @Returns:
 515
 516
 517 <!-- ##### FUNCTION gtk_file_chooser_get_preview_filename ##### -->
 518 <para>
 519
 520 </para>
 521
 522 @chooser:
 523 @Returns:
 524 <!-- # Unused Parameters # -->
 525 @file_chooser:
 526
 527
 528 <!-- ##### FUNCTION gtk_file_chooser_get_preview_uri ##### -->
 529 <para>
 530
 531 </para>
 532
 533 @chooser:
 534 @Returns:
 535 <!-- # Unused Parameters # -->
 536 @file_chooser:
 537
 538
 539 <!-- ##### FUNCTION gtk_file_chooser_set_extra_widget ##### -->
 540 <para>
 541
 542 </para>
 543
 544 @chooser:
 545 @extra_widget:
 546
 547
 548 <!-- ##### FUNCTION gtk_file_chooser_get_extra_widget ##### -->
 549 <para>
 550
 551 </para>
 552
 553 @chooser:
 554 @Returns:
 555
 556
 557 <!-- ##### FUNCTION gtk_file_chooser_add_filter ##### -->
 558 <para>
 559
 560 </para>
 561
 562 @chooser:
 563 @filter:
 564
 565
 566 <!-- ##### FUNCTION gtk_file_chooser_remove_filter ##### -->
 567 <para>
 568
 569 </para>
 570
 571 @chooser:
 572 @filter:
 573
 574
 575 <!-- ##### FUNCTION gtk_file_chooser_list_filters ##### -->
 576 <para>
 577
 578 </para>
 579
 580 @chooser:
 581 @Returns:
 582
 583
 584 <!-- ##### FUNCTION gtk_file_chooser_set_filter ##### -->
 585 <para>
 586
 587 </para>
 588
 589 @chooser:
 590 @filter:
 591
 592
 593 <!-- ##### FUNCTION gtk_file_chooser_get_filter ##### -->
 594 <para>
 595
 596 </para>
 597
 598 @chooser:
 599 @Returns:
 600
 601
 602 <!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder ##### -->
 603 <para>
 604
 605 </para>
 606
 607 @chooser:
 608 @folder:
 609 @error:
 610 @Returns:
 611
 612
 613 <!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder ##### -->
 614 <para>
 615
 616 </para>
 617
 618 @chooser:
 619 @folder:
 620 @error:
 621 @Returns:
 622
 623
 624 <!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folders ##### -->
 625 <para>
 626
 627 </para>
 628
 629 @chooser:
 630 @Returns:
 631
 632
 633 <!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder_uri ##### -->
 634 <para>
 635
 636 </para>
 637
 638 @chooser:
 639 @uri:
 640 @error:
 641 @Returns:
 642 <!-- # Unused Parameters # -->
 643 @folder:
 644
 645
 646 <!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder_uri ##### -->
 647 <para>
 648
 649 </para>
 650
 651 @chooser:
 652 @uri:
 653 @error:
 654 @Returns:
 655 <!-- # Unused Parameters # -->
 656 @folder:
 657
 658
 659 <!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folder_uris ##### -->
 660 <para>
 661
 662 </para>
 663
 664 @chooser:
 665 @Returns:
 666
 667
 668
 669 <!--
 670 Local variables:
 671 mode: sgml
 672 sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
 673 End:
 674 -->
 675
 676