1
<refentry id="GtkFileChooser">
3
<refentrytitle role="top_of_page">GtkFileChooser</refentrytitle>
4
<manvolnum>3</manvolnum>
5
<refmiscinfo>GTK Library</refmiscinfo>
9
<refname>GtkFileChooser</refname>
10
<refpurpose>File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog</refpurpose>
11
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
14
<refsynopsisdiv role="synopsis">
15
<title role="synopsis.title">Synopsis</title>
19
#include <gtk/gtk.h>
22
<link linkend="GtkFileChooser-struct">GtkFileChooser</link>;
23
enum <link linkend="GtkFileChooserAction">GtkFileChooserAction</link>;
24
enum <link linkend="GtkFileChooserConfirmation">GtkFileChooserConfirmation</link>;
25
#define <link linkend="GTK-FILE-CHOOSER-ERROR:CAPS">GTK_FILE_CHOOSER_ERROR</link>
26
enum <link linkend="GtkFileChooserError">GtkFileChooserError</link>;
27
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-action">gtk_file_chooser_set_action</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
28
<link linkend="GtkFileChooserAction">GtkFileChooserAction</link> action);
29
<link linkend="GtkFileChooserAction">GtkFileChooserAction</link> <link linkend="gtk-file-chooser-get-action">gtk_file_chooser_get_action</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
30
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-local-only">gtk_file_chooser_set_local_only</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
31
<link linkend="gboolean">gboolean</link> local_only);
32
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-get-local-only">gtk_file_chooser_get_local_only</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
33
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-select-multiple">gtk_file_chooser_set_select_multiple</link>
34
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
35
<link linkend="gboolean">gboolean</link> select_multiple);
36
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-get-select-multiple">gtk_file_chooser_get_select_multiple</link>
37
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
38
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-show-hidden">gtk_file_chooser_set_show_hidden</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
39
<link linkend="gboolean">gboolean</link> show_hidden);
40
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-get-show-hidden">gtk_file_chooser_get_show_hidden</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
41
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-do-overwrite-confirmation">gtk_file_chooser_set_do_overwrite_confirmation</link>
42
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
43
<link linkend="gboolean">gboolean</link> do_overwrite_confirmation);
44
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-get-do-overwrite-confirmation">gtk_file_chooser_get_do_overwrite_confirmation</link>
45
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
46
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-current-name">gtk_file_chooser_set_current_name</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
47
const <link linkend="gchar">gchar</link> *name);
48
<link linkend="gchar">gchar</link>* <link linkend="gtk-file-chooser-get-filename">gtk_file_chooser_get_filename</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
49
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-set-filename">gtk_file_chooser_set_filename</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
50
const <link linkend="char">char</link> *filename);
51
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-select-filename">gtk_file_chooser_select_filename</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
52
const <link linkend="char">char</link> *filename);
53
<link linkend="void">void</link> <link linkend="gtk-file-chooser-unselect-filename">gtk_file_chooser_unselect_filename</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
54
const <link linkend="char">char</link> *filename);
55
<link linkend="void">void</link> <link linkend="gtk-file-chooser-select-all">gtk_file_chooser_select_all</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
56
<link linkend="void">void</link> <link linkend="gtk-file-chooser-unselect-all">gtk_file_chooser_unselect_all</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
57
<link linkend="GSList">GSList</link>* <link linkend="gtk-file-chooser-get-filenames">gtk_file_chooser_get_filenames</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
58
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-set-current-folder">gtk_file_chooser_set_current_folder</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
59
const <link linkend="gchar">gchar</link> *filename);
60
<link linkend="gchar">gchar</link>* <link linkend="gtk-file-chooser-get-current-folder">gtk_file_chooser_get_current_folder</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
61
<link linkend="gchar">gchar</link>* <link linkend="gtk-file-chooser-get-uri">gtk_file_chooser_get_uri</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
62
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-set-uri">gtk_file_chooser_set_uri</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
63
const <link linkend="char">char</link> *uri);
64
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-select-uri">gtk_file_chooser_select_uri</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
65
const <link linkend="char">char</link> *uri);
66
<link linkend="void">void</link> <link linkend="gtk-file-chooser-unselect-uri">gtk_file_chooser_unselect_uri</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
67
const <link linkend="char">char</link> *uri);
68
<link linkend="GSList">GSList</link>* <link linkend="gtk-file-chooser-get-uris">gtk_file_chooser_get_uris</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
69
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-set-current-folder-uri">gtk_file_chooser_set_current_folder_uri</link>
70
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
71
const <link linkend="gchar">gchar</link> *uri);
72
<link linkend="gchar">gchar</link>* <link linkend="gtk-file-chooser-get-current-folder-uri">gtk_file_chooser_get_current_folder_uri</link>
73
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
74
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-preview-widget">gtk_file_chooser_set_preview_widget</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
75
<link linkend="GtkWidget">GtkWidget</link> *preview_widget);
76
<link linkend="GtkWidget">GtkWidget</link>* <link linkend="gtk-file-chooser-get-preview-widget">gtk_file_chooser_get_preview_widget</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
77
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-preview-widget-active">gtk_file_chooser_set_preview_widget_active</link>
78
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
79
<link linkend="gboolean">gboolean</link> active);
80
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-get-preview-widget-active">gtk_file_chooser_get_preview_widget_active</link>
81
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
82
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-use-preview-label">gtk_file_chooser_set_use_preview_label</link>
83
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
84
<link linkend="gboolean">gboolean</link> use_label);
85
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-get-use-preview-label">gtk_file_chooser_get_use_preview_label</link>
86
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
87
<link linkend="char">char</link>* <link linkend="gtk-file-chooser-get-preview-filename">gtk_file_chooser_get_preview_filename</link>
88
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
89
<link linkend="char">char</link>* <link linkend="gtk-file-chooser-get-preview-uri">gtk_file_chooser_get_preview_uri</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
90
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-extra-widget">gtk_file_chooser_set_extra_widget</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
91
<link linkend="GtkWidget">GtkWidget</link> *extra_widget);
92
<link linkend="GtkWidget">GtkWidget</link>* <link linkend="gtk-file-chooser-get-extra-widget">gtk_file_chooser_get_extra_widget</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
93
<link linkend="void">void</link> <link linkend="gtk-file-chooser-add-filter">gtk_file_chooser_add_filter</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
94
<link linkend="GtkFileFilter">GtkFileFilter</link> *filter);
95
<link linkend="void">void</link> <link linkend="gtk-file-chooser-remove-filter">gtk_file_chooser_remove_filter</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
96
<link linkend="GtkFileFilter">GtkFileFilter</link> *filter);
97
<link linkend="GSList">GSList</link>* <link linkend="gtk-file-chooser-list-filters">gtk_file_chooser_list_filters</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
98
<link linkend="void">void</link> <link linkend="gtk-file-chooser-set-filter">gtk_file_chooser_set_filter</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
99
<link linkend="GtkFileFilter">GtkFileFilter</link> *filter);
100
<link linkend="GtkFileFilter">GtkFileFilter</link>* <link linkend="gtk-file-chooser-get-filter">gtk_file_chooser_get_filter</link> (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
101
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-add-shortcut-folder">gtk_file_chooser_add_shortcut_folder</link>
102
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
103
const <link linkend="char">char</link> *folder,
104
<link linkend="GError">GError</link> **error);
105
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-remove-shortcut-folder">gtk_file_chooser_remove_shortcut_folder</link>
106
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
107
const <link linkend="char">char</link> *folder,
108
<link linkend="GError">GError</link> **error);
109
<link linkend="GSList">GSList</link>* <link linkend="gtk-file-chooser-list-shortcut-folders">gtk_file_chooser_list_shortcut_folders</link>
110
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
111
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-add-shortcut-folder-uri">gtk_file_chooser_add_shortcut_folder_uri</link>
112
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
113
const <link linkend="char">char</link> *uri,
114
<link linkend="GError">GError</link> **error);
115
<link linkend="gboolean">gboolean</link> <link linkend="gtk-file-chooser-remove-shortcut-folder-uri">gtk_file_chooser_remove_shortcut_folder_uri</link>
116
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
117
const <link linkend="char">char</link> *uri,
118
<link linkend="GError">GError</link> **error);
119
<link linkend="GSList">GSList</link>* <link linkend="gtk-file-chooser-list-shortcut-folder-uris">gtk_file_chooser_list_shortcut_folder_uris</link>
120
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);
126
<refsect1 role="object_hierarchy">
127
<title role="object_hierarchy.title">Object Hierarchy</title>
130
<link linkend="GInterface">GInterface</link>
136
<refsect1 role="prerequisites">
137
<title role="prerequisites.title">Prerequisites</title>
139
GtkFileChooser requires
140
<link linkend="GtkWidget">GtkWidget</link>.</para>
146
<refsect1 role="implementations">
147
<title role="implementations.title">Known Implementations</title>
149
GtkFileChooser is implemented by
150
<link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>, <link linkend="GtkFileChooserButton">GtkFileChooserButton</link> and <link linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>.</para>
155
<refsect1 role="signal_proto">
156
<title role="signal_proto.title">Signals</title>
159
"<link linkend="GtkFileChooser-confirm-overwrite">confirm-overwrite</link>" : Run Last
160
"<link linkend="GtkFileChooser-current-folder-changed">current-folder-changed</link>" : Run Last
161
"<link linkend="GtkFileChooser-file-activated">file-activated</link>" : Run Last
162
"<link linkend="GtkFileChooser-selection-changed">selection-changed</link>" : Run Last
163
"<link linkend="GtkFileChooser-update-preview">update-preview</link>" : Run Last
168
<refsect1 role="desc">
169
<title role="desc.title">Description</title>
171
<link linkend="GtkFileChooser"><type>GtkFileChooser</type></link> is an interface that can be implemented by file
172
selection widgets. In GTK+, the main objects that implement this
173
interface are <link linkend="GtkFileChooserWidget"><type>GtkFileChooserWidget</type></link>, <link linkend="GtkFileChooserDialog"><type>GtkFileChooserDialog</type></link>, and
174
<link linkend="GtkFileChooserButton"><type>GtkFileChooserButton</type></link>. You do not need to write an object that
175
implements the <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link> interface unless you are trying to
176
adapt an existing file selector to expose a standard programming
181
<link linkend="GtkFileChooser"><type>GtkFileChooser</type></link> allows for shortcuts to various places in the filesystem.
182
In the default implementation these are displayed in the left pane. It
183
may be a bit confusing at first taht these shortcuts come from various
184
sources and in various flavours, so lets explain the terminology here:
188
<term>Bookmarks</term>
190
are created by the user, by dragging folders from the
191
right pane to the left pane, or by using the "Add". Bookmarks
192
can be renamed and deleted by the user.
196
<term>Shortcuts</term>
198
can be provided by the application or by the underlying filesystem
199
abstraction (e.g. both the gnome-vfs and the Windows filesystems
200
provide "Desktop" shortcuts). Shortcuts cannot be modified by the
207
are provided by the underlying filesystem abstraction. They are
208
the "roots" of the filesystem.
213
<refsect2 id="gtkfilechooser-encodings">
214
<title>File Names and Encodings</title>
217
When the user is finished selecting files in a
218
<link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>, your program can get the selected names
219
either as filenames or as URIs. For URIs, the normal escaping
220
rules are applied if the URI contains non-ASCII characters.
221
However, filenames are <emphasis>always</emphasis> returned in
222
the character set specified by the
223
<envar>G_FILENAME_ENCODING</envar> environment variable.
224
Please see the Glib documentation for more details about this
230
This means that while you can pass the result of
231
<link linkend="gtk-file-chooser-get-filename"><function>gtk_file_chooser_get_filename()</function></link> to
232
<function>open(2)</function> or
233
<function>fopen(3)</function>, you may not be able to
234
directly set it as the text of a <link linkend="GtkLabel"><type>GtkLabel</type></link> widget unless you
235
convert it first to UTF-8, which all GTK+ widgets expect.
236
You should use <link linkend="g-filename-to-utf8"><function>g_filename_to_utf8()</function></link> to convert filenames
237
into strings that can be passed to GTK+ widgets.
242
<refsect2 id="gtkfilechooser-preview">
243
<title>Adding a Preview Widget</title>
246
You can add a custom preview widget to a file chooser and then
247
get notification about when the preview needs to be updated.
248
To install a preview widget, use
249
<link linkend="gtk-file-chooser-set-preview-widget"><function>gtk_file_chooser_set_preview_widget()</function></link>. Then, connect to the
250
<link linkend="GtkFileChooser-update-preview"><type>GtkFileChooser::update-preview</type></link> signal to get notified when
251
you need to update the contents of the preview.
255
Your callback should use
256
<link linkend="gtk-file-chooser-get-preview-filename"><function>gtk_file_chooser_get_preview_filename()</function></link> to see what needs
257
previewing. Once you have generated the preview for the
258
corresponding file, you must call
259
<link linkend="gtk-file-chooser-set-preview-widget-active"><function>gtk_file_chooser_set_preview_widget_active()</function></link> with a boolean
260
flag that indicates whether your callback could successfully
264
<example id="example-gtkfilechooser-preview">
265
<title>Sample Usage</title>
273
preview = gtk_image_new (<!-- -->);
275
gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
276
g_signal_connect (my_file_chooser, "update-preview",
277
G_CALLBACK (update_preview_cb), preview);
281
update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
286
gboolean have_preview;
288
preview = GTK_WIDGET (data);
289
filename = gtk_file_chooser_get_preview_filename (file_chooser);
291
pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
292
have_preview = (pixbuf != NULL);
295
gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
297
gobject_unref (pixbuf);
299
gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
305
<refsect2 id="gtkfilechooser-extra">
306
<title>Adding Extra Widgets</title>
309
You can add extra widgets to a file chooser to provide options
310
that are not present in the default design. For example, you
311
can add a toggle button to give the user the option to open a
312
file in read-only mode. You can use
313
<link linkend="gtk-file-chooser-set-extra-widget"><function>gtk_file_chooser_set_extra_widget()</function></link> to insert additional
314
widgets in a file chooser.
317
<example id="example-gtkfilechooser-extra">
318
<title>Sample Usage</title>
326
toggle = gtk_check_button_new_with_label ("Open file read-only");
327
gtk_widget_show (toggle);
328
gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
335
If you want to set more than one extra widget in the file
336
chooser, you can a container such as a GtkVBox or a GtkTable
337
and include your widgets in it. Then, set the container as
338
the whole extra widget.
343
<refsect2 id="gtkfilechooser-key-bindings">
344
<title>Key Bindings</title>
347
Internally, GTK+ implements a file chooser's graphical user
348
interface with the private
349
<classname>GtkFileChooserDefaultClass</classname>. This
350
widget has several <link linkend="gtk-Bindings">key
351
bindings</link> and their associated signals. This section
352
describes the available key binding signals.
355
<example id="gtkfilechooser-key-binding-example">
356
<title>GtkFileChooser key binding example</title>
359
The default keys that activate the key-binding signals in
360
<classname>GtkFileChooserDefaultClass</classname> are as
368
<entry>Signal name</entry>
369
<entry>Default key combinations</entry>
372
<entry>location-popup</entry>
374
<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> (empty path);
375
<keycap>/</keycap> (path of "/")<footnote>
377
Both the individual <keycap>/</keycap> key and the
378
numeric keypad's "divide" key are supported.
381
<keycap>~</keycap> (path of "~")
385
<entry>up-folder</entry>
387
<keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo><footnote>
389
Both the individual Up key and the numeric
390
keypad's Up key are supported.
394
<keycap>Backspace</keycap>
398
<entry>down-folder</entry>
399
<entry><keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo></entry>
402
<entry>home-folder</entry>
403
<entry><keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo></entry>
406
<entry>desktop-folder</entry>
407
<entry><keycombo><keycap>Alt</keycap><keycap>D</keycap></keycombo></entry>
410
<entry>quick-bookmark</entry>
411
<entry><keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo> through <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo></entry>
418
You can change these defaults to something else. For
419
example, to add a <keycap>Shift</keycap> modifier to a few
420
of the default bindings, you can include the following
421
fragment in your <filename>.gtkrc-2.0</filename> file:
425
binding "my-own-gtkfilechooser-bindings" {
426
bind "<Alt><Shift>Up" {
429
bind "<Alt><Shift>Down" {
432
bind "<Alt><Shift>Home" {
437
class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"
441
<refsect3 id="GtkFileChooserDefault-location-popup">
442
<title>The "GtkFileChooserDefault::location-popup" signal</title>
445
void user_function (GtkFileChooserDefault *chooser,
447
<link linkend="gpointer">gpointer</link> user_data);
451
This is used to make the file chooser show a "Location"
452
dialog which the user can use to manually type the name of
453
the file he wishes to select. The
454
<parameter>path</parameter> argument is a string that gets
455
put in the text entry for the file name. By default this is bound to
456
<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
457
with a <parameter>path</parameter> string of "" (the empty
458
string). It is also bound to <keycap>/</keycap> with a
459
<parameter>path</parameter> string of "<literal>/</literal>"
460
(a slash): this lets you type <keycap>/</keycap> and
461
immediately type a path name. On Unix systems, this is bound to
462
<keycap>~</keycap> (tilde) with a <parameter>path</parameter> string
463
of "~" itself for access to home directories.
466
<variablelist role="params">
468
<term><parameter>chooser</parameter> :</term>
471
the object which received the signal.
476
<term><parameter>path</parameter> :</term>
479
default contents for the text entry for the file name
484
<term><parameter>user_data</parameter> :</term>
487
user data set when the signal handler was connected.
495
You can create your own bindings for the
496
<symbol>location-popup</symbol> signal with custom
497
<parameter>path</parameter> strings, and have a crude form
498
of easily-to-type bookmarks. For example, say you access
499
the path <filename>/home/username/misc</filename> very
500
frequently. You could then create an <keycombo>
501
<keycap>Alt</keycap> <keycap>M</keycap> </keycombo>
502
shortcut by including the following in your
503
<filename>.gtkrc-2.0</filename>:
507
binding "misc-shortcut" {
508
bind "<Alt>M" {
509
"location-popup" ("/home/username/misc")
513
class "GtkFileChooserDefault" binding "misc-shortcut"
518
<refsect3 id="GtkFileChooserDefault-up-folder">
519
<title>The "GtkFileChooserDefault::up-folder" signal</title>
522
void user_function (GtkFileChooserDefault *chooser,
523
<link linkend="gpointer">gpointer</link> user_data);
527
This is used to make the file chooser go to the parent of
528
the current folder in the file hierarchy. By default this
529
is bound to <keycap>Backspace</keycap> and
530
<keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>
531
(the Up key in the numeric keypad also works).
534
<variablelist role="params">
536
<term><parameter>chooser</parameter> :</term>
539
the object which received the signal.
544
<term><parameter>user_data</parameter> :</term>
547
user data set when the signal handler was connected.
554
<refsect3 id="GtkFileChooserDefault-down-folder">
555
<title>The "GtkFileChooserDefault::down-folder" signal</title>
558
void user_function (GtkFileChooserDefault *chooser,
559
<link linkend="gpointer">gpointer</link> user_data);
563
This is used to make the file chooser go to a child of the
564
current folder in the file hierarchy. The subfolder that
565
will be used is displayed in the path bar widget of the file
566
chooser. For example, if the path bar is showing
567
"/foo/<emphasis>bar/</emphasis>baz", then this will cause
568
the file chooser to switch to the "baz" subfolder. By
569
default this is bound to
570
<keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>
571
(the Down key in the numeric keypad also works).
574
<variablelist role="params">
576
<term><parameter>chooser</parameter> :</term>
579
the object which received the signal.
584
<term><parameter>user_data</parameter> :</term>
587
user data set when the signal handler was connected.
594
<refsect3 id="GtkFileChooserDefault-home-folder">
595
<title>The "GtkFileChooserDefault::home-folder" signal</title>
598
void user_function (GtkFileChooserDefault *chooser,
599
<link linkend="gpointer">gpointer</link> user_data);
603
This is used to make the file chooser show the user's home
604
folder in the file list. By default this is bound to
605
<keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo>
606
(the Home key in the numeric keypad also works).
609
<variablelist role="params">
611
<term><parameter>chooser</parameter> :</term>
614
the object which received the signal.
619
<term><parameter>user_data</parameter> :</term>
622
user data set when the signal handler was connected.
629
<refsect3 id="GtkFileChooserDefault-desktop-folder">
630
<title>The "GtkFileChooserDefault::desktop-folder" signal</title>
633
void user_function (GtkFileChooserDefault *chooser,
634
<link linkend="gpointer">gpointer</link> user_data);
638
This is used to make the file chooser show the user's Desktop
639
folder in the file list. By default this is bound to
640
<keycombo><keycap>Alt</keycap><keycap>D</keycap></keycombo>.
643
<variablelist role="params">
645
<term><parameter>chooser</parameter> :</term>
648
the object which received the signal.
653
<term><parameter>user_data</parameter> :</term>
656
user data set when the signal handler was connected.
663
<refsect3 id="GtkFileChooserDefault-quick-bookmark">
664
<title>The "GtkFileChooserDefault::quick-bookmark" signal</title>
667
void user_function (GtkFileChooserDefault *chooser,
669
<link linkend="gpointer">gpointer</link> user_data);
673
This is used to make the file chooser switch to the bookmark
674
specified in the <parameter>bookmark_index</parameter> parameter.
675
For example, if you have three bookmarks, you can pass 0, 1, 2 to
676
this signal to switch to each of them, respectively. By default this is bound to
677
<keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo>,
678
<keycombo><keycap>Alt</keycap><keycap>2</keycap></keycombo>,
680
<keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo>. Note
681
that in the default binding,
682
that <keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo> is
683
actually defined to switch to the bookmark at index 0, and so on
685
<keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo> is
686
defined to switch to the bookmark at index 10.
689
<variablelist role="params">
691
<term><parameter>chooser</parameter> :</term>
694
the object which received the signal.
699
<term><parameter>bookmark_indes</parameter> :</term>
702
index of the bookmark to switch to; the indices start at 0.
707
<term><parameter>user_data</parameter> :</term>
710
user data set when the signal handler was connected.
719
<refsect1 role="details">
720
<title role="details.title">Details</title>
722
<title><anchor id="GtkFileChooser-struct" role="struct"/>GtkFileChooser</title>
723
<indexterm><primary>GtkFileChooser</primary></indexterm><programlisting>typedef struct _GtkFileChooser GtkFileChooser;</programlisting>
728
<title><anchor id="GtkFileChooserAction" role="enum"/>enum GtkFileChooserAction</title>
729
<indexterm><primary>GtkFileChooserAction</primary></indexterm><programlisting>typedef enum
731
GTK_FILE_CHOOSER_ACTION_OPEN,
732
GTK_FILE_CHOOSER_ACTION_SAVE,
733
GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER,
734
GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER
735
} GtkFileChooserAction;
738
Describes whether a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link> is being used to open
739
existing files or to save to a possibly new file.
740
</para><variablelist role="enum">
742
<term><anchor id="GTK-FILE-CHOOSER-ACTION-OPEN:CAPS" role="constant"/><literal>GTK_FILE_CHOOSER_ACTION_OPEN</literal></term>
743
<listitem><simpara>Indicates open mode. The file chooser
744
will only let the user pick an existing file.
745
</simpara></listitem>
748
<term><anchor id="GTK-FILE-CHOOSER-ACTION-SAVE:CAPS" role="constant"/><literal>GTK_FILE_CHOOSER_ACTION_SAVE</literal></term>
749
<listitem><simpara>Indicates save mode. The file chooser
750
will let the user pick an existing file, or type in a new
752
</simpara></listitem>
755
<term><anchor id="GTK-FILE-CHOOSER-ACTION-SELECT-FOLDER:CAPS" role="constant"/><literal>GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER</literal></term>
756
<listitem><simpara>Indicates an Open mode for
757
selecting folders. The file chooser will let the user pick an
759
</simpara></listitem>
762
<term><anchor id="GTK-FILE-CHOOSER-ACTION-CREATE-FOLDER:CAPS" role="constant"/><literal>GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER</literal></term>
763
<listitem><simpara>Indicates a mode for creating a
764
new folder. The file chooser will let the user name an existing or
767
</simpara></listitem>
769
</variablelist></refsect2>
771
<title><anchor id="GtkFileChooserConfirmation" role="enum"/>enum GtkFileChooserConfirmation</title>
772
<indexterm><primary>GtkFileChooserConfirmation</primary></indexterm><programlisting>typedef enum
774
GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM,
775
GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME,
776
GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN
777
} GtkFileChooserConfirmation;
780
Used as a return value of handlers for the <link
781
linkend="GtkFileChooser-confirm-overwrite">confirm-overwrite</link>
782
signal of a <classname>GtkFileChooser</classname>. This value
783
determines whether the file chooser will present the stock
784
confirmation dialog, accept the user's choice of a filename, or
785
let the user choose another filename.
786
</para><variablelist role="enum">
788
<term><anchor id="GTK-FILE-CHOOSER-CONFIRMATION-CONFIRM:CAPS" role="constant"/><literal>GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM</literal></term>
789
<listitem><simpara>The file chooser will present
790
its stock dialog to confirm about overwriting an existing file.
791
</simpara></listitem>
794
<term><anchor id="GTK-FILE-CHOOSER-CONFIRMATION-ACCEPT-FILENAME:CAPS" role="constant"/><literal>GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME</literal></term>
795
<listitem><simpara>The file chooser will
796
terminate and accept the user's choice of a file name.
797
</simpara></listitem>
800
<term><anchor id="GTK-FILE-CHOOSER-CONFIRMATION-SELECT-AGAIN:CAPS" role="constant"/><literal>GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN</literal></term>
801
<listitem><simpara>The file chooser will
802
continue running, so as to let the user select another file name.
808
</simpara></listitem>
810
</variablelist></refsect2>
812
<title><anchor id="GTK-FILE-CHOOSER-ERROR:CAPS" role="macro"/>GTK_FILE_CHOOSER_ERROR</title>
813
<indexterm><primary>GTK_FILE_CHOOSER_ERROR</primary></indexterm><programlisting>#define GTK_FILE_CHOOSER_ERROR (gtk_file_chooser_error_quark ())
816
Used to get the <link linkend="GError"><type>GError</type></link> quark for <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link> errors.
819
<title><anchor id="GtkFileChooserError" role="enum"/>enum GtkFileChooserError</title>
820
<indexterm><primary>GtkFileChooserError</primary></indexterm><programlisting>typedef enum {
821
GTK_FILE_CHOOSER_ERROR_NONEXISTENT,
822
GTK_FILE_CHOOSER_ERROR_BAD_FILENAME,
823
GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS
824
} GtkFileChooserError;
827
These identify the various errors that can occur while calling
828
<link linkend="GtkFileChooser"><type>GtkFileChooser</type></link> functions.
829
</para><variablelist role="enum">
831
<term><anchor id="GTK-FILE-CHOOSER-ERROR-NONEXISTENT:CAPS" role="constant"/><literal>GTK_FILE_CHOOSER_ERROR_NONEXISTENT</literal></term>
832
<listitem><simpara>Indicates that a file does not exist.
833
</simpara></listitem>
836
<term><anchor id="GTK-FILE-CHOOSER-ERROR-BAD-FILENAME:CAPS" role="constant"/><literal>GTK_FILE_CHOOSER_ERROR_BAD_FILENAME</literal></term>
837
<listitem><simpara>Indicates a malformed filename.
838
</simpara></listitem>
841
<term><anchor id="GTK-FILE-CHOOSER-ERROR-ALREADY-EXISTS:CAPS" role="constant"/><literal>GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS</literal></term>
844
</simpara></listitem>
846
</variablelist></refsect2>
848
<title><anchor id="gtk-file-chooser-set-action" role="function" condition="since:2.4"/>gtk_file_chooser_set_action ()</title>
849
<indexterm role="2.4"><primary>gtk_file_chooser_set_action</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_action (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
850
<link linkend="GtkFileChooserAction">GtkFileChooserAction</link> action);</programlisting>
852
Sets the type of operation that the chooser is performing; the
853
user interface is adapted to suit the selected action. For example,
854
an option to create a new folder might be shown if the action is
855
<link linkend="GTK-FILE-CHOOSER-ACTION-SAVE:CAPS"><literal>GTK_FILE_CHOOSER_ACTION_SAVE</literal></link> but not if the action is
856
<link linkend="GTK-FILE-CHOOSER-ACTION-OPEN:CAPS"><literal>GTK_FILE_CHOOSER_ACTION_OPEN</literal></link>.</para>
859
</para><variablelist role="params">
860
<varlistentry><term><parameter>chooser</parameter> :</term>
861
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
862
</simpara></listitem></varlistentry>
863
<varlistentry><term><parameter>action</parameter> :</term>
864
<listitem><simpara> the action that the file selector is performing
865
</simpara></listitem></varlistentry>
866
</variablelist><para role="since">Since 2.4
869
<title><anchor id="gtk-file-chooser-get-action" role="function" condition="since:2.4"/>gtk_file_chooser_get_action ()</title>
870
<indexterm role="2.4"><primary>gtk_file_chooser_get_action</primary></indexterm><programlisting><link linkend="GtkFileChooserAction">GtkFileChooserAction</link> gtk_file_chooser_get_action (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
872
Gets the type of operation that the file chooser is performing; see
873
<link linkend="gtk-file-chooser-set-action"><function>gtk_file_chooser_set_action()</function></link>.</para>
876
</para><variablelist role="params">
877
<varlistentry><term><parameter>chooser</parameter> :</term>
878
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
879
</simpara></listitem></varlistentry>
880
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the action that the file selector is performing
882
</simpara></listitem></varlistentry>
883
</variablelist><para role="since">Since 2.4
886
<title><anchor id="gtk-file-chooser-set-local-only" role="function" condition="since:2.4"/>gtk_file_chooser_set_local_only ()</title>
887
<indexterm role="2.4"><primary>gtk_file_chooser_set_local_only</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_local_only (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
888
<link linkend="gboolean">gboolean</link> local_only);</programlisting>
890
Sets whether only local files can be selected in the
891
file selector. If <parameter>local_only</parameter> is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> (the default),
892
then the selected file are files are guaranteed to be
893
accessible through the operating systems native file
894
file system and therefore the application only
895
needs to worry about the filename functions in
896
<link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>, like <link linkend="gtk-file-chooser-get-filename"><function>gtk_file_chooser_get_filename()</function></link>,
897
rather than the URI functions like
898
<link linkend="gtk-file-chooser-get-uri"><function>gtk_file_chooser_get_uri()</function></link>,</para>
901
</para><variablelist role="params">
902
<varlistentry><term><parameter>chooser</parameter> :</term>
903
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
904
</simpara></listitem></varlistentry>
905
<varlistentry><term><parameter>local_only</parameter> :</term>
906
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if only local files can be selected
907
</simpara></listitem></varlistentry>
908
</variablelist><para role="since">Since 2.4
911
<title><anchor id="gtk-file-chooser-get-local-only" role="function" condition="since:2.4"/>gtk_file_chooser_get_local_only ()</title>
912
<indexterm role="2.4"><primary>gtk_file_chooser_get_local_only</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_get_local_only (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
914
Gets whether only local files can be selected in the
915
file selector. See <link linkend="gtk-file-chooser-set-local-only"><function>gtk_file_chooser_set_local_only()</function></link></para>
918
</para><variablelist role="params">
919
<varlistentry><term><parameter>chooser</parameter> :</term>
920
<listitem><simpara> a <link linkend="GtkFileChoosre"><type>GtkFileChoosre</type></link>
921
</simpara></listitem></varlistentry>
922
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if only local files can be selected.
924
</simpara></listitem></varlistentry>
925
</variablelist><para role="since">Since 2.4
928
<title><anchor id="gtk-file-chooser-set-select-multiple" role="function" condition="since:2.4"/>gtk_file_chooser_set_select_multiple ()</title>
929
<indexterm role="2.4"><primary>gtk_file_chooser_set_select_multiple</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_select_multiple
930
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
931
<link linkend="gboolean">gboolean</link> select_multiple);</programlisting>
933
Sets whether multiple files can be selected in the file selector. This is
934
only relevant if the action is set to be GTK_FILE_CHOOSER_ACTION_OPEN or
935
GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.</para>
938
</para><variablelist role="params">
939
<varlistentry><term><parameter>chooser</parameter> :</term>
940
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
941
</simpara></listitem></varlistentry>
942
<varlistentry><term><parameter>select_multiple</parameter> :</term>
943
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if multiple files can be selected.
944
</simpara></listitem></varlistentry>
945
</variablelist><para role="since">Since 2.4
948
<title><anchor id="gtk-file-chooser-get-select-multiple" role="function" condition="since:2.4"/>gtk_file_chooser_get_select_multiple ()</title>
949
<indexterm role="2.4"><primary>gtk_file_chooser_get_select_multiple</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_get_select_multiple
950
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
952
Gets whether multiple files can be selected in the file
953
selector. See <link linkend="gtk-file-chooser-set-select-multiple"><function>gtk_file_chooser_set_select_multiple()</function></link>.</para>
956
</para><variablelist role="params">
957
<varlistentry><term><parameter>chooser</parameter> :</term>
958
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
959
</simpara></listitem></varlistentry>
960
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if multiple files can be selected.
962
</simpara></listitem></varlistentry>
963
</variablelist><para role="since">Since 2.4
966
<title><anchor id="gtk-file-chooser-set-show-hidden" role="function" condition="since:2.6"/>gtk_file_chooser_set_show_hidden ()</title>
967
<indexterm role="2.6"><primary>gtk_file_chooser_set_show_hidden</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_show_hidden (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
968
<link linkend="gboolean">gboolean</link> show_hidden);</programlisting>
970
Sets whether hidden files and folders are displayed in the file selector.</para>
973
</para><variablelist role="params">
974
<varlistentry><term><parameter>chooser</parameter> :</term>
975
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
976
</simpara></listitem></varlistentry>
977
<varlistentry><term><parameter>show_hidden</parameter> :</term>
978
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if hidden files and folders should be displayed.
979
</simpara></listitem></varlistentry>
980
</variablelist><para role="since">Since 2.6
983
<title><anchor id="gtk-file-chooser-get-show-hidden" role="function" condition="since:2.6"/>gtk_file_chooser_get_show_hidden ()</title>
984
<indexterm role="2.6"><primary>gtk_file_chooser_get_show_hidden</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_get_show_hidden (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
986
Gets whether hidden files and folders are displayed in the file selector.
987
See <link linkend="gtk-file-chooser-set-show-hidden"><function>gtk_file_chooser_set_show_hidden()</function></link>.</para>
990
</para><variablelist role="params">
991
<varlistentry><term><parameter>chooser</parameter> :</term>
992
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
993
</simpara></listitem></varlistentry>
994
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if hidden files and folders are displayed.
996
</simpara></listitem></varlistentry>
997
</variablelist><para role="since">Since 2.6
1000
<title><anchor id="gtk-file-chooser-set-do-overwrite-confirmation" role="function" condition="since:2.8"/>gtk_file_chooser_set_do_overwrite_confirmation ()</title>
1001
<indexterm role="2.8"><primary>gtk_file_chooser_set_do_overwrite_confirmation</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_do_overwrite_confirmation
1002
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1003
<link linkend="gboolean">gboolean</link> do_overwrite_confirmation);</programlisting>
1005
Sets whether a file chooser in GTK_FILE_CHOOSER_ACTION_SAVE mode will present
1006
a confirmation dialog if the user types a file name that already exists. This
1007
is <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> by default.
1010
Regardless of this setting, the <parameter>chooser</parameter> will emit the "confirm-overwrite"
1011
signal when appropriate.
1014
If all you need is the stock confirmation dialog, set this property to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>.
1015
You can override the way confirmation is done by actually handling the
1016
"confirm-overwrite" signal; please refer to its documentation for the
1020
</para><variablelist role="params">
1021
<varlistentry><term><parameter>chooser</parameter> :</term>
1022
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1023
</simpara></listitem></varlistentry>
1024
<varlistentry><term><parameter>do_overwrite_confirmation</parameter> :</term>
1025
<listitem><simpara> whether to confirm overwriting in save mode
1026
</simpara></listitem></varlistentry>
1027
</variablelist><para role="since">Since 2.8
1030
<title><anchor id="gtk-file-chooser-get-do-overwrite-confirmation" role="function" condition="since:2.8"/>gtk_file_chooser_get_do_overwrite_confirmation ()</title>
1031
<indexterm role="2.8"><primary>gtk_file_chooser_get_do_overwrite_confirmation</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_get_do_overwrite_confirmation
1032
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1034
Queries whether a file chooser is set to confirm for overwriting when the user
1035
types a file name that already exists.</para>
1038
</para><variablelist role="params">
1039
<varlistentry><term><parameter>chooser</parameter> :</term>
1040
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1041
</simpara></listitem></varlistentry>
1042
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the file chooser will present a confirmation dialog;
1043
<link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
1045
</simpara></listitem></varlistentry>
1046
</variablelist><para role="since">Since 2.8
1049
<title><anchor id="gtk-file-chooser-set-current-name" role="function" condition="since:2.4"/>gtk_file_chooser_set_current_name ()</title>
1050
<indexterm role="2.4"><primary>gtk_file_chooser_set_current_name</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_current_name (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1051
const <link linkend="gchar">gchar</link> *name);</programlisting>
1053
Sets the current name in the file selector, as if entered
1054
by the user. Note that the name passed in here is a UTF-8
1055
string rather than a filename. This function is meant for
1056
such uses as a suggested name in a "Save As..." dialog.
1059
If you want to preselect a particular existing file, you should use
1060
<link linkend="gtk-file-chooser-set-filename"><function>gtk_file_chooser_set_filename()</function></link> or <link linkend="gtk-file-chooser-set-uri"><function>gtk_file_chooser_set_uri()</function></link> instead.
1061
Please see the documentation for those functions for an example of using
1062
<link linkend="gtk-file-chooser-set-current-name"><function>gtk_file_chooser_set_current_name()</function></link> as well.</para>
1065
</para><variablelist role="params">
1066
<varlistentry><term><parameter>chooser</parameter> :</term>
1067
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1068
</simpara></listitem></varlistentry>
1069
<varlistentry><term><parameter>name</parameter> :</term>
1070
<listitem><simpara> the filename to use, as a UTF-8 string
1071
</simpara></listitem></varlistentry>
1072
</variablelist><para role="since">Since 2.4
1075
<title><anchor id="gtk-file-chooser-get-filename" role="function" condition="since:2.4"/>gtk_file_chooser_get_filename ()</title>
1076
<indexterm role="2.4"><primary>gtk_file_chooser_get_filename</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* gtk_file_chooser_get_filename (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1078
Gets the filename for the currently selected file in
1079
the file selector. If multiple files are selected,
1080
one of the filenames will be returned at random.
1083
If the file chooser is in folder mode, this function returns the selected
1087
</para><variablelist role="params">
1088
<varlistentry><term><parameter>chooser</parameter> :</term>
1089
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1090
</simpara></listitem></varlistentry>
1091
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The currently selected filename, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1092
if no file is selected, or the selected file can't
1093
be represented with a local filename. Free with <link linkend="g-free"><function>g_free()</function></link>.
1095
</simpara></listitem></varlistentry>
1096
</variablelist><para role="since">Since 2.4
1099
<title><anchor id="gtk-file-chooser-set-filename" role="function" condition="since:2.4"/>gtk_file_chooser_set_filename ()</title>
1100
<indexterm role="2.4"><primary>gtk_file_chooser_set_filename</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_set_filename (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1101
const <link linkend="char">char</link> *filename);</programlisting>
1103
Sets <parameter>filename</parameter> as the current filename for the file chooser, by changing
1104
to the file's parent folder and actually selecting the file in list. If
1105
the <parameter>chooser</parameter> is in <link linkend="GTK-FILE-CHOOSER-ACTION-SAVE:CAPS"><type>GTK_FILE_CHOOSER_ACTION_SAVE</type></link> mode, the file's base name
1106
will also appear in the dialog's file name entry.
1109
If the file name isn't in the current folder of <parameter>chooser</parameter>, then the current
1110
folder of <parameter>chooser</parameter> will be changed to the folder containing <parameter>filename</parameter>. This
1111
is equivalent to a sequence of <link linkend="gtk-file-chooser-unselect-all"><function>gtk_file_chooser_unselect_all()</function></link> followed by
1112
<link linkend="gtk-file-chooser-select-filename"><function>gtk_file_chooser_select_filename()</function></link>.
1115
Note that the file must exist, or nothing will be done except
1116
for the directory change.
1119
If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog, you
1120
should use this function if you already have a file name to which the user may save; for example,
1121
when the user opens an existing file and then does <guimenuitem>File/Save As...</guimenuitem>
1122
on it. If you don't have a file name already — for example, if the user just created
1123
a new file and is saving it for the first time, do not call this function. Instead, use
1124
something similar to this:
1128
if (document_is_new)
1130
/<!-- -->* the user just created a new document *<!-- -->/
1131
gtk_file_chooser_set_current_folder (chooser, default_folder_for_saving);
1132
gtk_file_chooser_set_current_name (chooser, "Untitled document");
1136
/<!-- -->* the user edited an existing document *<!-- -->/
1137
gtk_file_chooser_set_filename (chooser, existing_filename);
1139
</programlisting></para>
1142
</para><variablelist role="params">
1143
<varlistentry><term><parameter>chooser</parameter> :</term>
1144
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1145
</simpara></listitem></varlistentry>
1146
<varlistentry><term><parameter>filename</parameter> :</term>
1147
<listitem><simpara> the filename to set as current
1148
</simpara></listitem></varlistentry>
1149
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if both the folder could be changed and the file was
1150
selected successfully, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
1152
</simpara></listitem></varlistentry>
1153
</variablelist><para role="since">Since 2.4
1156
<title><anchor id="gtk-file-chooser-select-filename" role="function" condition="since:2.4"/>gtk_file_chooser_select_filename ()</title>
1157
<indexterm role="2.4"><primary>gtk_file_chooser_select_filename</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_select_filename (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1158
const <link linkend="char">char</link> *filename);</programlisting>
1160
Selects a filename. If the file name isn't in the current
1161
folder of <parameter>chooser</parameter>, then the current folder of <parameter>chooser</parameter> will
1162
be changed to the folder containing <parameter>filename</parameter>.</para>
1165
</para><variablelist role="params">
1166
<varlistentry><term><parameter>chooser</parameter> :</term>
1167
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1168
</simpara></listitem></varlistentry>
1169
<varlistentry><term><parameter>filename</parameter> :</term>
1170
<listitem><simpara> the filename to select
1171
</simpara></listitem></varlistentry>
1172
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if both the folder could be changed and the file was
1173
selected successfully, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
1175
</simpara></listitem></varlistentry>
1176
</variablelist><para role="since">Since 2.4
1179
<title><anchor id="gtk-file-chooser-unselect-filename" role="function" condition="since:2.4"/>gtk_file_chooser_unselect_filename ()</title>
1180
<indexterm role="2.4"><primary>gtk_file_chooser_unselect_filename</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_unselect_filename (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1181
const <link linkend="char">char</link> *filename);</programlisting>
1183
Unselects a currently selected filename. If the filename
1184
is not in the current directory, does not exist, or
1185
is otherwise not currently selected, does nothing.</para>
1188
</para><variablelist role="params">
1189
<varlistentry><term><parameter>chooser</parameter> :</term>
1190
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1191
</simpara></listitem></varlistentry>
1192
<varlistentry><term><parameter>filename</parameter> :</term>
1193
<listitem><simpara> the filename to unselect
1194
</simpara></listitem></varlistentry>
1195
</variablelist><para role="since">Since 2.4
1198
<title><anchor id="gtk-file-chooser-select-all" role="function" condition="since:2.4"/>gtk_file_chooser_select_all ()</title>
1199
<indexterm role="2.4"><primary>gtk_file_chooser_select_all</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_select_all (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1201
Selects all the files in the current folder of a file chooser.</para>
1204
</para><variablelist role="params">
1205
<varlistentry><term><parameter>chooser</parameter> :</term>
1206
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1207
</simpara></listitem></varlistentry>
1208
</variablelist><para role="since">Since 2.4
1211
<title><anchor id="gtk-file-chooser-unselect-all" role="function" condition="since:2.4"/>gtk_file_chooser_unselect_all ()</title>
1212
<indexterm role="2.4"><primary>gtk_file_chooser_unselect_all</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_unselect_all (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1214
Unselects all the files in the current folder of a file chooser.</para>
1217
</para><variablelist role="params">
1218
<varlistentry><term><parameter>chooser</parameter> :</term>
1219
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1220
</simpara></listitem></varlistentry>
1221
</variablelist><para role="since">Since 2.4
1224
<title><anchor id="gtk-file-chooser-get-filenames" role="function" condition="since:2.4"/>gtk_file_chooser_get_filenames ()</title>
1225
<indexterm role="2.4"><primary>gtk_file_chooser_get_filenames</primary></indexterm><programlisting><link linkend="GSList">GSList</link>* gtk_file_chooser_get_filenames (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1227
Lists all the selected files and subfolders in the current folder of
1228
<parameter>chooser</parameter>. The returned names are full absolute paths. If files in the current
1229
folder cannot be represented as local filenames they will be ignored. (See
1230
<link linkend="gtk-file-chooser-get-uris"><function>gtk_file_chooser_get_uris()</function></link>)</para>
1233
</para><variablelist role="params">
1234
<varlistentry><term><parameter>chooser</parameter> :</term>
1235
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1236
</simpara></listitem></varlistentry>
1237
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GSList"><type>GSList</type></link> containing the filenames of all selected
1238
files and subfolders in the current folder. Free the returned list
1239
with <link linkend="g-slist-free"><function>g_slist_free()</function></link>, and the filenames with <link linkend="g-free"><function>g_free()</function></link>.
1241
</simpara></listitem></varlistentry>
1242
</variablelist><para role="since">Since 2.4
1245
<title><anchor id="gtk-file-chooser-set-current-folder" role="function" condition="since:2.4"/>gtk_file_chooser_set_current_folder ()</title>
1246
<indexterm role="2.4"><primary>gtk_file_chooser_set_current_folder</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_set_current_folder (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1247
const <link linkend="gchar">gchar</link> *filename);</programlisting>
1249
Sets the current folder for <parameter>chooser</parameter> from a local filename.
1250
The user will be shown the full contents of the current folder,
1251
plus user interface elements for navigating to other folders.</para>
1254
</para><variablelist role="params">
1255
<varlistentry><term><parameter>chooser</parameter> :</term>
1256
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1257
</simpara></listitem></varlistentry>
1258
<varlistentry><term><parameter>filename</parameter> :</term>
1259
<listitem><simpara> the full path of the new current folder
1260
</simpara></listitem></varlistentry>
1261
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the folder could be changed successfully, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
1264
</simpara></listitem></varlistentry>
1265
</variablelist><para role="since">Since 2.4
1268
<title><anchor id="gtk-file-chooser-get-current-folder" role="function" condition="since:2.4"/>gtk_file_chooser_get_current_folder ()</title>
1269
<indexterm role="2.4"><primary>gtk_file_chooser_get_current_folder</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* gtk_file_chooser_get_current_folder (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1271
Gets the current folder of <parameter>chooser</parameter> as a local filename.
1272
See <link linkend="gtk-file-chooser-set-current-folder"><function>gtk_file_chooser_set_current_folder()</function></link>.
1275
Note that this is the folder that the file chooser is currently displaying
1276
(e.g. "/home/username/Documents"), which is <emphasis>not the same</emphasis>
1277
as the currently-selected folder if the chooser is in
1278
<link linkend="GTK-FILE-CHOOSER-SELECT-FOLDER:CAPS"><type>GTK_FILE_CHOOSER_SELECT_FOLDER</type></link> mode
1279
(e.g. "/home/username/Documents/selected-folder/". To get the
1280
currently-selected folder in that mode, use <link linkend="gtk-file-chooser-get-uri"><function>gtk_file_chooser_get_uri()</function></link> as the
1281
usual way to get the selection.</para>
1284
</para><variablelist role="params">
1285
<varlistentry><term><parameter>chooser</parameter> :</term>
1286
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1287
</simpara></listitem></varlistentry>
1288
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the full path of the current folder, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the current
1289
path cannot be represented as a local filename. Free with <link linkend="g-free"><function>g_free()</function></link>. This
1290
function will also return <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the file chooser was unable to load the
1291
last folder that was requested from it; for example, as would be for calling
1292
<link linkend="gtk-file-chooser-set-current-folder"><function>gtk_file_chooser_set_current_folder()</function></link> on a nonexistent folder.
1294
</simpara></listitem></varlistentry>
1295
</variablelist><para role="since">Since 2.4
1298
<title><anchor id="gtk-file-chooser-get-uri" role="function" condition="since:2.4"/>gtk_file_chooser_get_uri ()</title>
1299
<indexterm role="2.4"><primary>gtk_file_chooser_get_uri</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* gtk_file_chooser_get_uri (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1301
Gets the URI for the currently selected file in
1302
the file selector. If multiple files are selected,
1303
one of the filenames will be returned at random.
1306
If the file chooser is in folder mode, this function returns the selected
1310
</para><variablelist role="params">
1311
<varlistentry><term><parameter>chooser</parameter> :</term>
1312
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1313
</simpara></listitem></varlistentry>
1314
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The currently selected URI, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1315
if no file is selected. Free with <link linkend="g-free"><function>g_free()</function></link>
1317
</simpara></listitem></varlistentry>
1318
</variablelist><para role="since">Since 2.4
1321
<title><anchor id="gtk-file-chooser-set-uri" role="function" condition="since:2.4"/>gtk_file_chooser_set_uri ()</title>
1322
<indexterm role="2.4"><primary>gtk_file_chooser_set_uri</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_set_uri (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1323
const <link linkend="char">char</link> *uri);</programlisting>
1325
Sets the file referred to by <parameter>uri</parameter> as the current file for the file chooser,
1326
by changing to the URI's parent folder and actually selecting the URI in the
1327
list. If the <parameter>chooser</parameter> is <link linkend="GTK-FILE-CHOOSER-ACTION-SAVE:CAPS"><type>GTK_FILE_CHOOSER_ACTION_SAVE</type></link> mode, the URI's base
1328
name will also appear in the dialog's file name entry.
1331
If the URI isn't in the current folder of <parameter>chooser</parameter>, then the current folder
1332
of <parameter>chooser</parameter> will be changed to the folder containing <parameter>uri</parameter>. This is equivalent
1333
to a sequence of <link linkend="gtk-file-chooser-unselect-all"><function>gtk_file_chooser_unselect_all()</function></link> followed by
1334
<link linkend="gtk-file-chooser-select-uri"><function>gtk_file_chooser_select_uri()</function></link>.
1337
Note that the URI must exist, or nothing will be done except
1338
for the directory change.
1339
If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog, you
1340
should use this function if you already have a file name to which the user may save; for example,
1341
when the user opens an existing file and then does <guimenuitem>File/Save As...</guimenuitem>
1342
on it. If you don't have a file name already — for example, if the user just created
1343
a new file and is saving it for the first time, do not call this function. Instead, use
1344
something similar to this:
1348
if (document_is_new)
1350
/<!-- -->* the user just created a new document *<!-- -->/
1351
gtk_file_chooser_set_current_folder_uri (chooser, default_folder_for_saving);
1352
gtk_file_chooser_set_current_name (chooser, "Untitled document");
1356
/<!-- -->* the user edited an existing document *<!-- -->/
1357
gtk_file_chooser_set_uri (chooser, existing_uri);
1359
</programlisting></para>
1362
</para><variablelist role="params">
1363
<varlistentry><term><parameter>chooser</parameter> :</term>
1364
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1365
</simpara></listitem></varlistentry>
1366
<varlistentry><term><parameter>uri</parameter> :</term>
1367
<listitem><simpara> the URI to set as current
1368
</simpara></listitem></varlistentry>
1369
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if both the folder could be changed and the URI was
1370
selected successfully, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
1372
</simpara></listitem></varlistentry>
1373
</variablelist><para role="since">Since 2.4
1376
<title><anchor id="gtk-file-chooser-select-uri" role="function" condition="since:2.4"/>gtk_file_chooser_select_uri ()</title>
1377
<indexterm role="2.4"><primary>gtk_file_chooser_select_uri</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_select_uri (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1378
const <link linkend="char">char</link> *uri);</programlisting>
1380
Selects the file to by <parameter>uri</parameter>. If the URI doesn't refer to a
1381
file in the current folder of <parameter>chooser</parameter>, then the current folder of
1382
<parameter>chooser</parameter> will be changed to the folder containing <parameter>filename</parameter>.</para>
1385
</para><variablelist role="params">
1386
<varlistentry><term><parameter>chooser</parameter> :</term>
1387
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1388
</simpara></listitem></varlistentry>
1389
<varlistentry><term><parameter>uri</parameter> :</term>
1390
<listitem><simpara> the URI to select
1391
</simpara></listitem></varlistentry>
1392
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if both the folder could be changed and the URI was
1393
selected successfully, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
1395
</simpara></listitem></varlistentry>
1396
</variablelist><para role="since">Since 2.4
1399
<title><anchor id="gtk-file-chooser-unselect-uri" role="function" condition="since:2.4"/>gtk_file_chooser_unselect_uri ()</title>
1400
<indexterm role="2.4"><primary>gtk_file_chooser_unselect_uri</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_unselect_uri (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1401
const <link linkend="char">char</link> *uri);</programlisting>
1403
Unselects the file referred to by <parameter>uri</parameter>. If the file
1404
is not in the current directory, does not exist, or
1405
is otherwise not currently selected, does nothing.</para>
1408
</para><variablelist role="params">
1409
<varlistentry><term><parameter>chooser</parameter> :</term>
1410
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1411
</simpara></listitem></varlistentry>
1412
<varlistentry><term><parameter>uri</parameter> :</term>
1413
<listitem><simpara> the URI to unselect
1414
</simpara></listitem></varlistentry>
1415
</variablelist><para role="since">Since 2.4
1418
<title><anchor id="gtk-file-chooser-get-uris" role="function" condition="since:2.4"/>gtk_file_chooser_get_uris ()</title>
1419
<indexterm role="2.4"><primary>gtk_file_chooser_get_uris</primary></indexterm><programlisting><link linkend="GSList">GSList</link>* gtk_file_chooser_get_uris (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1421
Lists all the selected files and subfolders in the current folder of
1422
<parameter>chooser</parameter>. The returned names are full absolute URIs.</para>
1425
</para><variablelist role="params">
1426
<varlistentry><term><parameter>chooser</parameter> :</term>
1427
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1428
</simpara></listitem></varlistentry>
1429
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GSList"><type>GSList</type></link> containing the URIs of all selected
1430
files and subfolders in the current folder. Free the returned list
1431
with <link linkend="g-slist-free"><function>g_slist_free()</function></link>, and the filenames with <link linkend="g-free"><function>g_free()</function></link>.
1433
</simpara></listitem></varlistentry>
1434
</variablelist><para role="since">Since 2.4
1437
<title><anchor id="gtk-file-chooser-set-current-folder-uri" role="function" condition="since:2.4"/>gtk_file_chooser_set_current_folder_uri ()</title>
1438
<indexterm role="2.4"><primary>gtk_file_chooser_set_current_folder_uri</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_set_current_folder_uri
1439
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1440
const <link linkend="gchar">gchar</link> *uri);</programlisting>
1442
Sets the current folder for <parameter>chooser</parameter> from an URI.
1443
The user will be shown the full contents of the current folder,
1444
plus user interface elements for navigating to other folders.</para>
1447
</para><variablelist role="params">
1448
<varlistentry><term><parameter>chooser</parameter> :</term>
1449
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1450
</simpara></listitem></varlistentry>
1451
<varlistentry><term><parameter>uri</parameter> :</term>
1452
<listitem><simpara> the URI for the new current folder
1453
</simpara></listitem></varlistentry>
1454
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the folder could be changed successfully, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
1457
</simpara></listitem></varlistentry>
1458
</variablelist><para role="since">Since 2.4
1461
<title><anchor id="gtk-file-chooser-get-current-folder-uri" role="function" condition="since:2.4"/>gtk_file_chooser_get_current_folder_uri ()</title>
1462
<indexterm role="2.4"><primary>gtk_file_chooser_get_current_folder_uri</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* gtk_file_chooser_get_current_folder_uri
1463
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1465
Gets the current folder of <parameter>chooser</parameter> as an URI.
1466
See <link linkend="gtk-file-chooser-set-current-folder-uri"><function>gtk_file_chooser_set_current_folder_uri()</function></link>.
1469
Note that this is the folder that the file chooser is currently displaying
1470
(e.g. "file:///home/username/Documents"), which is <emphasis>not the same</emphasis>
1471
as the currently-selected folder if the chooser is in
1472
<link linkend="GTK-FILE-CHOOSER-SELECT-FOLDER:CAPS"><type>GTK_FILE_CHOOSER_SELECT_FOLDER</type></link> mode
1473
(e.g. "file:///home/username/Documents/selected-folder/". To get the
1474
currently-selected folder in that mode, use <link linkend="gtk-file-chooser-get-uri"><function>gtk_file_chooser_get_uri()</function></link> as the
1475
usual way to get the selection.</para>
1478
</para><variablelist role="params">
1479
<varlistentry><term><parameter>chooser</parameter> :</term>
1480
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1481
</simpara></listitem></varlistentry>
1482
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the URI for the current folder. Free with <link linkend="g-free"><function>g_free()</function></link>. This
1483
function will also return <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the file chooser was unable to load the
1484
last folder that was requested from it; for example, as would be for calling
1485
<link linkend="gtk-file-chooser-set-current-folder-uri"><function>gtk_file_chooser_set_current_folder_uri()</function></link> on a nonexistent folder.
1487
</simpara></listitem></varlistentry>
1488
</variablelist><para role="since">Since 2.4
1491
<title><anchor id="gtk-file-chooser-set-preview-widget" role="function" condition="since:2.4"/>gtk_file_chooser_set_preview_widget ()</title>
1492
<indexterm role="2.4"><primary>gtk_file_chooser_set_preview_widget</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_preview_widget (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1493
<link linkend="GtkWidget">GtkWidget</link> *preview_widget);</programlisting>
1495
Sets an application-supplied widget to use to display a custom preview
1496
of the currently selected file. To implement a preview, after setting the
1497
preview widget, you connect to the ::update-preview
1498
signal, and call <link linkend="gtk-file-chooser-get-preview-filename"><function>gtk_file_chooser_get_preview_filename()</function></link> or
1499
<link linkend="gtk-file-chooser-get-preview-uri"><function>gtk_file_chooser_get_preview_uri()</function></link> on each change. If you can
1500
display a preview of the new file, update your widget and
1501
set the preview active using <link linkend="gtk-file-chooser-set-preview-widget-active"><function>gtk_file_chooser_set_preview_widget_active()</function></link>.
1502
Otherwise, set the preview inactive.
1505
When there is no application-supplied preview widget, or the
1506
application-supplied preview widget is not active, the file chooser
1507
may display an internally generated preview of the current file or
1508
it may display no preview at all.</para>
1511
</para><variablelist role="params">
1512
<varlistentry><term><parameter>chooser</parameter> :</term>
1513
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1514
</simpara></listitem></varlistentry>
1515
<varlistentry><term><parameter>preview_widget</parameter> :</term>
1516
<listitem><simpara> widget for displaying preview.
1517
</simpara></listitem></varlistentry>
1518
</variablelist><para role="since">Since 2.4
1521
<title><anchor id="gtk-file-chooser-get-preview-widget" role="function" condition="since:2.4"/>gtk_file_chooser_get_preview_widget ()</title>
1522
<indexterm role="2.4"><primary>gtk_file_chooser_get_preview_widget</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>* gtk_file_chooser_get_preview_widget (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1524
Gets the current preview widget; see
1525
<link linkend="gtk-file-chooser-set-preview-widget"><function>gtk_file_chooser_set_preview_widget()</function></link>.</para>
1528
</para><variablelist role="params">
1529
<varlistentry><term><parameter>chooser</parameter> :</term>
1530
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1531
</simpara></listitem></varlistentry>
1532
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current preview widget, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1534
</simpara></listitem></varlistentry>
1535
</variablelist><para role="since">Since 2.4
1538
<title><anchor id="gtk-file-chooser-set-preview-widget-active" role="function" condition="since:2.4"/>gtk_file_chooser_set_preview_widget_active ()</title>
1539
<indexterm role="2.4"><primary>gtk_file_chooser_set_preview_widget_active</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_preview_widget_active
1540
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1541
<link linkend="gboolean">gboolean</link> active);</programlisting>
1543
Sets whether the preview widget set by
1544
<link linkend="gtk-file-chooser-set-preview-widget"><function>gtk_file_chooser_set_preview_widget()</function></link> should be shown for the
1545
current filename. When <parameter>active</parameter> is set to false, the file chooser
1546
may display an internally generated preview of the current file
1547
or it may display no preview at all. See
1548
<link linkend="gtk-file-chooser-set-preview-widget"><function>gtk_file_chooser_set_preview_widget()</function></link> for more details.</para>
1551
</para><variablelist role="params">
1552
<varlistentry><term><parameter>chooser</parameter> :</term>
1553
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1554
</simpara></listitem></varlistentry>
1555
<varlistentry><term><parameter>active</parameter> :</term>
1556
<listitem><simpara> whether to display the user-specified preview widget
1557
</simpara></listitem></varlistentry>
1558
</variablelist><para role="since">Since 2.4
1561
<title><anchor id="gtk-file-chooser-get-preview-widget-active" role="function" condition="since:2.4"/>gtk_file_chooser_get_preview_widget_active ()</title>
1562
<indexterm role="2.4"><primary>gtk_file_chooser_get_preview_widget_active</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_get_preview_widget_active
1563
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1565
Gets whether the preview widget set by <link linkend="gtk-file-chooser-set-preview-widget"><function>gtk_file_chooser_set_preview_widget()</function></link>
1566
should be shown for the current filename. See
1567
<link linkend="gtk-file-chooser-set-preview-widget-active"><function>gtk_file_chooser_set_preview_widget_active()</function></link>.</para>
1570
</para><variablelist role="params">
1571
<varlistentry><term><parameter>chooser</parameter> :</term>
1572
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1573
</simpara></listitem></varlistentry>
1574
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the preview widget is active for the current filename.
1576
</simpara></listitem></varlistentry>
1577
</variablelist><para role="since">Since 2.4
1580
<title><anchor id="gtk-file-chooser-set-use-preview-label" role="function" condition="since:2.4"/>gtk_file_chooser_set_use_preview_label ()</title>
1581
<indexterm role="2.4"><primary>gtk_file_chooser_set_use_preview_label</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_use_preview_label
1582
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1583
<link linkend="gboolean">gboolean</link> use_label);</programlisting>
1585
Sets whether the file chooser should display a stock label with the name of
1586
the file that is being previewed; the default is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>. Applications that
1587
want to draw the whole preview area themselves should set this to <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> and
1588
display the name themselves in their preview widget.
1591
See also: <link linkend="gtk-file-chooser-set-preview-widget"><function>gtk_file_chooser_set_preview_widget()</function></link></para>
1594
</para><variablelist role="params">
1595
<varlistentry><term><parameter>chooser</parameter> :</term>
1596
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1597
</simpara></listitem></varlistentry>
1598
<varlistentry><term><parameter>use_label</parameter> :</term>
1599
<listitem><simpara> whether to display a stock label with the name of the previewed file
1600
</simpara></listitem></varlistentry>
1601
</variablelist><para role="since">Since 2.4
1604
<title><anchor id="gtk-file-chooser-get-use-preview-label" role="function"/>gtk_file_chooser_get_use_preview_label ()</title>
1605
<indexterm><primary>gtk_file_chooser_get_use_preview_label</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_get_use_preview_label
1606
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1608
Gets whether a stock label should be drawn with the name of the previewed
1609
file. See <link linkend="gtk-file-chooser-set-use-preview-label"><function>gtk_file_chooser_set_use_preview_label()</function></link>.</para>
1612
</para><variablelist role="params">
1613
<varlistentry><term><parameter>chooser</parameter> :</term>
1614
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1615
</simpara></listitem></varlistentry>
1616
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the file chooser is set to display a label with the
1617
name of the previewed file, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
1618
</simpara></listitem></varlistentry>
1619
</variablelist></refsect2>
1621
<title><anchor id="gtk-file-chooser-get-preview-filename" role="function" condition="since:2.4"/>gtk_file_chooser_get_preview_filename ()</title>
1622
<indexterm role="2.4"><primary>gtk_file_chooser_get_preview_filename</primary></indexterm><programlisting><link linkend="char">char</link>* gtk_file_chooser_get_preview_filename
1623
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1625
Gets the filename that should be previewed in a custom preview
1626
widget. See <link linkend="gtk-file-chooser-set-preview-widget"><function>gtk_file_chooser_set_preview_widget()</function></link>.</para>
1629
</para><variablelist role="params">
1630
<varlistentry><term><parameter>chooser</parameter> :</term>
1631
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1632
</simpara></listitem></varlistentry>
1633
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the filename to preview, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if no file
1634
is selected, or if the selected file cannot be represented
1635
as a local filename. Free with <link linkend="g-free"><function>g_free()</function></link>
1637
</simpara></listitem></varlistentry>
1638
</variablelist><para role="since">Since 2.4
1641
<title><anchor id="gtk-file-chooser-get-preview-uri" role="function" condition="since:2.4"/>gtk_file_chooser_get_preview_uri ()</title>
1642
<indexterm role="2.4"><primary>gtk_file_chooser_get_preview_uri</primary></indexterm><programlisting><link linkend="char">char</link>* gtk_file_chooser_get_preview_uri (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1644
Gets the URI that should be previewed in a custom preview
1645
widget. See <link linkend="gtk-file-chooser-set-preview-widget"><function>gtk_file_chooser_set_preview_widget()</function></link>.</para>
1648
</para><variablelist role="params">
1649
<varlistentry><term><parameter>chooser</parameter> :</term>
1650
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1651
</simpara></listitem></varlistentry>
1652
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the URI for the file to preview, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if no file is
1653
selected. Free with <link linkend="g-free"><function>g_free()</function></link>.
1655
</simpara></listitem></varlistentry>
1656
</variablelist><para role="since">Since 2.4
1659
<title><anchor id="gtk-file-chooser-set-extra-widget" role="function" condition="since:2.4"/>gtk_file_chooser_set_extra_widget ()</title>
1660
<indexterm role="2.4"><primary>gtk_file_chooser_set_extra_widget</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_extra_widget (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1661
<link linkend="GtkWidget">GtkWidget</link> *extra_widget);</programlisting>
1663
Sets an application-supplied widget to provide extra options to the user.</para>
1666
</para><variablelist role="params">
1667
<varlistentry><term><parameter>chooser</parameter> :</term>
1668
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1669
</simpara></listitem></varlistentry>
1670
<varlistentry><term><parameter>extra_widget</parameter> :</term>
1671
<listitem><simpara> widget for extra options
1672
</simpara></listitem></varlistentry>
1673
</variablelist><para role="since">Since 2.4
1676
<title><anchor id="gtk-file-chooser-get-extra-widget" role="function" condition="since:2.4"/>gtk_file_chooser_get_extra_widget ()</title>
1677
<indexterm role="2.4"><primary>gtk_file_chooser_get_extra_widget</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>* gtk_file_chooser_get_extra_widget (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1679
Gets the current preview widget; see
1680
<link linkend="gtk-file-chooser-set-extra-widget"><function>gtk_file_chooser_set_extra_widget()</function></link>.</para>
1683
</para><variablelist role="params">
1684
<varlistentry><term><parameter>chooser</parameter> :</term>
1685
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1686
</simpara></listitem></varlistentry>
1687
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current extra widget, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1689
</simpara></listitem></varlistentry>
1690
</variablelist><para role="since">Since 2.4
1693
<title><anchor id="gtk-file-chooser-add-filter" role="function" condition="since:2.4"/>gtk_file_chooser_add_filter ()</title>
1694
<indexterm role="2.4"><primary>gtk_file_chooser_add_filter</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_add_filter (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1695
<link linkend="GtkFileFilter">GtkFileFilter</link> *filter);</programlisting>
1697
Adds <parameter>filter</parameter> to the list of filters that the user can select between.
1698
When a filter is selected, only files that are passed by that
1699
filter are displayed.
1702
Note that the <parameter>chooser</parameter> takes ownership of the filter, so you have to
1703
ref and sink it if you want to keep a reference.</para>
1706
</para><variablelist role="params">
1707
<varlistentry><term><parameter>chooser</parameter> :</term>
1708
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1709
</simpara></listitem></varlistentry>
1710
<varlistentry><term><parameter>filter</parameter> :</term>
1711
<listitem><simpara> a <link linkend="GtkFileFilter"><type>GtkFileFilter</type></link>
1712
</simpara></listitem></varlistentry>
1713
</variablelist><para role="since">Since 2.4
1716
<title><anchor id="gtk-file-chooser-remove-filter" role="function" condition="since:2.4"/>gtk_file_chooser_remove_filter ()</title>
1717
<indexterm role="2.4"><primary>gtk_file_chooser_remove_filter</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_remove_filter (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1718
<link linkend="GtkFileFilter">GtkFileFilter</link> *filter);</programlisting>
1720
Removes <parameter>filter</parameter> from the list of filters that the user can select between.</para>
1723
</para><variablelist role="params">
1724
<varlistentry><term><parameter>chooser</parameter> :</term>
1725
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1726
</simpara></listitem></varlistentry>
1727
<varlistentry><term><parameter>filter</parameter> :</term>
1728
<listitem><simpara> a <link linkend="GtkFileFilter"><type>GtkFileFilter</type></link>
1729
</simpara></listitem></varlistentry>
1730
</variablelist><para role="since">Since 2.4
1733
<title><anchor id="gtk-file-chooser-list-filters" role="function" condition="since:2.4"/>gtk_file_chooser_list_filters ()</title>
1734
<indexterm role="2.4"><primary>gtk_file_chooser_list_filters</primary></indexterm><programlisting><link linkend="GSList">GSList</link>* gtk_file_chooser_list_filters (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1736
Lists the current set of user-selectable filters; see
1737
<link linkend="gtk-file-chooser-add-filter"><function>gtk_file_chooser_add_filter()</function></link>, <link linkend="gtk-file-chooser-remove-filter"><function>gtk_file_chooser_remove_filter()</function></link>.</para>
1740
</para><variablelist role="params">
1741
<varlistentry><term><parameter>chooser</parameter> :</term>
1742
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1743
</simpara></listitem></varlistentry>
1744
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GSList"><type>GSList</type></link> containing the current set of
1745
user selectable filters. The contents of the list are
1746
owned by GTK+, but you must free the list itself with
1747
<link linkend="g-slist-free"><function>g_slist_free()</function></link> when you are done with it.
1749
</simpara></listitem></varlistentry>
1750
</variablelist><para role="since">Since 2.4
1753
<title><anchor id="gtk-file-chooser-set-filter" role="function" condition="since:2.4"/>gtk_file_chooser_set_filter ()</title>
1754
<indexterm role="2.4"><primary>gtk_file_chooser_set_filter</primary></indexterm><programlisting><link linkend="void">void</link> gtk_file_chooser_set_filter (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1755
<link linkend="GtkFileFilter">GtkFileFilter</link> *filter);</programlisting>
1757
Sets the current filter; only the files that pass the
1758
filter will be displayed. If the user-selectable list of filters
1759
is non-empty, then the filter should be one of the filters
1760
in that list. Setting the current filter when the list of
1761
filters is empty is useful if you want to restrict the displayed
1762
set of files without letting the user change it.</para>
1765
</para><variablelist role="params">
1766
<varlistentry><term><parameter>chooser</parameter> :</term>
1767
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1768
</simpara></listitem></varlistentry>
1769
<varlistentry><term><parameter>filter</parameter> :</term>
1770
<listitem><simpara> a <link linkend="GtkFileFilter"><type>GtkFileFilter</type></link>
1771
</simpara></listitem></varlistentry>
1772
</variablelist><para role="since">Since 2.4
1775
<title><anchor id="gtk-file-chooser-get-filter" role="function" condition="since:2.4"/>gtk_file_chooser_get_filter ()</title>
1776
<indexterm role="2.4"><primary>gtk_file_chooser_get_filter</primary></indexterm><programlisting><link linkend="GtkFileFilter">GtkFileFilter</link>* gtk_file_chooser_get_filter (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1778
Gets the current filter; see <link linkend="gtk-file-chooser-set-filter"><function>gtk_file_chooser_set_filter()</function></link>.</para>
1781
</para><variablelist role="params">
1782
<varlistentry><term><parameter>chooser</parameter> :</term>
1783
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1784
</simpara></listitem></varlistentry>
1785
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current filter, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1787
</simpara></listitem></varlistentry>
1788
</variablelist><para role="since">Since 2.4
1791
<title><anchor id="gtk-file-chooser-add-shortcut-folder" role="function" condition="since:2.4"/>gtk_file_chooser_add_shortcut_folder ()</title>
1792
<indexterm role="2.4"><primary>gtk_file_chooser_add_shortcut_folder</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_add_shortcut_folder
1793
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1794
const <link linkend="char">char</link> *folder,
1795
<link linkend="GError">GError</link> **error);</programlisting>
1797
Adds a folder to be displayed with the shortcut folders in a file chooser.
1798
Note that shortcut folders do not get saved, as they are provided by the
1799
application. For example, you can use this to add a
1800
"/usr/share/mydrawprogram/Clipart" folder to the volume list.</para>
1803
</para><variablelist role="params">
1804
<varlistentry><term><parameter>chooser</parameter> :</term>
1805
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1806
</simpara></listitem></varlistentry>
1807
<varlistentry><term><parameter>folder</parameter> :</term>
1808
<listitem><simpara> filename of the folder to add
1809
</simpara></listitem></varlistentry>
1810
<varlistentry><term><parameter>error</parameter> :</term>
1811
<listitem><simpara> location to store error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1812
</simpara></listitem></varlistentry>
1813
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the folder could be added successfully, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
1814
otherwise. In the latter case, the <parameter>error</parameter> will be set as appropriate.
1816
</simpara></listitem></varlistentry>
1817
</variablelist><para role="since">Since 2.4
1820
<title><anchor id="gtk-file-chooser-remove-shortcut-folder" role="function" condition="since:2.4"/>gtk_file_chooser_remove_shortcut_folder ()</title>
1821
<indexterm role="2.4"><primary>gtk_file_chooser_remove_shortcut_folder</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_remove_shortcut_folder
1822
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1823
const <link linkend="char">char</link> *folder,
1824
<link linkend="GError">GError</link> **error);</programlisting>
1826
Removes a folder from a file chooser's list of shortcut folders.</para>
1829
</para><variablelist role="params">
1830
<varlistentry><term><parameter>chooser</parameter> :</term>
1831
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1832
</simpara></listitem></varlistentry>
1833
<varlistentry><term><parameter>folder</parameter> :</term>
1834
<listitem><simpara> filename of the folder to remove
1835
</simpara></listitem></varlistentry>
1836
<varlistentry><term><parameter>error</parameter> :</term>
1837
<listitem><simpara> location to store error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1838
</simpara></listitem></varlistentry>
1839
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the operation succeeds, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
1840
In the latter case, the <parameter>error</parameter> will be set as appropriate.
1842
See also: <link linkend="gtk-file-chooser-add-shortcut-folder"><function>gtk_file_chooser_add_shortcut_folder()</function></link>
1844
</simpara></listitem></varlistentry>
1845
</variablelist><para role="since">Since 2.4
1848
<title><anchor id="gtk-file-chooser-list-shortcut-folders" role="function" condition="since:2.4"/>gtk_file_chooser_list_shortcut_folders ()</title>
1849
<indexterm role="2.4"><primary>gtk_file_chooser_list_shortcut_folders</primary></indexterm><programlisting><link linkend="GSList">GSList</link>* gtk_file_chooser_list_shortcut_folders
1850
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1852
Queries the list of shortcut folders in the file chooser, as set by
1853
<link linkend="gtk-file-chooser-add-shortcut-folder"><function>gtk_file_chooser_add_shortcut_folder()</function></link>.</para>
1856
</para><variablelist role="params">
1857
<varlistentry><term><parameter>chooser</parameter> :</term>
1858
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1859
</simpara></listitem></varlistentry>
1860
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A list of folder filenames, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if there are no shortcut
1861
folders. Free the returned list with <link linkend="g-slist-free"><function>g_slist_free()</function></link>, and the filenames with
1862
<link linkend="g-free"><function>g_free()</function></link>.
1864
</simpara></listitem></varlistentry>
1865
</variablelist><para role="since">Since 2.4
1868
<title><anchor id="gtk-file-chooser-add-shortcut-folder-uri" role="function" condition="since:2.4"/>gtk_file_chooser_add_shortcut_folder_uri ()</title>
1869
<indexterm role="2.4"><primary>gtk_file_chooser_add_shortcut_folder_uri</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_add_shortcut_folder_uri
1870
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1871
const <link linkend="char">char</link> *uri,
1872
<link linkend="GError">GError</link> **error);</programlisting>
1874
Adds a folder URI to be displayed with the shortcut folders in a file
1875
chooser. Note that shortcut folders do not get saved, as they are provided
1876
by the application. For example, you can use this to add a
1877
"file:///usr/share/mydrawprogram/Clipart" folder to the volume list.</para>
1880
</para><variablelist role="params">
1881
<varlistentry><term><parameter>chooser</parameter> :</term>
1882
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1883
</simpara></listitem></varlistentry>
1884
<varlistentry><term><parameter>uri</parameter> :</term>
1885
<listitem><simpara> URI of the folder to add
1886
</simpara></listitem></varlistentry>
1887
<varlistentry><term><parameter>error</parameter> :</term>
1888
<listitem><simpara> location to store error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1889
</simpara></listitem></varlistentry>
1890
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the folder could be added successfully, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
1891
otherwise. In the latter case, the <parameter>error</parameter> will be set as appropriate.
1893
</simpara></listitem></varlistentry>
1894
</variablelist><para role="since">Since 2.4
1897
<title><anchor id="gtk-file-chooser-remove-shortcut-folder-uri" role="function" condition="since:2.4"/>gtk_file_chooser_remove_shortcut_folder_uri ()</title>
1898
<indexterm role="2.4"><primary>gtk_file_chooser_remove_shortcut_folder_uri</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_file_chooser_remove_shortcut_folder_uri
1899
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
1900
const <link linkend="char">char</link> *uri,
1901
<link linkend="GError">GError</link> **error);</programlisting>
1903
Removes a folder URI from a file chooser's list of shortcut folders.</para>
1906
</para><variablelist role="params">
1907
<varlistentry><term><parameter>chooser</parameter> :</term>
1908
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1909
</simpara></listitem></varlistentry>
1910
<varlistentry><term><parameter>uri</parameter> :</term>
1911
<listitem><simpara> URI of the folder to remove
1912
</simpara></listitem></varlistentry>
1913
<varlistentry><term><parameter>error</parameter> :</term>
1914
<listitem><simpara> location to store error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1915
</simpara></listitem></varlistentry>
1916
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the operation succeeds, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
1917
In the latter case, the <parameter>error</parameter> will be set as appropriate.
1919
See also: <link linkend="gtk-file-chooser-add-shortcut-folder-uri"><function>gtk_file_chooser_add_shortcut_folder_uri()</function></link>
1921
</simpara></listitem></varlistentry>
1922
</variablelist><para role="since">Since 2.4
1925
<title><anchor id="gtk-file-chooser-list-shortcut-folder-uris" role="function" condition="since:2.4"/>gtk_file_chooser_list_shortcut_folder_uris ()</title>
1926
<indexterm role="2.4"><primary>gtk_file_chooser_list_shortcut_folder_uris</primary></indexterm><programlisting><link linkend="GSList">GSList</link>* gtk_file_chooser_list_shortcut_folder_uris
1927
(<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser);</programlisting>
1929
Queries the list of shortcut folders in the file chooser, as set by
1930
<link linkend="gtk-file-chooser-add-shortcut-folder-uri"><function>gtk_file_chooser_add_shortcut_folder_uri()</function></link>.</para>
1933
</para><variablelist role="params">
1934
<varlistentry><term><parameter>chooser</parameter> :</term>
1935
<listitem><simpara> a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
1936
</simpara></listitem></varlistentry>
1937
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A list of folder URIs, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if there are no shortcut
1938
folders. Free the returned list with <link linkend="g-slist-free"><function>g_slist_free()</function></link>, and the URIs with
1939
<link linkend="g-free"><function>g_free()</function></link>.
1941
</simpara></listitem></varlistentry>
1942
</variablelist><para role="since">Since 2.4
1947
<refsect1 role="signals">
1948
<title role="signals.title">Signal Details</title>
1949
<refsect2><title><anchor id="GtkFileChooser-confirm-overwrite"/>The "confirm-overwrite" signal</title>
1950
<indexterm><primary>GtkFileChooser::confirm-overwrite</primary></indexterm><programlisting><link linkend="GtkFileChooserConfirmation">GtkFileChooserConfirmation</link>user_function (<link linkend="GtkFileChooser">GtkFileChooser</link> *filechooser,
1951
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
1953
This signal gets emitted whenever it is appropriate to present a
1954
confirmation dialog when the user has selected a file name that
1955
already exists. The signal only gets emitted when the file
1956
chooser is in <link linkend="GTK-FILE-CHOOSER-ACTION-SAVE:CAPS"><type>GTK_FILE_CHOOSER_ACTION_SAVE</type></link> mode.
1960
Most applications just need to turn on the <link
1961
linkend="GtkFileChooser--do-overwrite-confirmation">do-overwrite-confirmation</link>
1962
property (or call the
1963
<link linkend="gtk-file-chooser-set-do-overwrite-confirmation"><function>gtk_file_chooser_set_do_overwrite_confirmation()</function></link> function), and
1964
they will automatically get a stock confirmation dialog.
1965
Applications which need to customize this behavior should do
1966
that, and also connect to the <symbol>confirm-overwrite</symbol>
1971
A signal handler for this signal must return a
1972
<link linkend="GtkFileChooserConfirmation"><type>GtkFileChooserConfirmation</type></link> value, which indicates the action to
1973
take. If the handler determines that the user wants to select a
1974
different filename, it should return
1975
<link linkend="GTK-FILE-CHOOSER-CONFIRMATION-SELECT-AGAIN:CAPS"><type>GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN</type></link>. If it determines
1976
that the user is satisfied with his choice of file name, it
1977
should return <link linkend="GTK-FILE-CHOOSER-CONFIRMATION-ACCEPT-FILENAME:CAPS"><type>GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME</type></link>.
1978
On the other hand, if it determines that the stock confirmation
1979
dialog should be used, it should return
1980
<link linkend="GTK-FILE-CHOOSER-CONFIRMATION-CONFIRM:CAPS"><type>GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM</type></link>. The following example
1984
<example id="gtkfilechooser-confirmation">
1985
<title>Custom confirmation</title>
1988
static GtkFileChooserConfirmation
1989
confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data)
1993
uri = gtk_file_chooser_get_uri (chooser);
1995
if (is_uri_read_only (uri))
1997
if (user_wants_to_replace_read_only_file (uri))
1998
return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME;
2000
return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN;
2002
return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; /* fall back to the default dialog */
2007
chooser = gtk_file_chooser_dialog_new (...);
2009
gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
2010
g_signal_connect (chooser, "confirm-overwrite",
2011
G_CALLBACK (confirm_overwrite_callback), NULL);
2013
if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT)
2014
save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser));
2016
gtk_widget_destroy (chooser);
2018
</example><variablelist role="params">
2019
<varlistentry><term><parameter>filechooser</parameter> :</term>
2020
<listitem><simpara>the object which received the signal.
2021
</simpara></listitem></varlistentry>
2022
<varlistentry><term><parameter>user_data</parameter> :</term>
2023
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
2024
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><link linkend="GtkFileChooserConfirmation"><type>GtkFileChooserConfirmation</type></link> value that indicates which
2025
action to take after emitting the signal.
2031
</simpara></listitem></varlistentry>
2032
</variablelist></refsect2><refsect2><title><anchor id="GtkFileChooser-current-folder-changed"/>The "current-folder-changed" signal</title>
2033
<indexterm><primary>GtkFileChooser::current-folder-changed</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
2034
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
2036
This signal is emitted when the current folder in a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>
2037
changes. This can happen due to the user performing some action that
2038
changes folders, such as selecting a bookmark or visiting a folder on the
2039
file list. It can also happen as a result of calling a function to
2040
explicitly change the current folder in a file chooser.
2043
Normally you do not need to connect to this signal, unless you need to keep
2044
track of which folder a file chooser is showing.
2047
See also: <link linkend="gtk-file-chooser-set-current-folder"><function>gtk_file_chooser_set_current_folder()</function></link>,
2048
<link linkend="gtk-file-chooser-get-current-folder"><function>gtk_file_chooser_get_current_folder()</function></link>,
2049
<link linkend="gtk-file-chooser-set-current-folder-uri"><function>gtk_file_chooser_set_current_folder_uri()</function></link>,
2050
<link linkend="gtk-file-chooser-get-current-folder-uri"><function>gtk_file_chooser_get_current_folder_uri()</function></link>.</para>
2053
</para><variablelist role="params">
2054
<varlistentry><term><parameter>chooser</parameter> :</term>
2055
<listitem><simpara> the object which received the signal.
2056
</simpara></listitem></varlistentry>
2057
<varlistentry><term><parameter>user_data</parameter> :</term>
2058
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
2059
</variablelist></refsect2><refsect2><title><anchor id="GtkFileChooser-file-activated"/>The "file-activated" signal</title>
2060
<indexterm><primary>GtkFileChooser::file-activated</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
2061
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
2063
This signal is emitted when the user "activates" a file in the file
2064
chooser. This can happen by double-clicking on a file in the file list, or
2065
by pressing <keycap>Enter</keycap>.
2068
Normally you do not need to connect to this signal. It is used internally
2069
by <link linkend="GtkFileChooserDialog"><type>GtkFileChooserDialog</type></link> to know when to activate the default button in the
2073
See also: <link linkend="gtk-file-chooser-get-filename"><function>gtk_file_chooser_get_filename()</function></link>,
2074
<link linkend="gtk-file-chooser-get-filenames"><function>gtk_file_chooser_get_filenames()</function></link>, <link linkend="gtk-file-chooser-get-uri"><function>gtk_file_chooser_get_uri()</function></link>,
2075
<link linkend="gtk-file-chooser-get-uris"><function>gtk_file_chooser_get_uris()</function></link>.</para>
2078
</para><variablelist role="params">
2079
<varlistentry><term><parameter>chooser</parameter> :</term>
2080
<listitem><simpara> the object which received the signal.
2081
</simpara></listitem></varlistentry>
2082
<varlistentry><term><parameter>user_data</parameter> :</term>
2083
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
2084
</variablelist></refsect2><refsect2><title><anchor id="GtkFileChooser-selection-changed"/>The "selection-changed" signal</title>
2085
<indexterm><primary>GtkFileChooser::selection-changed</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
2086
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
2088
This signal is emitted when there is a change in the set of selected files
2089
in a <link linkend="GtkFileChooser"><type>GtkFileChooser</type></link>. This can happen when the user modifies the selection
2090
with the mouse or the keyboard, or when explicitly calling functions to
2091
change the selection.
2094
Normally you do not need to connect to this signal, as it is easier to wait
2095
for the file chooser to finish running, and then to get the list of
2096
selected files using the functions mentioned below.
2099
See also: <link linkend="gtk-file-chooser-select-filename"><function>gtk_file_chooser_select_filename()</function></link>,
2100
<link linkend="gtk-file-chooser-unselect-filename"><function>gtk_file_chooser_unselect_filename()</function></link>, <link linkend="gtk-file-chooser-get-filename"><function>gtk_file_chooser_get_filename()</function></link>,
2101
<link linkend="gtk-file-chooser-get-filenames"><function>gtk_file_chooser_get_filenames()</function></link>, <link linkend="gtk-file-chooser-select-uri"><function>gtk_file_chooser_select_uri()</function></link>,
2102
<link linkend="gtk-file-chooser-unselect-uri"><function>gtk_file_chooser_unselect_uri()</function></link>, <link linkend="gtk-file-chooser-get-uri"><function>gtk_file_chooser_get_uri()</function></link>,
2103
<link linkend="gtk-file-chooser-get-uris"><function>gtk_file_chooser_get_uris()</function></link>.</para>
2106
</para><variablelist role="params">
2107
<varlistentry><term><parameter>chooser</parameter> :</term>
2108
<listitem><simpara> the object which received the signal.
2109
</simpara></listitem></varlistentry>
2110
<varlistentry><term><parameter>user_data</parameter> :</term>
2111
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
2112
</variablelist></refsect2><refsect2><title><anchor id="GtkFileChooser-update-preview"/>The "update-preview" signal</title>
2113
<indexterm><primary>GtkFileChooser::update-preview</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="GtkFileChooser">GtkFileChooser</link> *chooser,
2114
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
2116
This signal is emitted when the preview in a file chooser should be
2117
regenerated. For example, this can happen when the currently selected file
2118
changes. You should use this signal if you want your file chooser to have
2122
Once you have installed a preview widget with
2123
<link linkend="gtk-file-chooser-set-preview-widget"><function>gtk_file_chooser_set_preview_widget()</function></link>, you should update it when this
2124
signal is emitted. You can use the functions
2125
<link linkend="gtk-file-chooser-get-preview-filename"><function>gtk_file_chooser_get_preview_filename()</function></link> or
2126
<link linkend="gtk-file-chooser-get-preview-uri"><function>gtk_file_chooser_get_preview_uri()</function></link> to get the name of the file to preview.
2127
Your widget may not be able to preview all kinds of files; your callback
2128
must call <link linkend="gtk-file-chooser-set-preview-wiget-active"><function>gtk_file_chooser_set_preview_wiget_active()</function></link> to inform the file
2129
chooser about whether the preview was generated successfully or not.
2132
Please see the example code in <xref linkend="gtkfilechooser-preview"/>.
2135
See also: <link linkend="gtk-file-chooser-set-preview-widget"><function>gtk_file_chooser_set_preview_widget()</function></link>,
2136
<link linkend="gtk-file-chooser-set-preview-widget-active"><function>gtk_file_chooser_set_preview_widget_active()</function></link>,
2137
<link linkend="gtk-file-chooser-set-use-preview-label"><function>gtk_file_chooser_set_use_preview_label()</function></link>,
2138
<link linkend="gtk-file-chooser-get-preview-filename"><function>gtk_file_chooser_get_preview_filename()</function></link>,
2139
<link linkend="gtk-file-chooser-get-preview-uri"><function>gtk_file_chooser_get_preview_uri()</function></link>.</para>
2142
</para><variablelist role="params">
2143
<varlistentry><term><parameter>chooser</parameter> :</term>
2144
<listitem><simpara> the object which received the signal.
2145
</simpara></listitem></varlistentry>
2146
<varlistentry><term><parameter>user_data</parameter> :</term>
2147
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
2148
</variablelist></refsect2>
2153
<title>See Also</title>
2155
<link linkend="GtkFileChooserDialog"><type>GtkFileChooserDialog</type></link>, <link linkend="GtkFileChooserWidget"><type>GtkFileChooserWidget</type></link>, <link linkend="GtkFileChooserButton"><type>GtkFileChooserButton</type></link>
added
removed
docs/reference/gtk/xml/gtkfilechooser.xml
