<!-- ##### SECTION Long_Description ##### -->
<para>
#GtkFileChooser is an interface that can be implemented by file
- selection widgets. In GTK+, the main objects that implement
- this interface are #GtkFileChooserWidget and
- #GtkFileChooserDialog. 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.
+ 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.
</para>
+ <para>
+ #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 taht these shortcuts come from various
+ sources and in various flavours, so lets explain the terminology here:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Bookmarks</term>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Shortcuts</term>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Volumes</term>
+ <listitem><para>
+ are provided by the underlying filesystem abstraction. They are
+ the "roots" of the filesystem.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
<refsect2 id="gtkfilechooser-encodings">
<title>File Names and Encodings</title>
gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
if (pixbuf)
- gdk_pixbuf_unref (pixbuf);
+ gobject_unref (pixbuf);
gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
}
<tbody>
<row>
<entry>Signal name</entry>
- <entry>Key</entry>
+ <entry>Default key combinations</entry>
</row>
<row>
<entry>location-popup</entry>
- <entry><keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo></entry>
+ <entry>
+ <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> (empty path);
+ <keycap>/</keycap> (path of "/")<footnote>
+ <para>
+ Both the individual <keycap>/</keycap> key and the
+ numeric keypad's "divide" key are supported.
+ </para>
+ </footnote>;
+ <keycap>~</keycap> (path of "~")
+ </entry>
</row>
<row>
<entry>up-folder</entry>
- <entry><keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo></entry>
+ <entry>
+ <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo><footnote>
+ <para>
+ Both the individual Up key and the numeric
+ keypad's Up key are supported.
+ </para>
+ </footnote>
+ ;
+ <keycap>Backspace</keycap>
+ </entry>
</row>
<row>
<entry>down-folder</entry>
<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>
</tbody>
</tgroup>
</informaltable>
<para>
- To change these defaults to something else, you could
- include the following fragment in your
- <filename>.gtkrc-2.0</filename> file:
+ 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-2.0</filename> file:
</para>
<programlisting>
binding "my-own-gtkfilechooser-bindings" {
- bind "<Alt><Shift>l" {
- "location-popup" ()
- }
bind "<Alt><Shift>Up" {
"up-folder" ()
}
"down-folder" ()
}
bind "<Alt><Shift>Home" {
- "home-folder-folder" ()
+ "home-folder" ()
}
}
<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. By default this is bound to
- <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>.
+ 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">
</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>
</listitem>
</varlistentry>
</variablelist>
+
+ <tip>
+ <para>
+ You can create your own bindings for the
+ <symbol>location-popup</symbol> 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-2.0</filename>:
+ </para>
+
+ <programlisting>
+binding "misc-shortcut" {
+ bind "<Alt>M" {
+ "location-popup" ("/home/username/misc")
+ }
+}
+
+class "GtkFileChooserDefault" binding "misc-shortcut"
+ </programlisting>
+ </tip>
</refsect3>
<refsect3 id="GtkFileChooserDefault-up-folder">
<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
- <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>.
+ 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">
"/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>.
+ <keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>
+ (the Down key in the numeric keypad also works).
</para>
<variablelist role="params">
<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>.
+ <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>
</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>
<!-- ##### SECTION See_Also ##### -->
<para>
- #GtkFileChooserDialog, #GtkFileChooserWidget
+ #GtkFileChooserDialog, #GtkFileChooserWidget, #GtkFileChooserButton
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### STRUCT GtkFileChooser ##### -->
<para>
</para>
+<!-- ##### SIGNAL GtkFileChooser::confirm-overwrite ##### -->
+ <para>
+ 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.
+ </para>
+
+ <para>
+ Most applications just need to turn on the <link
+ linkend="GtkFileChooser--do-overwrite-confirmation">do-overwrite-confirmation</link>
+ 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 <symbol>confirm-overwrite</symbol>
+ signal.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <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>
+
+@filechooser: the object which received the signal.
+@Returns: #GtkFileChooserConfirmation value that indicates which
+ action to take after emitting the signal.
+
+ <para>
+ Since 2.8
+ </para>
+
<!-- ##### SIGNAL GtkFileChooser::current-folder-changed ##### -->
<para>
</para>
+<!-- ##### ARG GtkFileChooser:do-overwrite-confirmation ##### -->
+<para>
+
+</para>
+
<!-- ##### ARG GtkFileChooser:extra-widget ##### -->
<para>
new folder. The file chooser will let the user name an existing or
new folder.
+<!-- ##### ENUM GtkFileChooserConfirmation ##### -->
+ <para>
+ Used as a return value of handlers for the <link
+ linkend="GtkFileChooser-confirm-overwrite">confirm-overwrite</link>
+ signal of a <classname>GtkFileChooser</classname>. This value
+ determines whether the file chooser will present the stock
+ confirmation dialog, accept the user's choice of a filename, or
+ let the user choose another filename.
+ </para>
+
+@GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM: The file chooser will present
+ its stock dialog to confirm about overwriting an existing file.
+@GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME: The file chooser will
+ terminate and accept the user's choice of a file name.
+@GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN: The file chooser will
+ continue running, so as to let the user select another file name.
+
+ <para>
+ Since 2.8
+ </para>
+
<!-- ##### MACRO GTK_FILE_CHOOSER_ERROR ##### -->
<para>
Used to get the #GError quark for #GtkFileChooser errors.
@GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist.
@GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename.
-
-<!-- ##### FUNCTION gtk_file_chooser_error_quark ##### -->
-<para>
-
-</para>
-
-@Returns:
-
+@GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS:
<!-- ##### FUNCTION gtk_file_chooser_set_action ##### -->
<para>
@chooser:
@local_only:
-<!-- # Unused Parameters # -->
-@files_only:
<!-- ##### FUNCTION gtk_file_chooser_get_local_only ##### -->
@Returns:
+<!-- ##### FUNCTION gtk_file_chooser_set_do_overwrite_confirmation ##### -->
+<para>
+
+</para>
+
+@chooser:
+@do_overwrite_confirmation:
+
+
+<!-- ##### FUNCTION gtk_file_chooser_get_do_overwrite_confirmation ##### -->
+<para>
+
+</para>
+
+@chooser:
+@Returns:
+
+
<!-- ##### FUNCTION gtk_file_chooser_set_current_name ##### -->
<para>
@chooser:
@Returns:
-<!-- # Unused Parameters # -->
-@file_chooser:
<!-- ##### FUNCTION gtk_file_chooser_get_preview_uri ##### -->
@chooser:
@Returns:
-<!-- # Unused Parameters # -->
-@file_chooser:
<!-- ##### FUNCTION gtk_file_chooser_set_extra_widget ##### -->
@uri:
@error:
@Returns:
-<!-- # Unused Parameters # -->
-@folder:
<!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder_uri ##### -->
@uri:
@error:
@Returns:
-<!-- # Unused Parameters # -->
-@folder:
<!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folder_uris ##### -->
projects / ~andy / gtk / blobdiff