/* GTK - The GIMP Toolkit

 * gtkfilechooser.c: Abstract interface for file selector GUIs

 * Copyright (C) 2003, Red Hat, Inc.

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Lesser General Public

 * License as published by the Free Software Foundation; either

 * version 2 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public

 * License along with this library; if not, write to the

 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

 * Boston, MA 02111-1307, USA.

 */

#include "config.h"

#include "gtkfilechooser.h"

#include "gtkfilechooserprivate.h"

#include "gtkintl.h"

#include "gtktypebuiltins.h"

#include "gtkprivate.h"

#include "gtkmarshalers.h"

#include "gtkalias.h"

/**

 * SECTION:gtkfilechooser

 * @Short_description: File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog

 * @Title: GtkFileChooser

 * @See_also: #GtkFileChooserDialog, #GtkFileChooserWidget, #GtkFileChooserButton

 *

 * #GtkFileChooser is an interface that can be implemented by file

 * selection widgets.  In GTK+, the main objects that implement this

 * interface are #GtkFileChooserWidget, #GtkFileChooserDialog, and

 * #GtkFileChooserButton.  You do not need to write an object that

 * implements the #GtkFileChooser interface unless you are trying to

 * adapt an existing file selector to expose a standard programming

 * interface.

 *

 * #GtkFileChooser allows for shortcuts to various places in the filesystem.

 * In the default implementation these are displayed in the left pane. It

 * may be a bit confusing at first that these shortcuts come from various

 * sources and in various flavours, so lets explain the terminology here:

 * <variablelist>

 *    <varlistentry>

 *       <term>Bookmarks</term>

 *       <listitem>

 *          are created by the user, by dragging folders from the

 *          right pane to the left pane, or by using the "Add". Bookmarks

 *          can be renamed and deleted by the user.

 *       </listitem>

 *    </varlistentry>

 *    <varlistentry>

 *       <term>Shortcuts</term>

 *       <listitem>

 *          can be provided by the application or by the underlying filesystem

 *          abstraction (e.g. both the gnome-vfs and the Windows filesystems

 *          provide "Desktop" shortcuts). Shortcuts cannot be modified by the

 *          user.

 *       </listitem>

 *    </varlistentry>

 *    <varlistentry>

 *       <term>Volumes</term>

 *       <listitem>

 *          are provided by the underlying filesystem abstraction. They are

 *          the "roots" of the filesystem.

 *       </listitem>

 *    </varlistentry>

 * </variablelist>

 *

 * <refsect2 id="gtkfilechooser-encodings">

 * <title>File Names and Encodings</title>

 * When the user is finished selecting files in a

 * #GtkFileChooser, your program can get the selected names

 * either as filenames or as URIs.  For URIs, the normal escaping

 * rules are applied if the URI contains non-ASCII characters.

 * However, filenames are <emphasis>always</emphasis> returned in

 * the character set specified by the

 * <envar>G_FILENAME_ENCODING</envar> environment variable.

 * Please see the Glib documentation for more details about this

 * variable.

 * <note>

 *    This means that while you can pass the result of

 *    gtk_file_chooser_get_filename() to

 *    <function>open(2)</function> or

 *    <function>fopen(3)</function>, you may not be able to

 *    directly set it as the text of a #GtkLabel widget unless you

 *    convert it first to UTF-8, which all GTK+ widgets expect.

 *    You should use g_filename_to_utf8() to convert filenames

 *    into strings that can be passed to GTK+ widgets.

 * </note>

 * </refsect2>

 * <refsect2 id="gtkfilechooser-preview">

 * <title>Adding a Preview Widget</title>

 * <para>

 * You can add a custom preview widget to a file chooser and then

 * get notification about when the preview needs to be updated.

 * To install a preview widget, use

 * gtk_file_chooser_set_preview_widget().  Then, connect to the

 * #GtkFileChooser::update-preview signal to get notified when

 * you need to update the contents of the preview.

 * </para>

 * <para>

 * Your callback should use

 * gtk_file_chooser_get_preview_filename() to see what needs

 * previewing.  Once you have generated the preview for the

 * corresponding file, you must call

 * gtk_file_chooser_set_preview_widget_active() with a boolean

 * flag that indicates whether your callback could successfully

 * generate a preview.

 * </para>

 * <example id="example-gtkfilechooser-preview">

 * <title>Sample Usage</title>

 * <programlisting>

 * {

 *   GtkImage *preview;

 *

 *   ...

 *

 *   preview = gtk_image_new ();

 *

 *   gtk_file_chooser_set_preview_widget (my_file_chooser, preview);

 *   g_signal_connect (my_file_chooser, "update-preview",

 * 		    G_CALLBACK (update_preview_cb), preview);

 * }

 *

 * static void

 * update_preview_cb (GtkFileChooser *file_chooser, gpointer data)

 * {

 *   GtkWidget *preview;

 *   char *filename;

 *   GdkPixbuf *pixbuf;

 *   gboolean have_preview;

 *

 *   preview = GTK_WIDGET (data);

 *   filename = gtk_file_chooser_get_preview_filename (file_chooser);

 *

 *   pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);

 *   have_preview = (pixbuf != NULL);

 *   g_free (filename);

 *

 *   gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);

 *   if (pixbuf)

 *     g_object_unref (pixbuf);

 *

 *   gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);

 * }

 * </programlisting>

 * </example>

 * </refsect2>

 * <refsect2 id="gtkfilechooser-extra">

 * <title>Adding Extra Widgets</title>

 * <para>

 * You can add extra widgets to a file chooser to provide options

 * that are not present in the default design.  For example, you

 * can add a toggle button to give the user the option to open a

 * file in read-only mode.  You can use

 * gtk_file_chooser_set_extra_widget() to insert additional

 * widgets in a file chooser.

 * </para>

 * <example id="example-gtkfilechooser-extra">

 * <title>Sample Usage</title>

 * <programlisting>

 *

 *   GtkWidget *toggle;

 *

 *   ...

 *

 *   toggle = gtk_check_button_new_with_label ("Open file read-only");

 *   gtk_widget_show (toggle);

 *   gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);

 * }

 * </programlisting>

 * </example>

 * <note>

 *    If you want to set more than one extra widget in the file

 *    chooser, you can a container such as a #GtkVBox or a #GtkTable

 *    and include your widgets in it.  Then, set the container as

 *    the whole extra widget.

 * </note>

 * </refsect2>

 * <refsect2 id="gtkfilechooser-key-bindings">

 * <title>Key Bindings</title>

 * <para>

 * Internally, GTK+ implements a file chooser's graphical user

 * interface with the private

 * <classname>GtkFileChooserDefaultClass</classname>.  This

 * widget has several <link linkend="gtk-Bindings">key

 * bindings</link> and their associated signals.  This section

 * describes the available key binding signals.

 * </para>

 * <example id="gtkfilechooser-key-binding-example">

 * <title>GtkFileChooser key binding example</title>

 * <para>

 * The default keys that activate the key-binding signals in

 * <classname>GtkFileChooserDefaultClass</classname> are as

 * follows:

 * </para>

 * 	<informaltable>

 * 	  <tgroup cols="2">

 * 	    

 * 	      <row>

 * 		<entry>Signal name</entry>

 * 		<entry>Default key combinations</entry>

 * 	      </row>

 * 	      <row>

 * 		<entry>location-popup</entry>

 * 		<entry>

 * 		  <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> (empty path);

 * 		  <keycap>/</keycap> (path of "/")

 *                <footnote>

 * 		      Both the individual <keycap>/</keycap> key and the

 * 		      numeric keypad's "divide" key are supported.

 * 		  </footnote>;

 * 		  <keycap>~</keycap> (path of "~")

 * 		</entry>

 * 	      </row>

 * 	      <row>

 * 		<entry>up-folder</entry>

 * 		<entry>

 * 		  <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>;

 *                <keycombo><keycap>Alt</keycap><keycap>Shift</keycap><keycap>Up</keycap></keycombo>

 *                <footnote>

 * 		      Both the individual Up key and the numeric

 * 		      keypad's Up key are supported.

 * 		  </footnote>;

 * 		  <keycap>Backspace</keycap>

 * 		</entry>

 * 	      </row>

 * 	      <row>

 * 		<entry>down-folder</entry>

 * 		<entry>

 *                <keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>;

 *                <keycombo><keycap>Alt</keycap><keycap>Shift</keycap><keycap>Down</keycap></keycombo>

 *                <footnote>

 * 		      Both the individual Down key and the numeric

 * 		      keypad's Down key are supported.

 * 		  </footnote>

 *              </entry>

 * 	      </row>

 * 	      <row>

 * 		<entry>home-folder</entry>

 * 		<entry><keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo></entry>

 * 	      </row>

 * 	      <row>

 * 		<entry>desktop-folder</entry>

 * 		<entry><keycombo><keycap>Alt</keycap><keycap>D</keycap></keycombo></entry>

 * 	      </row>

 * 	      <row>

 * 		<entry>quick-bookmark</entry>

 * 		<entry><keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo> through <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo></entry>

 * 	      </row>

 * 	    

 * 	  </tgroup>

 * 	</informaltable>

 * <para>

 * You can change these defaults to something else.  For

 * example, to add a <keycap>Shift</keycap> modifier to a few

 * of the default bindings, you can include the following

 * fragment in your <filename>.gtkrc-3.0</filename> file:

 * </para>

 * <programlisting>

 * binding "my-own-gtkfilechooser-bindings" {

 * 	bind "<Alt><Shift>Up" {

 * 		"up-folder" ()

 * 	}

 * 	bind "<Alt><Shift>Down" {

 * 		"down-folder" ()

 * 	}

 * 	bind "<Alt><Shift>Home" {

 * 		"home-folder" ()

 * 	}

 * }

 *

 * class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"

 * </programlisting>

 * </example>

 * <refsect3 id="GtkFileChooserDefault-location-popup">

 * <title>The "GtkFileChooserDefault::location-popup" signal</title>

 * <programlisting>

 *    void user_function (GtkFileChooserDefault *chooser,

 *                        const char            *path,

 * <link linkend="gpointer">gpointer</link>      user_data);

 * </programlisting>

 * <para>

 * This is used to make the file chooser show a "Location"

 * dialog which the user can use to manually type the name of

 * the file he wishes to select.  The

 * <parameter>path</parameter> argument is a string that gets

 * put in the text entry for the file name.  By default this is bound to

 * <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>

 * with a <parameter>path</parameter> string of "" (the empty

 * string).  It is also bound to <keycap>/</keycap> with a

 * <parameter>path</parameter> string of "<literal>/</literal>"

 * (a slash):  this lets you type <keycap>/</keycap> and

 * immediately type a path name.  On Unix systems, this is bound to

 * <keycap>~</keycap> (tilde) with a <parameter>path</parameter> string

 * of "~" itself for access to home directories.

 * </para>

 * 	<variablelist role="params">

 * 	  <varlistentry>

 * 	    <term><parameter>chooser</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		the object which received the signal.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	  <varlistentry>

 * 	    <term><parameter>path</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		default contents for the text entry for the file name

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	  <varlistentry>

 * 	    <term><parameter>user_data</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		user data set when the signal handler was connected.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	</variablelist>

 * <note>

 *    You can create your own bindings for the

 *    #GtkFileChooserDefault::location-popup signal with custom

 *    <parameter>path</parameter> strings, and have a crude form

 *    of easily-to-type bookmarks.  For example, say you access

 *    the path <filename>/home/username/misc</filename> very

 *    frequently.  You could then create an <keycombo>

 *    <keycap>Alt</keycap> <keycap>M</keycap> </keycombo>

 *    shortcut by including the following in your

 *    <filename>.gtkrc-3.0</filename>:

 *    <programlisting>

 *    binding "misc-shortcut" {

 *       bind "<Alt>M" {

 *          "location-popup" ("/home/username/misc")

 * 	 }

 *    }

 *

 *    class "GtkFileChooserDefault" binding "misc-shortcut"

 *    </programlisting>

 * </note>

 * </refsect3>

 * <refsect3 id="GtkFileChooserDefault-up-folder">

 * <title>The "GtkFileChooserDefault::up-folder" signal</title>

 * <programlisting>

 *           void user_function (GtkFileChooserDefault *chooser,

 *                               <link linkend="gpointer">gpointer</link> user_data);

 * </programlisting>

 * <para>

 * This is used to make the file chooser go to the parent of

 * the current folder in the file hierarchy.  By default this

 * is bound to <keycap>Backspace</keycap> and

 * <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>

 * (the Up key in the numeric keypad also works).

 * </para>

 * 	<variablelist role="params">

 * 	  <varlistentry>

 * 	    <term><parameter>chooser</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		the object which received the signal.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	  <varlistentry>

 * 	    <term><parameter>user_data</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		user data set when the signal handler was connected.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	</variablelist>

 * </refsect3>

 * <refsect3 id="GtkFileChooserDefault-down-folder">

 * <title>The "GtkFileChooserDefault::down-folder" signal</title>

 * <programlisting>

 *           void user_function (GtkFileChooserDefault *chooser,

 *                               <link linkend="gpointer">gpointer</link> user_data);

 * </programlisting>

 * <para>

 * This is used to make the file chooser go to a child of the

 * current folder in the file hierarchy.  The subfolder that

 * will be used is displayed in the path bar widget of the file

 * chooser.  For example, if the path bar is showing

 * "/foo/<emphasis>bar/</emphasis>baz", then this will cause

 * the file chooser to switch to the "baz" subfolder.  By

 * default this is bound to

 * <keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>

 * (the Down key in the numeric keypad also works).

 * </para>

 * 	<variablelist role="params">

 * 	  <varlistentry>

 * 	    <term><parameter>chooser</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		the object which received the signal.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	  <varlistentry>

 * 	    <term><parameter>user_data</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		user data set when the signal handler was connected.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	</variablelist>

 * </refsect3>

 * <refsect3 id="GtkFileChooserDefault-home-folder">

 * <title>The "GtkFileChooserDefault::home-folder" signal</title>

 * <programlisting>

 *           void user_function (GtkFileChooserDefault *chooser,

 *                               <link linkend="gpointer">gpointer</link> user_data);

 * </programlisting>

 * <para>

 * This is used to make the file chooser show the user's home

 * folder in the file list.  By default this is bound to

 * <keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo>

 * (the Home key in the numeric keypad also works).

 * </para>

 * 	<variablelist role="params">

 * 	  <varlistentry>

 * 	    <term><parameter>chooser</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		the object which received the signal.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	  <varlistentry>

 * 	    <term><parameter>user_data</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		user data set when the signal handler was connected.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	</variablelist>

 * </refsect3>

 * <refsect3 id="GtkFileChooserDefault-desktop-folder">

 * <title>The "GtkFileChooserDefault::desktop-folder" signal</title>

 * <programlisting>

 *           void user_function (GtkFileChooserDefault *chooser,

 *                               <link linkend="gpointer">gpointer</link> user_data);

 * </programlisting>

 * <para>

 * This is used to make the file chooser show the user's Desktop

 * folder in the file list.  By default this is bound to

 * <keycombo><keycap>Alt</keycap><keycap>D</keycap></keycombo>.

 * </para>

 * 	<variablelist role="params">

 * 	  <varlistentry>

 * 	    <term><parameter>chooser</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		the object which received the signal.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	  <varlistentry>

 * 	    <term><parameter>user_data</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		user data set when the signal handler was connected.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	</variablelist>

 * </refsect3>

 * <refsect3 id="GtkFileChooserDefault-quick-bookmark">

 * <title>The "GtkFileChooserDefault::quick-bookmark" signal</title>

 * <programlisting>

 *           void user_function (GtkFileChooserDefault *chooser,

 *                               gint bookmark_index,

 *                               <link linkend="gpointer">gpointer</link> user_data);

 * </programlisting>

 * <para>

 * This is used to make the file chooser switch to the bookmark

 * specified in the <parameter>bookmark_index</parameter> parameter.

 * For example, if you have three bookmarks, you can pass 0, 1, 2 to

 * this signal to switch to each of them, respectively.  By default this is bound to

 * <keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo>,

 * <keycombo><keycap>Alt</keycap><keycap>2</keycap></keycombo>,

 * etc. until

 * <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo>.  Note

 * that in the default binding,

 * that <keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo> is

 * actually defined to switch to the bookmark at index 0, and so on

 * successively;

 * <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo> is

 * defined to switch to the bookmark at index 10.

 * </para>

 * 	<variablelist role="params">

 * 	  <varlistentry>

 * 	    <term><parameter>chooser</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		the object which received the signal.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	  <varlistentry>

 * 	    <term><parameter>bookmark_indes</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		index of the bookmark to switch to; the indices start at 0.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	  <varlistentry>

 * 	    <term><parameter>user_data</parameter> :</term>

 * 	    <listitem>

 * 	      <simpara>

 * 		user data set when the signal handler was connected.

 * 	      </simpara>

 * 	    </listitem>

 * 	  </varlistentry>

 * 	</variablelist>

 * </refsect3>

 * </refsect2>

 * <refsect2 id="gtkfilechooser-configuration-options">

 * <title>Configuration Options</title>

 * <para>

 * In GTK+ 2.x, the file chooser saves its state and configuration options in a

 * <filename>gtk-2.0/gtkfilechooser.ini</filename> file under the directory that

 * g_get_user_config_dir() returns.  (On Unix, this usually resolves to

 * <filename>$HOME/username/.config/gtk-2.0/gtkfilechooser.ini</filename>.)  While some of

 * the available options can be changed directly through the file chooser's user

 * interface, a couple are only editable by hand or by third-party tools (such

 * as 

 * url="https://wiki.gnome.org/action/show/Apps/GnomeTweakTool">gnome-tweak-tool</ulink>).

 * This section describes the available options.

 * </para>

 * <para>

 * This is a sample of the contents of a <filename>gtkfilechooser.ini</filename>

 * file.  Note that all the following options go under a

 * <literal>[Filechooser Settings]</literal> heading.

 * </para>

 * <programlisting>

 * [Filechooser Settings]

 * LocationMode=filename-entry

 * ShowHidden=false

 * ExpandFolders=true

 * GeometryX=570

 * GeometryY=273

 * GeometryWidth=780

 * GeometryHeight=585

 * ShowSizeColumn=true

 * SortColumn=name

 * SortOrder=ascending

 * StartupMode=recent

 * </programlisting>

 * <refsect3 id="gtkfilechooser-settings-location-mode">

 * <title>LocationMode key</title>

 * <para>

 * The <literal>LocationMode</literal> key controls whether the file chooser

 * shows just a path bar, or a visible entry for the filename as well, for the

 * benefit of typing-oriented users.  The possible string values for these modes

 * are <literal>path-bar</literal> and <literal>filename-entry</literal>,

 * respectively.

 * </para>

 * </refsect3>

 * <refsect3 id="gtkfilechooser-settings-show-hidden">

 * <title>ShowHidden key</title>

 * <para>

 * The <literal>ShowHidden</literal> key controls whether the file chooser shows

 * hidden files or not.  The value can be be <literal>true</literal> or

 * <literal>false</literal>.

 * </para>

 * </refsect3>

 * <refsect3 id="gtkfilechooser-settings-show-size-column">

 * <title>ShowSizeColumn key</title>

 * <para>

 * The <literal>ShowSize</literal> key controls whether the file chooser shows

 * a column with file sizes.  The value can be be <literal>true</literal> or

 * <literal>false</literal>.

 * </para>

 * </refsect3>

 * <refsect3 id="gtkfilechooser-settings-geometry-keys">

 * <title>Geometry keys</title>

 * <para>

 * The four keys <literal>GeometryX</literal>, <literal>GeometryY</literal>,

 * <literal>GeometryWidth</literal>, <literal>GeometryHeight</literal> save the

 * position and dimensions of the #GtkFileChooserDialog's window.

 * </para>

 * </refsect3>

 * <refsect3 id="gtkfilechooser-settings-sort-column">

 * <title>SortColumn key</title>

 * <para>

 * The <literal>SortColumn</literal> key can be one of the strings

 * <literal>name</literal>, <literal>modified</literal>, or

 * <literal>size</literal>.  It controls which of the columns in the file

 * chooser is used for sorting the list of files.

 * </para>

 * </refsect3>

 * <refsect3 id="gtkfilechooser-settings-sort-order">

 * <title>SortOrder key</title>

 * <para>

 * The <literal>SortOrder</literal> key can be one of the strings

 * <literal>ascending</literal> or <literal>descending</literal>.

 * </para>

 * </refsect3>

 * <refsect3 id="gtkfilechooser-settings-startup-mode">

 * <title>StartupMode key</title>

 * <para>

 * The <literal>StartupMode</literal> key controls whether the file chooser

 * starts up showing the list of recently-used files, or the contents of the

 * current working directory.  Respectively, the values can be

 * <literal>recent</literal> or <literal>cwd</literal>.

 * </para>

 * </refsect3>

 * </refsect2>

 */

static void gtk_file_chooser_class_init (gpointer g_iface);

GType

gtk_file_chooser_get_type (void)

{

  static GType file_chooser_type = 0;

  if (!file_chooser_type)

    {

      file_chooser_type = g_type_register_static_simple (G_TYPE_INTERFACE,

							 I_("GtkFileChooser"),

							 sizeof (GtkFileChooserIface),

							 (GClassInitFunc) gtk_file_chooser_class_init,

							 0, NULL, 0);

      g_type_interface_add_prerequisite (file_chooser_type, GTK_TYPE_WIDGET);

    }

  return file_chooser_type;

}

static gboolean

confirm_overwrite_accumulator (GSignalInvocationHint *ihint,

			       GValue                *return_accu,

			       const GValue          *handler_return,

			       gpointer               dummy)

{

  gboolean continue_emission;

  GtkFileChooserConfirmation conf;

  conf = g_value_get_enum (handler_return);

  g_value_set_enum (return_accu, conf);

  continue_emission = (conf == GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM);

  return continue_emission;

}

static void

gtk_file_chooser_class_init (gpointer g_iface)

{

  GType iface_type = G_TYPE_FROM_INTERFACE (g_iface);

  /**

   * GtkFileChooser::current-folder-changed

   * @chooser: the object which received the signal.

   *

   * This signal is emitted when the current folder in a #GtkFileChooser

   * changes.  This can happen due to the user performing some action that

   * changes folders, such as selecting a bookmark or visiting a folder on the

   * file list.  It can also happen as a result of calling a function to

   * explicitly change the current folder in a file chooser.

   *

   * Normally you do not need to connect to this signal, unless you need to keep

   * track of which folder a file chooser is showing.

   *

   * See also:  gtk_file_chooser_set_current_folder(),

   * gtk_file_chooser_get_current_folder(),

   * gtk_file_chooser_set_current_folder_uri(),

   * gtk_file_chooser_get_current_folder_uri().

   */

  g_signal_new (I_("current-folder-changed"),

		iface_type,

		G_SIGNAL_RUN_LAST,

		G_STRUCT_OFFSET (GtkFileChooserIface, current_folder_changed),

		NULL, NULL,

		g_cclosure_marshal_VOID__VOID,

		G_TYPE_NONE, 0);

  /**

   * GtkFileChooser::selection-changed

   * @chooser: the object which received the signal.

   *

   * This signal is emitted when there is a change in the set of selected files

   * in a #GtkFileChooser.  This can happen when the user modifies the selection

   * with the mouse or the keyboard, or when explicitly calling functions to

   * change the selection.

   *

   * Normally you do not need to connect to this signal, as it is easier to wait

   * for the file chooser to finish running, and then to get the list of

   * selected files using the functions mentioned below.

   *

   * See also: gtk_file_chooser_select_filename(),

   * gtk_file_chooser_unselect_filename(), gtk_file_chooser_get_filename(),

   * gtk_file_chooser_get_filenames(), gtk_file_chooser_select_uri(),

   * gtk_file_chooser_unselect_uri(), gtk_file_chooser_get_uri(),

   * gtk_file_chooser_get_uris().

   */

  g_signal_new (I_("selection-changed"),

		iface_type,

		G_SIGNAL_RUN_LAST,

		G_STRUCT_OFFSET (GtkFileChooserIface, selection_changed),

		NULL, NULL,

		g_cclosure_marshal_VOID__VOID,

		G_TYPE_NONE, 0);

  /**

   * GtkFileChooser::update-preview

   * @chooser: the object which received the signal.

   *

   * This signal is emitted when the preview in a file chooser should be

   * regenerated.  For example, this can happen when the currently selected file

   * changes.  You should use this signal if you want your file chooser to have

   * a preview widget.

   *

   * Once you have installed a preview widget with

   * gtk_file_chooser_set_preview_widget(), you should update it when this

   * signal is emitted.  You can use the functions

   * gtk_file_chooser_get_preview_filename() or

   * gtk_file_chooser_get_preview_uri() to get the name of the file to preview.

   * Your widget may not be able to preview all kinds of files; your callback

   * must call gtk_file_chooser_set_preview_widget_active() to inform the file

   * chooser about whether the preview was generated successfully or not.

   *

   * Please see the example code in <xref linkend="gtkfilechooser-preview"/>.

   *

   * See also: gtk_file_chooser_set_preview_widget(),

   * gtk_file_chooser_set_preview_widget_active(),

   * gtk_file_chooser_set_use_preview_label(),

   * gtk_file_chooser_get_preview_filename(),

   * gtk_file_chooser_get_preview_uri().

   */

  g_signal_new (I_("update-preview"),

		iface_type,

		G_SIGNAL_RUN_LAST,

		G_STRUCT_OFFSET (GtkFileChooserIface, update_preview),

		NULL, NULL,

		g_cclosure_marshal_VOID__VOID,

		G_TYPE_NONE, 0);

  /**

   * GtkFileChooser::file-activated

   * @chooser: the object which received the signal.

   *

   * This signal is emitted when the user "activates" a file in the file

   * chooser.  This can happen by double-clicking on a file in the file list, or

   * by pressing <keycap>Enter</keycap>.

   *

   * Normally you do not need to connect to this signal.  It is used internally

   * by #GtkFileChooserDialog to know when to activate the default button in the

   * dialog.

   *

   * See also: gtk_file_chooser_get_filename(),

   * gtk_file_chooser_get_filenames(), gtk_file_chooser_get_uri(),

   * gtk_file_chooser_get_uris().

   */

  g_signal_new (I_("file-activated"),

		iface_type,

		G_SIGNAL_RUN_LAST,

		G_STRUCT_OFFSET (GtkFileChooserIface, file_activated),

		NULL, NULL,

		g_cclosure_marshal_VOID__VOID,

		G_TYPE_NONE, 0);

  /**

   * GtkFileChooser::confirm-overwrite:

   * @chooser: the object which received the signal.

   *

   * This signal gets emitted whenever it is appropriate to present a

   * confirmation dialog when the user has selected a file name that

   * already exists.  The signal only gets emitted when the file

   * chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode.

   *

   * Most applications just need to turn on the

   * #GtkFileChooser:do-overwrite-confirmation property (or call the

   * gtk_file_chooser_set_do_overwrite_confirmation() function), and

   * they will automatically get a stock confirmation dialog.

   * Applications which need to customize this behavior should do

   * that, and also connect to the #GtkFileChooser::confirm-overwrite

   * signal.

   *

   * A signal handler for this signal must return a

   * #GtkFileChooserConfirmation value, which indicates the action to

   * take.  If the handler determines that the user wants to select a

   * different filename, it should return

   * %GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN.  If it determines

   * that the user is satisfied with his choice of file name, it

   * should return %GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME.

   * On the other hand, if it determines that the stock confirmation

   * dialog should be used, it should return

   * %GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM. The following example

   * illustrates this.

   * <example id="gtkfilechooser-confirmation">

   * <title>Custom confirmation</title>

   * <programlisting>

   * static GtkFileChooserConfirmation

   * confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data)

   * {

   *   char *uri;

   *

   *   uri = gtk_file_chooser_get_uri (chooser);

   *

   *   if (is_uri_read_only (uri))

   *     {

   *       if (user_wants_to_replace_read_only_file (uri))

   *         return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME;

   *       else

   *         return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN;

   *     } else

   *       return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; // fall back to the default dialog

   * }

   *

   * ...

   *

   * chooser = gtk_file_chooser_dialog_new (...);

   *

   * gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);

   * g_signal_connect (chooser, "confirm-overwrite",

   *                   G_CALLBACK (confirm_overwrite_callback), NULL);

   *

   * if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT)

   *         save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser));

   *

   * gtk_widget_destroy (chooser);

   * </programlisting>

   * </example>

   *

   * Returns: a #GtkFileChooserConfirmation value that indicates which

   *  action to take after emitting the signal.

   *

   * Since: 2.8

   */

  g_signal_new (I_("confirm-overwrite"),

		iface_type,

		G_SIGNAL_RUN_LAST,

		G_STRUCT_OFFSET (GtkFileChooserIface, confirm_overwrite),

		confirm_overwrite_accumulator, NULL,

		_gtk_marshal_ENUM__VOID,

		GTK_TYPE_FILE_CHOOSER_CONFIRMATION, 0);

  g_object_interface_install_property (g_iface,

				       g_param_spec_enum ("action",

							  P_("Action"),

							  P_("The type of operation that the file selector is performing"),

							  GTK_TYPE_FILE_CHOOSER_ACTION,

							  GTK_FILE_CHOOSER_ACTION_OPEN,

							  GTK_PARAM_READWRITE));

  g_object_interface_install_property (g_iface,

				       g_param_spec_string ("file-system-backend",

							    P_("File System Backend"),

							    P_("Name of file system backend to use"),

							    NULL, 

							    GTK_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));

  g_object_interface_install_property (g_iface,

				       g_param_spec_object ("filter",

							    P_("Filter"),

							    P_("The current filter for selecting which files are displayed"),

							    GTK_TYPE_FILE_FILTER,

							    GTK_PARAM_READWRITE));

  g_object_interface_install_property (g_iface,

				       g_param_spec_boolean ("local-only",

							     P_("Local Only"),

							     P_("Whether the selected file(s) should be limited to local file: URLs"),

							     TRUE,

							     GTK_PARAM_READWRITE));