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