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 ##### -->
 169 <para>
 170
 171 </para>
 172
 173 <!-- ##### ARG GtkFileChooser:filter ##### -->
 174 <para>
 175
 176 </para>
 177
 178 <!-- ##### ARG GtkFileChooser:folder-mode ##### -->
 179 <para>
 180
 181 </para>
 182
 183 <!-- ##### ARG GtkFileChooser:local-only ##### -->
 184 <para>
 185
 186 </para>
 187
 188 <!-- ##### ARG GtkFileChooser:preview-widget ##### -->
 189 <para>
 190
 191 </para>
 192
 193 <!-- ##### ARG GtkFileChooser:preview-widget-active ##### -->
 194 <para>
 195
 196 </para>
 197
 198 <!-- ##### ARG GtkFileChooser:select-multiple ##### -->
 199 <para>
 200
 201 </para>
 202
 203 <!-- ##### ARG GtkFileChooser:show-hidden ##### -->
 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
 220 <!-- ##### MACRO GTK_FILE_CHOOSER_ERROR ##### -->
 221     <para>
 222       Used to get the #GError quark for #GtkFileChooser errors.
 223     </para>
 224
 225
 226
 227 <!-- ##### ENUM GtkFileChooserError ##### -->
 228     <para>
 229       These identify the various errors that can occur while calling
 230       #GtkFileChooser functions.
 231     </para>
 232
 233 @GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist.
 234 @GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename.
 235
 236 <!-- ##### FUNCTION gtk_file_chooser_error_quark ##### -->
 237 <para>
 238
 239 </para>
 240
 241 @Returns:
 242
 243
 244 <!-- ##### FUNCTION gtk_file_chooser_set_action ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @chooser:
 250 @action:
 251
 252
 253 <!-- ##### FUNCTION gtk_file_chooser_get_action ##### -->
 254 <para>
 255
 256 </para>
 257
 258 @chooser:
 259 @Returns:
 260
 261
 262 <!-- ##### FUNCTION gtk_file_chooser_set_folder_mode ##### -->
 263 <para>
 264
 265 </para>
 266
 267 @chooser:
 268 @folder_mode:
 269
 270
 271 <!-- ##### FUNCTION gtk_file_chooser_get_folder_mode ##### -->
 272 <para>
 273
 274 </para>
 275
 276 @chooser:
 277 @Returns:
 278
 279
 280 <!-- ##### FUNCTION gtk_file_chooser_set_local_only ##### -->
 281 <para>
 282
 283 </para>
 284
 285 @chooser:
 286 @local_only:
 287 <!-- # Unused Parameters # -->
 288 @files_only:
 289
 290
 291 <!-- ##### FUNCTION gtk_file_chooser_get_local_only ##### -->
 292 <para>
 293
 294 </para>
 295
 296 @chooser:
 297 @Returns:
 298
 299
 300 <!-- ##### FUNCTION gtk_file_chooser_set_select_multiple ##### -->
 301 <para>
 302
 303 </para>
 304
 305 @chooser:
 306 @select_multiple:
 307
 308
 309 <!-- ##### FUNCTION gtk_file_chooser_get_select_multiple ##### -->
 310 <para>
 311
 312 </para>
 313
 314 @chooser:
 315 @Returns:
 316
 317
 318 <!-- ##### FUNCTION gtk_file_chooser_set_current_name ##### -->
 319 <para>
 320
 321 </para>
 322
 323 @chooser:
 324 @name:
 325
 326
 327 <!-- ##### FUNCTION gtk_file_chooser_get_filename ##### -->
 328 <para>
 329
 330 </para>
 331
 332 @chooser:
 333 @Returns:
 334
 335
 336 <!-- ##### FUNCTION gtk_file_chooser_set_filename ##### -->
 337 <para>
 338
 339 </para>
 340
 341 @chooser:
 342 @filename:
 343
 344
 345 <!-- ##### FUNCTION gtk_file_chooser_select_filename ##### -->
 346 <para>
 347
 348 </para>
 349
 350 @chooser:
 351 @filename:
 352
 353
 354 <!-- ##### FUNCTION gtk_file_chooser_unselect_filename ##### -->
 355 <para>
 356
 357 </para>
 358
 359 @chooser:
 360 @filename:
 361
 362
 363 <!-- ##### FUNCTION gtk_file_chooser_select_all ##### -->
 364 <para>
 365
 366 </para>
 367
 368 @chooser:
 369
 370
 371 <!-- ##### FUNCTION gtk_file_chooser_unselect_all ##### -->
 372 <para>
 373
 374 </para>
 375
 376 @chooser:
 377
 378
 379 <!-- ##### FUNCTION gtk_file_chooser_get_filenames ##### -->
 380 <para>
 381
 382 </para>
 383
 384 @chooser:
 385 @Returns:
 386
 387
 388 <!-- ##### FUNCTION gtk_file_chooser_set_current_folder ##### -->
 389 <para>
 390
 391 </para>
 392
 393 @chooser:
 394 @filename:
 395
 396
 397 <!-- ##### FUNCTION gtk_file_chooser_get_current_folder ##### -->
 398 <para>
 399
 400 </para>
 401
 402 @chooser:
 403 @Returns:
 404
 405
 406 <!-- ##### FUNCTION gtk_file_chooser_get_uri ##### -->
 407 <para>
 408
 409 </para>
 410
 411 @chooser:
 412 @Returns:
 413
 414
 415 <!-- ##### FUNCTION gtk_file_chooser_set_uri ##### -->
 416 <para>
 417
 418 </para>
 419
 420 @chooser:
 421 @uri:
 422
 423
 424 <!-- ##### FUNCTION gtk_file_chooser_select_uri ##### -->
 425 <para>
 426
 427 </para>
 428
 429 @chooser:
 430 @uri:
 431
 432
 433 <!-- ##### FUNCTION gtk_file_chooser_unselect_uri ##### -->
 434 <para>
 435
 436 </para>
 437
 438 @chooser:
 439 @uri:
 440
 441
 442 <!-- ##### FUNCTION gtk_file_chooser_get_uris ##### -->
 443 <para>
 444
 445 </para>
 446
 447 @chooser:
 448 @Returns:
 449
 450
 451 <!-- ##### FUNCTION gtk_file_chooser_set_current_folder_uri ##### -->
 452 <para>
 453
 454 </para>
 455
 456 @chooser:
 457 @uri:
 458
 459
 460 <!-- ##### FUNCTION gtk_file_chooser_get_current_folder_uri ##### -->
 461 <para>
 462
 463 </para>
 464
 465 @chooser:
 466 @Returns:
 467
 468
 469 <!-- ##### FUNCTION gtk_file_chooser_set_preview_widget ##### -->
 470 <para>
 471
 472 </para>
 473
 474 @chooser:
 475 @preview_widget:
 476
 477
 478 <!-- ##### FUNCTION gtk_file_chooser_get_preview_widget ##### -->
 479 <para>
 480
 481 </para>
 482
 483 @chooser:
 484 @Returns:
 485
 486
 487 <!-- ##### FUNCTION gtk_file_chooser_set_preview_widget_active ##### -->
 488 <para>
 489
 490 </para>
 491
 492 @chooser:
 493 @active:
 494
 495
 496 <!-- ##### FUNCTION gtk_file_chooser_get_preview_widget_active ##### -->
 497 <para>
 498
 499 </para>
 500
 501 @chooser:
 502 @Returns:
 503
 504
 505 <!-- ##### FUNCTION gtk_file_chooser_get_preview_filename ##### -->
 506 <para>
 507
 508 </para>
 509
 510 @chooser:
 511 @Returns:
 512 <!-- # Unused Parameters # -->
 513 @file_chooser:
 514
 515
 516 <!-- ##### FUNCTION gtk_file_chooser_get_preview_uri ##### -->
 517 <para>
 518
 519 </para>
 520
 521 @chooser:
 522 @Returns:
 523 <!-- # Unused Parameters # -->
 524 @file_chooser:
 525
 526
 527 <!-- ##### FUNCTION gtk_file_chooser_set_extra_widget ##### -->
 528 <para>
 529
 530 </para>
 531
 532 @chooser:
 533 @extra_widget:
 534
 535
 536 <!-- ##### FUNCTION gtk_file_chooser_get_extra_widget ##### -->
 537 <para>
 538
 539 </para>
 540
 541 @chooser:
 542 @Returns:
 543
 544
 545 <!-- ##### FUNCTION gtk_file_chooser_add_filter ##### -->
 546 <para>
 547
 548 </para>
 549
 550 @chooser:
 551 @filter:
 552
 553
 554 <!-- ##### FUNCTION gtk_file_chooser_remove_filter ##### -->
 555 <para>
 556
 557 </para>
 558
 559 @chooser:
 560 @filter:
 561
 562
 563 <!-- ##### FUNCTION gtk_file_chooser_list_filters ##### -->
 564 <para>
 565
 566 </para>
 567
 568 @chooser:
 569 @Returns:
 570
 571
 572 <!-- ##### FUNCTION gtk_file_chooser_set_filter ##### -->
 573 <para>
 574
 575 </para>
 576
 577 @chooser:
 578 @filter:
 579
 580
 581 <!-- ##### FUNCTION gtk_file_chooser_get_filter ##### -->
 582 <para>
 583
 584 </para>
 585
 586 @chooser:
 587 @Returns:
 588
 589
 590 <!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder ##### -->
 591 <para>
 592
 593 </para>
 594
 595 @chooser:
 596 @folder:
 597 @error:
 598 @Returns:
 599
 600
 601 <!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder ##### -->
 602 <para>
 603
 604 </para>
 605
 606 @chooser:
 607 @folder:
 608 @error:
 609 @Returns:
 610
 611
 612 <!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folders ##### -->
 613 <para>
 614
 615 </para>
 616
 617 @chooser:
 618 @Returns:
 619
 620
 621 <!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder_uri ##### -->
 622 <para>
 623
 624 </para>
 625
 626 @chooser:
 627 @uri:
 628 @error:
 629 @Returns:
 630 <!-- # Unused Parameters # -->
 631 @folder:
 632
 633
 634 <!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder_uri ##### -->
 635 <para>
 636
 637 </para>
 638
 639 @chooser:
 640 @uri:
 641 @error:
 642 @Returns:
 643 <!-- # Unused Parameters # -->
 644 @folder:
 645
 646
 647 <!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folder_uris ##### -->
 648 <para>
 649
 650 </para>
 651
 652 @chooser:
 653 @Returns:
 654
 655
 656
 657 <!--
 658 Local variables:
 659 mode: sgml
 660 sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
 661 End:
 662 -->
 663
 664