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 this
  11       interface are #GtkFileChooserWidget, #GtkFileChooserDialog, and
  12       #GtkFileChooserButton.  You do not need to write an object that
  13       implements the #GtkFileChooser interface unless you are trying to
  14       adapt an existing file selector to expose a standard programming
  15       interface.
  16     </para>
  17
  18     <para>
  19       #GtkFileChooser allows for shortcuts to various places in the filesystem.
  20       In the default implementation these are displayed in the left pane. It
  21       may be a bit confusing at first taht these shortcuts come from various
  22       sources and in various flavours, so lets explain the terminology here:
  23     </para>
  24       <variablelist>
  25          <varlistentry>
  26            <term>Bookmarks</term>
  27            <listitem><para>
  28              are created by the user, by dragging folders from the
  29              right pane to the left pane, or by using the "Add". Bookmarks
  30              can be renamed and deleted by the user.
  31            </para></listitem>
  32          </varlistentry>
  33          <varlistentry>
  34            <term>Shortcuts</term>
  35            <listitem><para>
  36              can be provided by the application or by the underlying filesystem
  37              abstraction (e.g. both the gnome-vfs and the Windows filesystems
  38              provide "Desktop" shortcuts). Shortcuts cannot be modified by the
  39              user.
  40            </para></listitem>
  41          </varlistentry>
  42          <varlistentry>
  43            <term>Volumes</term>
  44            <listitem><para>
  45              are provided by the underlying filesystem abstraction. They are
  46              the "roots" of the filesystem.
  47            </para></listitem>
  48          </varlistentry>
  49       </variablelist>
  50
  51     <refsect2 id="gtkfilechooser-encodings">
  52       <title>File Names and Encodings</title>
  53
  54       <para>
  55         When the user is finished selecting files in a
  56         #GtkFileChooser, your program can get the selected names
  57         either as filenames or as URIs.  For URIs, the normal escaping
  58         rules are applied if the URI contains non-ASCII characters.
  59         However, filenames are <emphasis>always</emphasis> returned in
  60         the character set specified by the
  61         <envar>G_FILENAME_ENCODING</envar> environment variable.
  62         Please see the Glib documentation for more details about this
  63         variable.
  64       </para>
  65
  66       <important>
  67         <para>
  68           This means that while you can pass the result of
  69           gtk_file_chooser_get_filename() to
  70           <function>open(2)</function> or
  71           <function>fopen(3)</function>, you may not be able to
  72           directly set it as the text of a #GtkLabel widget unless you
  73           convert it first to UTF-8, which all GTK+ widgets expect.
  74           You should use g_filename_to_utf8() to convert filenames
  75           into strings that can be passed to GTK+ widgets.
  76         </para>
  77       </important>
  78     </refsect2>
  79
  80     <refsect2 id="gtkfilechooser-preview">
  81       <title>Adding a Preview Widget</title>
  82
  83       <para>
  84         You can add a custom preview widget to a file chooser and then
  85         get notification about when the preview needs to be updated.
  86         To install a preview widget, use
  87         gtk_file_chooser_set_preview_widget().  Then, connect to the
  88         #GtkFileChooser::update-preview signal to get notified when
  89         you need to update the contents of the preview.
  90       </para>
  91
  92       <para>
  93         Your callback should use
  94         gtk_file_chooser_get_preview_filename() to see what needs
  95         previewing.  Once you have generated the preview for the
  96         corresponding file, you must call
  97         gtk_file_chooser_set_preview_widget_active() with a boolean
  98         flag that indicates whether your callback could successfully
  99         generate a preview.
 100       </para>
 101
 102       <example id="example-gtkfilechooser-preview">
 103         <title>Sample Usage</title>
 104
 105         <programlisting>
 106 {
 107   GtkImage *preview;
 108
 109   ...
 110
 111   preview = gtk_image_new (<!-- -->);
 112
 113   gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
 114   g_signal_connect (my_file_chooser, "update-preview",
 115                     G_CALLBACK (update_preview_cb), preview);
 116 }
 117
 118 static void
 119 update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
 120 {
 121   GtkWidget *preview;
 122   char *filename;
 123   GdkPixbuf *pixbuf;
 124   gboolean have_preview;
 125
 126   preview = GTK_WIDGET (data);
 127   filename = gtk_file_chooser_get_preview_filename (file_chooser);
 128
 129   pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
 130   have_preview = (pixbuf != NULL);
 131   g_free (filename);
 132
 133   gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
 134   if (pixbuf)
 135     gobject_unref (pixbuf);
 136
 137   gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
 138 }
 139         </programlisting>
 140       </example>
 141     </refsect2>
 142
 143     <refsect2 id="gtkfilechooser-extra">
 144       <title>Adding Extra Widgets</title>
 145
 146       <para>
 147         You can add extra widgets to a file chooser to provide options
 148         that are not present in the default design.  For example, you
 149         can add a toggle button to give the user the option to open a
 150         file in read-only mode.  You can use
 151         gtk_file_chooser_set_extra_widget() to insert additional
 152         widgets in a file chooser.
 153       </para>
 154
 155       <example id="example-gtkfilechooser-extra">
 156         <title>Sample Usage</title>
 157
 158         <programlisting>
 159 {
 160   GtkWidget *toggle;
 161
 162   ...
 163
 164   toggle = gtk_check_button_new_with_label ("Open file read-only");
 165   gtk_widget_show (toggle);
 166   gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
 167 }
 168         </programlisting>
 169       </example>
 170
 171       <note>
 172         <para>
 173           If you want to set more than one extra widget in the file
 174           chooser, you can a container such as a GtkVBox or a GtkTable
 175           and include your widgets in it.  Then, set the container as
 176           the whole extra widget.
 177         </para>
 178       </note>
 179     </refsect2>
 180
 181     <refsect2 id="gtkfilechooser-key-bindings">
 182       <title>Key Bindings</title>
 183
 184       <para>
 185         Internally, GTK+ implements a file chooser's graphical user
 186         interface with the private
 187         <classname>GtkFileChooserDefaultClass</classname>.  This
 188         widget has several <link linkend="gtk-Bindings">key
 189         bindings</link> and their associated signals.  This section
 190         describes the available key binding signals.
 191       </para>
 192
 193       <example id="gtkfilechooser-key-binding-example">
 194         <title>GtkFileChooser key binding example</title>
 195
 196         <para>
 197           The default keys that activate the key-binding signals in
 198           <classname>GtkFileChooserDefaultClass</classname> are as
 199           follows:
 200         </para>
 201
 202         <informaltable>
 203           <tgroup cols="2">
 204             <tbody>
 205               <row>
 206                 <entry>Signal name</entry>
 207                 <entry>Default key combinations</entry>
 208               </row>
 209               <row>
 210                 <entry>location-popup</entry>
 211                 <entry>
 212                   <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> (empty path);
 213                   <keycap>/</keycap> (path of "/")<footnote>
 214                     <para>
 215                       Both the individual <keycap>/</keycap> key and the
 216                       numeric keypad's "divide" key are supported.
 217                     </para>
 218                   </footnote>;
 219                   <keycap>~</keycap> (path of "~")
 220                 </entry>
 221               </row>
 222               <row>
 223                 <entry>up-folder</entry>
 224                 <entry>
 225                   <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo><footnote>
 226                     <para>
 227                       Both the individual Up key and the numeric
 228                       keypad's Up key are supported.
 229                     </para>
 230                   </footnote>
 231                   ;
 232                   <keycap>Backspace</keycap>
 233                 </entry>
 234               </row>
 235               <row>
 236                 <entry>down-folder</entry>
 237                 <entry><keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo></entry>
 238               </row>
 239               <row>
 240                 <entry>home-folder</entry>
 241                 <entry><keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo></entry>
 242               </row>
 243               <row>
 244                 <entry>desktop-folder</entry>
 245                 <entry><keycombo><keycap>Alt</keycap><keycap>D</keycap></keycombo></entry>
 246               </row>
 247               <row>
 248                 <entry>quick-bookmark</entry>
 249                 <entry><keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo> through <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo></entry>
 250               </row>
 251             </tbody>
 252           </tgroup>
 253         </informaltable>
 254
 255         <para>
 256           You can change these defaults to something else.  For
 257           example, to add a <keycap>Shift</keycap> modifier to a few
 258           of the default bindings, you can include the following
 259           fragment in your <filename>.gtkrc-2.0</filename> file:
 260         </para>
 261
 262         <programlisting>
 263 binding "my-own-gtkfilechooser-bindings" {
 264         bind "&lt;Alt&gt;&lt;Shift&gt;Up" {
 265                 "up-folder" ()
 266         }
 267         bind "&lt;Alt&gt;&lt;Shift&gt;Down" {
 268                 "down-folder" ()
 269         }
 270         bind "&lt;Alt&gt;&lt;Shift&gt;Home" {
 271                 "home-folder" ()
 272         }
 273 }
 274
 275 class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"
 276         </programlisting>
 277       </example>
 278
 279       <refsect3 id="GtkFileChooserDefault-location-popup">
 280         <title>The &quot;GtkFileChooserDefault::location-popup&quot; signal</title>
 281
 282         <programlisting>
 283           void user_function (GtkFileChooserDefault *chooser,
 284                               const char            *path,
 285                               <link linkend="gpointer">gpointer</link> user_data);
 286         </programlisting>
 287
 288         <para>
 289           This is used to make the file chooser show a "Location"
 290           dialog which the user can use to manually type the name of
 291           the file he wishes to select.  The
 292           <parameter>path</parameter> argument is a string that gets
 293           put in the text entry for the file name.  By default this is bound to
 294           <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
 295           with a <parameter>path</parameter> string of "" (the empty
 296           string).  It is also bound to <keycap>/</keycap> with a
 297           <parameter>path</parameter> string of "<literal>/</literal>"
 298           (a slash):  this lets you type <keycap>/</keycap> and
 299           immediately type a path name.  On Unix systems, this is bound to
 300           <keycap>~</keycap> (tilde) with a <parameter>path</parameter> string
 301           of "~" itself for access to home directories.
 302         </para>
 303
 304         <variablelist role="params">
 305           <varlistentry>
 306             <term><parameter>chooser</parameter>&nbsp;:</term>
 307             <listitem>
 308               <simpara>
 309                 the object which received the signal.
 310               </simpara>
 311             </listitem>
 312           </varlistentry>
 313           <varlistentry>
 314             <term><parameter>path</parameter>&nbsp;:</term>
 315             <listitem>
 316               <simpara>
 317                 default contents for the text entry for the file name
 318               </simpara>
 319             </listitem>
 320           </varlistentry>
 321           <varlistentry>
 322             <term><parameter>user_data</parameter>&nbsp;:</term>
 323             <listitem>
 324               <simpara>
 325                 user data set when the signal handler was connected.
 326               </simpara>
 327             </listitem>
 328           </varlistentry>
 329         </variablelist>
 330
 331         <tip>
 332           <para>
 333             You can create your own bindings for the
 334             <symbol>location-popup</symbol> signal with custom
 335             <parameter>path</parameter> strings, and have a crude form
 336             of easily-to-type bookmarks.  For example, say you access
 337             the path <filename>/home/username/misc</filename> very
 338             frequently.  You could then create an <keycombo>
 339             <keycap>Alt</keycap> <keycap>M</keycap> </keycombo>
 340             shortcut by including the following in your
 341             <filename>.gtkrc-2.0</filename>:
 342           </para>
 343
 344           <programlisting>
 345 binding "misc-shortcut" {
 346         bind "&lt;Alt&gt;M" {
 347                 "location-popup" ("/home/username/misc")
 348         }
 349 }
 350
 351 class "GtkFileChooserDefault" binding "misc-shortcut"
 352           </programlisting>
 353         </tip>
 354       </refsect3>
 355
 356       <refsect3 id="GtkFileChooserDefault-up-folder">
 357         <title>The &quot;GtkFileChooserDefault::up-folder&quot; signal</title>
 358
 359         <programlisting>
 360           void user_function (GtkFileChooserDefault *chooser,
 361                               <link linkend="gpointer">gpointer</link> user_data);
 362         </programlisting>
 363
 364         <para>
 365           This is used to make the file chooser go to the parent of
 366           the current folder in the file hierarchy.  By default this
 367           is bound to <keycap>Backspace</keycap> and
 368           <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>
 369           (the Up key in the numeric keypad also works).
 370         </para>
 371
 372         <variablelist role="params">
 373           <varlistentry>
 374             <term><parameter>chooser</parameter>&nbsp;:</term>
 375             <listitem>
 376               <simpara>
 377                 the object which received the signal.
 378               </simpara>
 379             </listitem>
 380           </varlistentry>
 381           <varlistentry>
 382             <term><parameter>user_data</parameter>&nbsp;:</term>
 383             <listitem>
 384               <simpara>
 385                 user data set when the signal handler was connected.
 386               </simpara>
 387             </listitem>
 388           </varlistentry>
 389         </variablelist>
 390       </refsect3>
 391
 392       <refsect3 id="GtkFileChooserDefault-down-folder">
 393         <title>The &quot;GtkFileChooserDefault::down-folder&quot; signal</title>
 394
 395         <programlisting>
 396           void user_function (GtkFileChooserDefault *chooser,
 397                               <link linkend="gpointer">gpointer</link> user_data);
 398         </programlisting>
 399
 400         <para>
 401           This is used to make the file chooser go to a child of the
 402           current folder in the file hierarchy.  The subfolder that
 403           will be used is displayed in the path bar widget of the file
 404           chooser.  For example, if the path bar is showing
 405           "/foo/<emphasis>bar/</emphasis>baz", then this will cause
 406           the file chooser to switch to the "baz" subfolder.  By
 407           default this is bound to
 408           <keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>
 409           (the Down key in the numeric keypad also works).
 410         </para>
 411
 412         <variablelist role="params">
 413           <varlistentry>
 414             <term><parameter>chooser</parameter>&nbsp;:</term>
 415             <listitem>
 416               <simpara>
 417                 the object which received the signal.
 418               </simpara>
 419             </listitem>
 420           </varlistentry>
 421           <varlistentry>
 422             <term><parameter>user_data</parameter>&nbsp;:</term>
 423             <listitem>
 424               <simpara>
 425                 user data set when the signal handler was connected.
 426               </simpara>
 427             </listitem>
 428           </varlistentry>
 429         </variablelist>
 430       </refsect3>
 431
 432       <refsect3 id="GtkFileChooserDefault-home-folder">
 433         <title>The &quot;GtkFileChooserDefault::home-folder&quot; signal</title>
 434
 435         <programlisting>
 436           void user_function (GtkFileChooserDefault *chooser,
 437                               <link linkend="gpointer">gpointer</link> user_data);
 438         </programlisting>
 439
 440         <para>
 441           This is used to make the file chooser show the user's home
 442           folder in the file list.  By default this is bound to
 443           <keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo>
 444           (the Home key in the numeric keypad also works).
 445         </para>
 446
 447         <variablelist role="params">
 448           <varlistentry>
 449             <term><parameter>chooser</parameter>&nbsp;:</term>
 450             <listitem>
 451               <simpara>
 452                 the object which received the signal.
 453               </simpara>
 454             </listitem>
 455           </varlistentry>
 456           <varlistentry>
 457             <term><parameter>user_data</parameter>&nbsp;:</term>
 458             <listitem>
 459               <simpara>
 460                 user data set when the signal handler was connected.
 461               </simpara>
 462             </listitem>
 463           </varlistentry>
 464         </variablelist>
 465       </refsect3>
 466
 467       <refsect3 id="GtkFileChooserDefault-desktop-folder">
 468         <title>The &quot;GtkFileChooserDefault::desktop-folder&quot; signal</title>
 469
 470         <programlisting>
 471           void user_function (GtkFileChooserDefault *chooser,
 472                               <link linkend="gpointer">gpointer</link> user_data);
 473         </programlisting>
 474
 475         <para>
 476           This is used to make the file chooser show the user's Desktop
 477           folder in the file list.  By default this is bound to
 478           <keycombo><keycap>Alt</keycap><keycap>D</keycap></keycombo>.
 479         </para>
 480
 481         <variablelist role="params">
 482           <varlistentry>
 483             <term><parameter>chooser</parameter>&nbsp;:</term>
 484             <listitem>
 485               <simpara>
 486                 the object which received the signal.
 487               </simpara>
 488             </listitem>
 489           </varlistentry>
 490           <varlistentry>
 491             <term><parameter>user_data</parameter>&nbsp;:</term>
 492             <listitem>
 493               <simpara>
 494                 user data set when the signal handler was connected.
 495               </simpara>
 496             </listitem>
 497           </varlistentry>
 498         </variablelist>
 499       </refsect3>
 500
 501       <refsect3 id="GtkFileChooserDefault-quick-bookmark">
 502         <title>The &quot;GtkFileChooserDefault::quick-bookmark&quot; signal</title>
 503
 504         <programlisting>
 505           void user_function (GtkFileChooserDefault *chooser,
 506                               gint bookmark_index,
 507                               <link linkend="gpointer">gpointer</link> user_data);
 508         </programlisting>
 509
 510         <para>
 511           This is used to make the file chooser switch to the bookmark
 512           specified in the <parameter>bookmark_index</parameter> parameter.
 513           For example, if you have three bookmarks, you can pass 0, 1, 2 to
 514           this signal to switch to each of them, respectively.  By default this is bound to
 515           <keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo>,
 516           <keycombo><keycap>Alt</keycap><keycap>2</keycap></keycombo>,
 517           etc. until
 518           <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo>.  Note
 519           that in the default binding,
 520           that <keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo> is
 521           actually defined to switch to the bookmark at index 0, and so on
 522           successively;
 523           <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo> is
 524           defined to switch to the bookmark at index 10.
 525         </para>
 526
 527         <variablelist role="params">
 528           <varlistentry>
 529             <term><parameter>chooser</parameter>&nbsp;:</term>
 530             <listitem>
 531               <simpara>
 532                 the object which received the signal.
 533               </simpara>
 534             </listitem>
 535           </varlistentry>
 536           <varlistentry>
 537             <term><parameter>bookmark_indes</parameter>&nbsp;:</term>
 538             <listitem>
 539               <simpara>
 540                 index of the bookmark to switch to; the indices start at 0.
 541               </simpara>
 542             </listitem>
 543           </varlistentry>
 544           <varlistentry>
 545             <term><parameter>user_data</parameter>&nbsp;:</term>
 546             <listitem>
 547               <simpara>
 548                 user data set when the signal handler was connected.
 549               </simpara>
 550             </listitem>
 551           </varlistentry>
 552         </variablelist>
 553       </refsect3>
 554     </refsect2>
 555
 556 <!-- ##### SECTION See_Also ##### -->
 557     <para>
 558       #GtkFileChooserDialog, #GtkFileChooserWidget, #GtkFileChooserButton
 559     </para>
 560
 561 <!-- ##### SECTION Stability_Level ##### -->
 562
 563
 564 <!-- ##### STRUCT GtkFileChooser ##### -->
 565 <para>
 566
 567 </para>
 568
 569
 570 <!-- ##### SIGNAL GtkFileChooser::confirm-overwrite ##### -->
 571     <para>
 572       This signal gets emitted whenever it is appropriate to present a
 573       confirmation dialog when the user has selected a file name that
 574       already exists.  The signal only gets emitted when the file
 575       chooser is in #GTK_FILE_CHOOSER_ACTION_SAVE mode.
 576     </para>
 577
 578     <para>
 579       Most applications just need to turn on the <link
 580       linkend="GtkFileChooser--do-overwrite-confirmation">do-overwrite-confirmation</link>
 581       property (or call the
 582       gtk_file_chooser_set_do_overwrite_confirmation() function), and
 583       they will automatically get a stock confirmation dialog.
 584       Applications which need to customize this behavior should do
 585       that, and also connect to the <symbol>confirm-overwrite</symbol>
 586       signal.
 587     </para>
 588
 589     <para>
 590       A signal handler for this signal must return a
 591       #GtkFileChooserConfirmation value, which indicates the action to
 592       take.  If the handler determines that the user wants to select a
 593       different filename, it should return
 594       #GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN.  If it determines
 595       that the user is satisfied with his choice of file name, it
 596       should return #GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME.
 597       On the other hand, if it determines that the stock confirmation
 598       dialog should be used, it should return
 599       #GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM.  The following example
 600       illustrates this.
 601     </para>
 602
 603     <example id="gtkfilechooser-confirmation">
 604       <title>Custom confirmation</title>
 605
 606       <programlisting>
 607 static GtkFileChooserConfirmation
 608 confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data)
 609 {
 610   char *uri;
 611
 612   uri = gtk_file_chooser_get_uri (chooser);
 613
 614   if (is_uri_read_only (uri))
 615     {
 616       if (user_wants_to_replace_read_only_file (uri))
 617         return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME;
 618       else
 619         return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN;
 620     } else
 621       return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; /* fall back to the default dialog */
 622 }
 623
 624 ...
 625
 626 chooser = gtk_file_chooser_dialog_new (...);
 627
 628 gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
 629 g_signal_connect (chooser, "confirm-overwrite",
 630                   G_CALLBACK (confirm_overwrite_callback), NULL);
 631
 632 if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT)
 633         save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser));
 634
 635 gtk_widget_destroy (chooser);
 636       </programlisting>
 637     </example>
 638
 639 @filechooser: the object which received the signal.
 640 @Returns: #GtkFileChooserConfirmation value that indicates which
 641     action to take after emitting the signal.
 642
 643     <para>
 644       Since 2.8
 645     </para>
 646
 647 <!-- ##### SIGNAL GtkFileChooser::current-folder-changed ##### -->
 648 <para>
 649
 650 </para>
 651
 652 @filechooser: the object which received the signal.
 653
 654 <!-- ##### SIGNAL GtkFileChooser::file-activated ##### -->
 655 <para>
 656
 657 </para>
 658
 659 @filechooser: the object which received the signal.
 660
 661 <!-- ##### SIGNAL GtkFileChooser::selection-changed ##### -->
 662 <para>
 663
 664 </para>
 665
 666 @filechooser: the object which received the signal.
 667
 668 <!-- ##### SIGNAL GtkFileChooser::update-preview ##### -->
 669 <para>
 670
 671 </para>
 672
 673 @filechooser: the object which received the signal.
 674
 675 <!-- ##### ARG GtkFileChooser:action ##### -->
 676 <para>
 677
 678 </para>
 679
 680 <!-- ##### ARG GtkFileChooser:do-overwrite-confirmation ##### -->
 681 <para>
 682
 683 </para>
 684
 685 <!-- ##### ARG GtkFileChooser:extra-widget ##### -->
 686 <para>
 687
 688 </para>
 689
 690 <!-- ##### ARG GtkFileChooser:file-system-backend ##### -->
 691 <para>
 692
 693 </para>
 694
 695 <!-- ##### ARG GtkFileChooser:filter ##### -->
 696 <para>
 697
 698 </para>
 699
 700 <!-- ##### ARG GtkFileChooser:local-only ##### -->
 701 <para>
 702
 703 </para>
 704
 705 <!-- ##### ARG GtkFileChooser:preview-widget ##### -->
 706 <para>
 707
 708 </para>
 709
 710 <!-- ##### ARG GtkFileChooser:preview-widget-active ##### -->
 711 <para>
 712
 713 </para>
 714
 715 <!-- ##### ARG GtkFileChooser:select-multiple ##### -->
 716 <para>
 717
 718 </para>
 719
 720 <!-- ##### ARG GtkFileChooser:show-hidden ##### -->
 721 <para>
 722
 723 </para>
 724
 725 <!-- ##### ARG GtkFileChooser:use-preview-label ##### -->
 726 <para>
 727
 728 </para>
 729
 730 <!-- ##### ENUM GtkFileChooserAction ##### -->
 731     <para>
 732       Describes whether a #GtkFileChooser is being used to open
 733       existing files or to save to a possibly new file.
 734     </para>
 735
 736 @GTK_FILE_CHOOSER_ACTION_OPEN: Indicates open mode.  The file chooser
 737     will only let the user pick an existing file.
 738 @GTK_FILE_CHOOSER_ACTION_SAVE: Indicates save mode.  The file chooser
 739     will let the user pick an existing file, or type in a new
 740     filename.
 741 @GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER: Indicates an Open mode for
 742     selecting folders.  The file chooser will let the user pick an
 743     existing folder.
 744 @GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER: Indicates a mode for creating a
 745     new folder.  The file chooser will let the user name an existing or
 746     new folder.
 747
 748 <!-- ##### ENUM GtkFileChooserConfirmation ##### -->
 749     <para>
 750       Used as a return value of handlers for the <link
 751       linkend="GtkFileChooser-confirm-overwrite">confirm-overwrite</link>
 752       signal of a <classname>GtkFileChooser</classname>.  This value
 753       determines whether the file chooser will present the stock
 754       confirmation dialog, accept the user's choice of a filename, or
 755       let the user choose another filename.
 756     </para>
 757
 758 @GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM: The file chooser will present
 759     its stock dialog to confirm about overwriting an existing file.
 760 @GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME: The file chooser will
 761     terminate and accept the user's choice of a file name.
 762 @GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN: The file chooser will
 763     continue running, so as to let the user select another file name.
 764
 765     <para>
 766       Since 2.8
 767     </para>
 768
 769 <!-- ##### MACRO GTK_FILE_CHOOSER_ERROR ##### -->
 770     <para>
 771       Used to get the #GError quark for #GtkFileChooser errors.
 772     </para>
 773
 774
 775
 776 <!-- ##### ENUM GtkFileChooserError ##### -->
 777     <para>
 778       These identify the various errors that can occur while calling
 779       #GtkFileChooser functions.
 780     </para>
 781
 782 @GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist.
 783 @GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename.
 784 @GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS:
 785
 786 <!-- ##### FUNCTION gtk_file_chooser_error_quark ##### -->
 787 <para>
 788
 789 </para>
 790
 791 @Returns:
 792
 793
 794 <!-- ##### FUNCTION gtk_file_chooser_set_action ##### -->
 795 <para>
 796
 797 </para>
 798
 799 @chooser:
 800 @action:
 801
 802
 803 <!-- ##### FUNCTION gtk_file_chooser_get_action ##### -->
 804 <para>
 805
 806 </para>
 807
 808 @chooser:
 809 @Returns:
 810
 811
 812 <!-- ##### FUNCTION gtk_file_chooser_set_local_only ##### -->
 813 <para>
 814
 815 </para>
 816
 817 @chooser:
 818 @local_only:
 819 <!-- # Unused Parameters # -->
 820 @files_only:
 821
 822
 823 <!-- ##### FUNCTION gtk_file_chooser_get_local_only ##### -->
 824 <para>
 825
 826 </para>
 827
 828 @chooser:
 829 @Returns:
 830
 831
 832 <!-- ##### FUNCTION gtk_file_chooser_set_select_multiple ##### -->
 833 <para>
 834
 835 </para>
 836
 837 @chooser:
 838 @select_multiple:
 839
 840
 841 <!-- ##### FUNCTION gtk_file_chooser_get_select_multiple ##### -->
 842 <para>
 843
 844 </para>
 845
 846 @chooser:
 847 @Returns:
 848
 849
 850 <!-- ##### FUNCTION gtk_file_chooser_set_show_hidden ##### -->
 851 <para>
 852
 853 </para>
 854
 855 @chooser:
 856 @show_hidden:
 857
 858
 859 <!-- ##### FUNCTION gtk_file_chooser_get_show_hidden ##### -->
 860 <para>
 861
 862 </para>
 863
 864 @chooser:
 865 @Returns:
 866
 867
 868 <!-- ##### FUNCTION gtk_file_chooser_set_do_overwrite_confirmation ##### -->
 869 <para>
 870
 871 </para>
 872
 873 @chooser:
 874 @do_overwrite_confirmation:
 875
 876
 877 <!-- ##### FUNCTION gtk_file_chooser_get_do_overwrite_confirmation ##### -->
 878 <para>
 879
 880 </para>
 881
 882 @chooser:
 883 @Returns:
 884
 885
 886 <!-- ##### FUNCTION gtk_file_chooser_set_current_name ##### -->
 887 <para>
 888
 889 </para>
 890
 891 @chooser:
 892 @name:
 893
 894
 895 <!-- ##### FUNCTION gtk_file_chooser_get_filename ##### -->
 896 <para>
 897
 898 </para>
 899
 900 @chooser:
 901 @Returns:
 902
 903
 904 <!-- ##### FUNCTION gtk_file_chooser_set_filename ##### -->
 905 <para>
 906
 907 </para>
 908
 909 @chooser:
 910 @filename:
 911 @Returns:
 912
 913
 914 <!-- ##### FUNCTION gtk_file_chooser_select_filename ##### -->
 915 <para>
 916
 917 </para>
 918
 919 @chooser:
 920 @filename:
 921 @Returns:
 922
 923
 924 <!-- ##### FUNCTION gtk_file_chooser_unselect_filename ##### -->
 925 <para>
 926
 927 </para>
 928
 929 @chooser:
 930 @filename:
 931
 932
 933 <!-- ##### FUNCTION gtk_file_chooser_select_all ##### -->
 934 <para>
 935
 936 </para>
 937
 938 @chooser:
 939
 940
 941 <!-- ##### FUNCTION gtk_file_chooser_unselect_all ##### -->
 942 <para>
 943
 944 </para>
 945
 946 @chooser:
 947
 948
 949 <!-- ##### FUNCTION gtk_file_chooser_get_filenames ##### -->
 950 <para>
 951
 952 </para>
 953
 954 @chooser:
 955 @Returns:
 956
 957
 958 <!-- ##### FUNCTION gtk_file_chooser_set_current_folder ##### -->
 959 <para>
 960
 961 </para>
 962
 963 @chooser:
 964 @filename:
 965 @Returns:
 966
 967
 968 <!-- ##### FUNCTION gtk_file_chooser_get_current_folder ##### -->
 969 <para>
 970
 971 </para>
 972
 973 @chooser:
 974 @Returns:
 975
 976
 977 <!-- ##### FUNCTION gtk_file_chooser_get_uri ##### -->
 978 <para>
 979
 980 </para>
 981
 982 @chooser:
 983 @Returns:
 984
 985
 986 <!-- ##### FUNCTION gtk_file_chooser_set_uri ##### -->
 987 <para>
 988
 989 </para>
 990
 991 @chooser:
 992 @uri:
 993 @Returns:
 994
 995
 996 <!-- ##### FUNCTION gtk_file_chooser_select_uri ##### -->
 997 <para>
 998
 999 </para>
1000
1001 @chooser:
1002 @uri:
1003 @Returns:
1004
1005
1006 <!-- ##### FUNCTION gtk_file_chooser_unselect_uri ##### -->
1007 <para>
1008
1009 </para>
1010
1011 @chooser:
1012 @uri:
1013
1014
1015 <!-- ##### FUNCTION gtk_file_chooser_get_uris ##### -->
1016 <para>
1017
1018 </para>
1019
1020 @chooser:
1021 @Returns:
1022
1023
1024 <!-- ##### FUNCTION gtk_file_chooser_set_current_folder_uri ##### -->
1025 <para>
1026
1027 </para>
1028
1029 @chooser:
1030 @uri:
1031 @Returns:
1032
1033
1034 <!-- ##### FUNCTION gtk_file_chooser_get_current_folder_uri ##### -->
1035 <para>
1036
1037 </para>
1038
1039 @chooser:
1040 @Returns:
1041
1042
1043 <!-- ##### FUNCTION gtk_file_chooser_set_preview_widget ##### -->
1044 <para>
1045
1046 </para>
1047
1048 @chooser:
1049 @preview_widget:
1050
1051
1052 <!-- ##### FUNCTION gtk_file_chooser_get_preview_widget ##### -->
1053 <para>
1054
1055 </para>
1056
1057 @chooser:
1058 @Returns:
1059
1060
1061 <!-- ##### FUNCTION gtk_file_chooser_set_preview_widget_active ##### -->
1062 <para>
1063
1064 </para>
1065
1066 @chooser:
1067 @active:
1068
1069
1070 <!-- ##### FUNCTION gtk_file_chooser_get_preview_widget_active ##### -->
1071 <para>
1072
1073 </para>
1074
1075 @chooser:
1076 @Returns:
1077
1078
1079 <!-- ##### FUNCTION gtk_file_chooser_set_use_preview_label ##### -->
1080 <para>
1081
1082 </para>
1083
1084 @chooser:
1085 @use_label:
1086
1087
1088 <!-- ##### FUNCTION gtk_file_chooser_get_use_preview_label ##### -->
1089 <para>
1090
1091 </para>
1092
1093 @chooser:
1094 @Returns:
1095
1096
1097 <!-- ##### FUNCTION gtk_file_chooser_get_preview_filename ##### -->
1098 <para>
1099
1100 </para>
1101
1102 @chooser:
1103 @Returns:
1104 <!-- # Unused Parameters # -->
1105 @file_chooser:
1106
1107
1108 <!-- ##### FUNCTION gtk_file_chooser_get_preview_uri ##### -->
1109 <para>
1110
1111 </para>
1112
1113 @chooser:
1114 @Returns:
1115 <!-- # Unused Parameters # -->
1116 @file_chooser:
1117
1118
1119 <!-- ##### FUNCTION gtk_file_chooser_set_extra_widget ##### -->
1120 <para>
1121
1122 </para>
1123
1124 @chooser:
1125 @extra_widget:
1126
1127
1128 <!-- ##### FUNCTION gtk_file_chooser_get_extra_widget ##### -->
1129 <para>
1130
1131 </para>
1132
1133 @chooser:
1134 @Returns:
1135
1136
1137 <!-- ##### FUNCTION gtk_file_chooser_add_filter ##### -->
1138 <para>
1139
1140 </para>
1141
1142 @chooser:
1143 @filter:
1144
1145
1146 <!-- ##### FUNCTION gtk_file_chooser_remove_filter ##### -->
1147 <para>
1148
1149 </para>
1150
1151 @chooser:
1152 @filter:
1153
1154
1155 <!-- ##### FUNCTION gtk_file_chooser_list_filters ##### -->
1156 <para>
1157
1158 </para>
1159
1160 @chooser:
1161 @Returns:
1162
1163
1164 <!-- ##### FUNCTION gtk_file_chooser_set_filter ##### -->
1165 <para>
1166
1167 </para>
1168
1169 @chooser:
1170 @filter:
1171
1172
1173 <!-- ##### FUNCTION gtk_file_chooser_get_filter ##### -->
1174 <para>
1175
1176 </para>
1177
1178 @chooser:
1179 @Returns:
1180
1181
1182 <!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder ##### -->
1183 <para>
1184
1185 </para>
1186
1187 @chooser:
1188 @folder:
1189 @error:
1190 @Returns:
1191
1192
1193 <!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder ##### -->
1194 <para>
1195
1196 </para>
1197
1198 @chooser:
1199 @folder:
1200 @error:
1201 @Returns:
1202
1203
1204 <!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folders ##### -->
1205 <para>
1206
1207 </para>
1208
1209 @chooser:
1210 @Returns:
1211
1212
1213 <!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder_uri ##### -->
1214 <para>
1215
1216 </para>
1217
1218 @chooser:
1219 @uri:
1220 @error:
1221 @Returns:
1222 <!-- # Unused Parameters # -->
1223 @folder:
1224
1225
1226 <!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder_uri ##### -->
1227 <para>
1228
1229 </para>
1230
1231 @chooser:
1232 @uri:
1233 @error:
1234 @Returns:
1235 <!-- # Unused Parameters # -->
1236 @folder:
1237
1238
1239 <!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folder_uris ##### -->
1240 <para>
1241
1242 </para>
1243
1244 @chooser:
1245 @Returns:
1246
1247
1248
1249 <!--
1250 Local variables:
1251 mode: sgml
1252 sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
1253 End:
1254 -->
1255
1256