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     <refsect2 id="gtkfilechooser-key-bindings">
 120       <title>Key Bindings</title>
 121
 122       <para>
 123         Internally, GTK+ implements a file chooser's graphical user
 124         interface with the private
 125         <classname>GtkFileChooserDefaultClass</classname>.  This
 126         widget has several <link linkend="gtk-Bindings"">key
 127         bindings</link> and their associated signals.  This section
 128         describes the available key binding signals.
 129       </para>
 130
 131       <refsect3 id="GtkFileChooserDefault-location-popup">
 132         <title>The &quot;GtkFileChooserDefault::location-popup&quot; signal</title>
 133
 134         <programlisting>
 135           void user_function (GtkFileChooserDefault *chooser,
 136                               <link linkend="gpointer">gpointer</link> user_data);
 137         </programlisting>
 138
 139         <para>
 140           This is used to make the file chooser show a "Location"
 141           dialog which the user can use to manually type the name of
 142           the file he wishes to select.  By default this is bound to
 143           <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>.
 144         </para>
 145
 146         <variablelist role="params">
 147           <varlistentry>
 148             <term><parameter>chooser</parameter>&nbsp;:</term>
 149             <listitem>
 150               <simpara>
 151                 the object which received the signal.
 152               </simpara>
 153             </listitem>
 154           </varlistentry>
 155           <varlistentry>
 156             <term><parameter>user_data</parameter>&nbsp;:</term>
 157             <listitem>
 158               <simpara>
 159                 user data set when the signal handler was connected.
 160               </simpara>
 161             </listitem>
 162           </varlistentry>
 163         </variablelist>
 164       </refsect3>
 165
 166       <refsect3 id="GtkFileChooserDefault-up-folder">
 167         <title>The &quot;GtkFileChooserDefault::up-folder&quot; signal</title>
 168
 169         <programlisting>
 170           void user_function (GtkFileChooserDefault *chooser,
 171                               <link linkend="gpointer">gpointer</link> user_data);
 172         </programlisting>
 173
 174         <para>
 175           This is used to make the file chooser go to the parent of
 176           the current folder in the file hierarchy.  By default this
 177           is bound to
 178           <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>.
 179         </para>
 180
 181         <variablelist role="params">
 182           <varlistentry>
 183             <term><parameter>chooser</parameter>&nbsp;:</term>
 184             <listitem>
 185               <simpara>
 186                 the object which received the signal.
 187               </simpara>
 188             </listitem>
 189           </varlistentry>
 190           <varlistentry>
 191             <term><parameter>user_data</parameter>&nbsp;:</term>
 192             <listitem>
 193               <simpara>
 194                 user data set when the signal handler was connected.
 195               </simpara>
 196             </listitem>
 197           </varlistentry>
 198         </variablelist>
 199       </refsect3>
 200
 201       <refsect3 id="GtkFileChooserDefault-down-folder">
 202         <title>The &quot;GtkFileChooserDefault::down-folder&quot; signal</title>
 203
 204         <programlisting>
 205           void user_function (GtkFileChooserDefault *chooser,
 206                               <link linkend="gpointer">gpointer</link> user_data);
 207         </programlisting>
 208
 209         <para>
 210           This is used to make the file chooser go to a child of the
 211           current folder in the file hierarchy.  The subfolder that
 212           will be used is displayed in the path bar widget of the file
 213           chooser.  For example, if the path bar is showing
 214           "/foo/<emphasis>bar/</emphasis>baz", then this will cause
 215           the file chooser to switch to the "baz" subfolder.  By
 216           default this is bound to
 217           <keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>.
 218         </para>
 219
 220         <variablelist role="params">
 221           <varlistentry>
 222             <term><parameter>chooser</parameter>&nbsp;:</term>
 223             <listitem>
 224               <simpara>
 225                 the object which received the signal.
 226               </simpara>
 227             </listitem>
 228           </varlistentry>
 229           <varlistentry>
 230             <term><parameter>user_data</parameter>&nbsp;:</term>
 231             <listitem>
 232               <simpara>
 233                 user data set when the signal handler was connected.
 234               </simpara>
 235             </listitem>
 236           </varlistentry>
 237         </variablelist>
 238       </refsect3>
 239
 240       <refsect3 id="GtkFileChooserDefault-home-folder">
 241         <title>The &quot;GtkFileChooserDefault::home-folder&quot; signal</title>
 242
 243         <programlisting>
 244           void user_function (GtkFileChooserDefault *chooser,
 245                               <link linkend="gpointer">gpointer</link> user_data);
 246         </programlisting>
 247
 248         <para>
 249           This is used to make the file chooser show the user's home
 250           folder in the file list.  By default this is bound to
 251           <keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo>.
 252         </para>
 253
 254         <variablelist role="params">
 255           <varlistentry>
 256             <term><parameter>chooser</parameter>&nbsp;:</term>
 257             <listitem>
 258               <simpara>
 259                 the object which received the signal.
 260               </simpara>
 261             </listitem>
 262           </varlistentry>
 263           <varlistentry>
 264             <term><parameter>user_data</parameter>&nbsp;:</term>
 265             <listitem>
 266               <simpara>
 267                 user data set when the signal handler was connected.
 268               </simpara>
 269             </listitem>
 270           </varlistentry>
 271         </variablelist>
 272       </refsect3>
 273     </refsect2>
 274
 275 <!-- ##### SECTION See_Also ##### -->
 276     <para>
 277       #GtkFileChooserDialog, #GtkFileChooserWidget
 278     </para>
 279
 280 <!-- ##### STRUCT GtkFileChooser ##### -->
 281 <para>
 282
 283 </para>
 284
 285
 286 <!-- ##### SIGNAL GtkFileChooser::current-folder-changed ##### -->
 287 <para>
 288
 289 </para>
 290
 291 @filechooser: the object which received the signal.
 292
 293 <!-- ##### SIGNAL GtkFileChooser::file-activated ##### -->
 294 <para>
 295
 296 </para>
 297
 298 @filechooser: the object which received the signal.
 299
 300 <!-- ##### SIGNAL GtkFileChooser::selection-changed ##### -->
 301 <para>
 302
 303 </para>
 304
 305 @filechooser: the object which received the signal.
 306
 307 <!-- ##### SIGNAL GtkFileChooser::update-preview ##### -->
 308 <para>
 309
 310 </para>
 311
 312 @filechooser: the object which received the signal.
 313
 314 <!-- ##### ARG GtkFileChooser:action ##### -->
 315 <para>
 316
 317 </para>
 318
 319 <!-- ##### ARG GtkFileChooser:extra-widget ##### -->
 320 <para>
 321
 322 </para>
 323
 324 <!-- ##### ARG GtkFileChooser:file-system-backend ##### -->
 325 <para>
 326
 327 </para>
 328
 329 <!-- ##### ARG GtkFileChooser:filter ##### -->
 330 <para>
 331
 332 </para>
 333
 334 <!-- ##### ARG GtkFileChooser:local-only ##### -->
 335 <para>
 336
 337 </para>
 338
 339 <!-- ##### ARG GtkFileChooser:preview-widget ##### -->
 340 <para>
 341
 342 </para>
 343
 344 <!-- ##### ARG GtkFileChooser:preview-widget-active ##### -->
 345 <para>
 346
 347 </para>
 348
 349 <!-- ##### ARG GtkFileChooser:select-multiple ##### -->
 350 <para>
 351
 352 </para>
 353
 354 <!-- ##### ARG GtkFileChooser:show-hidden ##### -->
 355 <para>
 356
 357 </para>
 358
 359 <!-- ##### ARG GtkFileChooser:use-preview-label ##### -->
 360 <para>
 361
 362 </para>
 363
 364 <!-- ##### ENUM GtkFileChooserAction ##### -->
 365     <para>
 366       Describes whether a #GtkFileChooser is being used to open
 367       existing files or to save to a possibly new file.
 368     </para>
 369
 370 @GTK_FILE_CHOOSER_ACTION_OPEN: Indicates open mode.  The file chooser
 371     will only let the user pick an existing file.
 372 @GTK_FILE_CHOOSER_ACTION_SAVE: Indicates save mode.  The file chooser
 373     will let the user pick an existing file, or type in a new
 374     filename.
 375 @GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER: Indicates an Open mode for
 376     selecting folders.  The file chooser will let the user pick an
 377     existing folder.
 378 @GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER: Indicates a mode for creating a
 379     new folder.  The file chooser will let the user name an existing or
 380     new folder.
 381
 382 <!-- ##### MACRO GTK_FILE_CHOOSER_ERROR ##### -->
 383     <para>
 384       Used to get the #GError quark for #GtkFileChooser errors.
 385     </para>
 386
 387
 388
 389 <!-- ##### ENUM GtkFileChooserError ##### -->
 390     <para>
 391       These identify the various errors that can occur while calling
 392       #GtkFileChooser functions.
 393     </para>
 394
 395 @GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist.
 396 @GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename.
 397
 398 <!-- ##### FUNCTION gtk_file_chooser_error_quark ##### -->
 399 <para>
 400
 401 </para>
 402
 403 @Returns:
 404
 405
 406 <!-- ##### FUNCTION gtk_file_chooser_set_action ##### -->
 407 <para>
 408
 409 </para>
 410
 411 @chooser:
 412 @action:
 413
 414
 415 <!-- ##### FUNCTION gtk_file_chooser_get_action ##### -->
 416 <para>
 417
 418 </para>
 419
 420 @chooser:
 421 @Returns:
 422
 423
 424 <!-- ##### FUNCTION gtk_file_chooser_set_local_only ##### -->
 425 <para>
 426
 427 </para>
 428
 429 @chooser:
 430 @local_only:
 431 <!-- # Unused Parameters # -->
 432 @files_only:
 433
 434
 435 <!-- ##### FUNCTION gtk_file_chooser_get_local_only ##### -->
 436 <para>
 437
 438 </para>
 439
 440 @chooser:
 441 @Returns:
 442
 443
 444 <!-- ##### FUNCTION gtk_file_chooser_set_select_multiple ##### -->
 445 <para>
 446
 447 </para>
 448
 449 @chooser:
 450 @select_multiple:
 451
 452
 453 <!-- ##### FUNCTION gtk_file_chooser_get_select_multiple ##### -->
 454 <para>
 455
 456 </para>
 457
 458 @chooser:
 459 @Returns:
 460
 461
 462 <!-- ##### FUNCTION gtk_file_chooser_set_current_name ##### -->
 463 <para>
 464
 465 </para>
 466
 467 @chooser:
 468 @name:
 469
 470
 471 <!-- ##### FUNCTION gtk_file_chooser_get_filename ##### -->
 472 <para>
 473
 474 </para>
 475
 476 @chooser:
 477 @Returns:
 478
 479
 480 <!-- ##### FUNCTION gtk_file_chooser_set_filename ##### -->
 481 <para>
 482
 483 </para>
 484
 485 @chooser:
 486 @filename:
 487 @Returns:
 488
 489
 490 <!-- ##### FUNCTION gtk_file_chooser_select_filename ##### -->
 491 <para>
 492
 493 </para>
 494
 495 @chooser:
 496 @filename:
 497 @Returns:
 498
 499
 500 <!-- ##### FUNCTION gtk_file_chooser_unselect_filename ##### -->
 501 <para>
 502
 503 </para>
 504
 505 @chooser:
 506 @filename:
 507
 508
 509 <!-- ##### FUNCTION gtk_file_chooser_select_all ##### -->
 510 <para>
 511
 512 </para>
 513
 514 @chooser:
 515
 516
 517 <!-- ##### FUNCTION gtk_file_chooser_unselect_all ##### -->
 518 <para>
 519
 520 </para>
 521
 522 @chooser:
 523
 524
 525 <!-- ##### FUNCTION gtk_file_chooser_get_filenames ##### -->
 526 <para>
 527
 528 </para>
 529
 530 @chooser:
 531 @Returns:
 532
 533
 534 <!-- ##### FUNCTION gtk_file_chooser_set_current_folder ##### -->
 535 <para>
 536
 537 </para>
 538
 539 @chooser:
 540 @filename:
 541 @Returns:
 542
 543
 544 <!-- ##### FUNCTION gtk_file_chooser_get_current_folder ##### -->
 545 <para>
 546
 547 </para>
 548
 549 @chooser:
 550 @Returns:
 551
 552
 553 <!-- ##### FUNCTION gtk_file_chooser_get_uri ##### -->
 554 <para>
 555
 556 </para>
 557
 558 @chooser:
 559 @Returns:
 560
 561
 562 <!-- ##### FUNCTION gtk_file_chooser_set_uri ##### -->
 563 <para>
 564
 565 </para>
 566
 567 @chooser:
 568 @uri:
 569 @Returns:
 570
 571
 572 <!-- ##### FUNCTION gtk_file_chooser_select_uri ##### -->
 573 <para>
 574
 575 </para>
 576
 577 @chooser:
 578 @uri:
 579 @Returns:
 580
 581
 582 <!-- ##### FUNCTION gtk_file_chooser_unselect_uri ##### -->
 583 <para>
 584
 585 </para>
 586
 587 @chooser:
 588 @uri:
 589
 590
 591 <!-- ##### FUNCTION gtk_file_chooser_get_uris ##### -->
 592 <para>
 593
 594 </para>
 595
 596 @chooser:
 597 @Returns:
 598
 599
 600 <!-- ##### FUNCTION gtk_file_chooser_set_current_folder_uri ##### -->
 601 <para>
 602
 603 </para>
 604
 605 @chooser:
 606 @uri:
 607 @Returns:
 608
 609
 610 <!-- ##### FUNCTION gtk_file_chooser_get_current_folder_uri ##### -->
 611 <para>
 612
 613 </para>
 614
 615 @chooser:
 616 @Returns:
 617
 618
 619 <!-- ##### FUNCTION gtk_file_chooser_set_preview_widget ##### -->
 620 <para>
 621
 622 </para>
 623
 624 @chooser:
 625 @preview_widget:
 626
 627
 628 <!-- ##### FUNCTION gtk_file_chooser_get_preview_widget ##### -->
 629 <para>
 630
 631 </para>
 632
 633 @chooser:
 634 @Returns:
 635
 636
 637 <!-- ##### FUNCTION gtk_file_chooser_set_preview_widget_active ##### -->
 638 <para>
 639
 640 </para>
 641
 642 @chooser:
 643 @active:
 644
 645
 646 <!-- ##### FUNCTION gtk_file_chooser_get_preview_widget_active ##### -->
 647 <para>
 648
 649 </para>
 650
 651 @chooser:
 652 @Returns:
 653
 654
 655 <!-- ##### FUNCTION gtk_file_chooser_set_use_preview_label ##### -->
 656 <para>
 657
 658 </para>
 659
 660 @chooser:
 661 @use_label:
 662
 663
 664 <!-- ##### FUNCTION gtk_file_chooser_get_use_preview_label ##### -->
 665 <para>
 666
 667 </para>
 668
 669 @chooser:
 670 @Returns:
 671
 672
 673 <!-- ##### FUNCTION gtk_file_chooser_get_preview_filename ##### -->
 674 <para>
 675
 676 </para>
 677
 678 @chooser:
 679 @Returns:
 680 <!-- # Unused Parameters # -->
 681 @file_chooser:
 682
 683
 684 <!-- ##### FUNCTION gtk_file_chooser_get_preview_uri ##### -->
 685 <para>
 686
 687 </para>
 688
 689 @chooser:
 690 @Returns:
 691 <!-- # Unused Parameters # -->
 692 @file_chooser:
 693
 694
 695 <!-- ##### FUNCTION gtk_file_chooser_set_extra_widget ##### -->
 696 <para>
 697
 698 </para>
 699
 700 @chooser:
 701 @extra_widget:
 702
 703
 704 <!-- ##### FUNCTION gtk_file_chooser_get_extra_widget ##### -->
 705 <para>
 706
 707 </para>
 708
 709 @chooser:
 710 @Returns:
 711
 712
 713 <!-- ##### FUNCTION gtk_file_chooser_add_filter ##### -->
 714 <para>
 715
 716 </para>
 717
 718 @chooser:
 719 @filter:
 720
 721
 722 <!-- ##### FUNCTION gtk_file_chooser_remove_filter ##### -->
 723 <para>
 724
 725 </para>
 726
 727 @chooser:
 728 @filter:
 729
 730
 731 <!-- ##### FUNCTION gtk_file_chooser_list_filters ##### -->
 732 <para>
 733
 734 </para>
 735
 736 @chooser:
 737 @Returns:
 738
 739
 740 <!-- ##### FUNCTION gtk_file_chooser_set_filter ##### -->
 741 <para>
 742
 743 </para>
 744
 745 @chooser:
 746 @filter:
 747
 748
 749 <!-- ##### FUNCTION gtk_file_chooser_get_filter ##### -->
 750 <para>
 751
 752 </para>
 753
 754 @chooser:
 755 @Returns:
 756
 757
 758 <!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder ##### -->
 759 <para>
 760
 761 </para>
 762
 763 @chooser:
 764 @folder:
 765 @error:
 766 @Returns:
 767
 768
 769 <!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder ##### -->
 770 <para>
 771
 772 </para>
 773
 774 @chooser:
 775 @folder:
 776 @error:
 777 @Returns:
 778
 779
 780 <!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folders ##### -->
 781 <para>
 782
 783 </para>
 784
 785 @chooser:
 786 @Returns:
 787
 788
 789 <!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder_uri ##### -->
 790 <para>
 791
 792 </para>
 793
 794 @chooser:
 795 @uri:
 796 @error:
 797 @Returns:
 798 <!-- # Unused Parameters # -->
 799 @folder:
 800
 801
 802 <!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder_uri ##### -->
 803 <para>
 804
 805 </para>
 806
 807 @chooser:
 808 @uri:
 809 @error:
 810 @Returns:
 811 <!-- # Unused Parameters # -->
 812 @folder:
 813
 814
 815 <!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folder_uris ##### -->
 816 <para>
 817
 818 </para>
 819
 820 @chooser:
 821 @Returns:
 822
 823
 824
 825 <!--
 826 Local variables:
 827 mode: sgml
 828 sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
 829 End:
 830 -->
 831
 832