1 /* GTK - The GIMP Toolkit
2 * gtkfilechooser.c: Abstract interface for file selector GUIs
3 * Copyright (C) 2003, Red Hat, Inc.
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 * Boston, MA 02111-1307, USA.
19 */
20
21 #include "config.h"
22 #include "gtkfilechooser.h"
23 #include "gtkfilechooserprivate.h"
24 #include "gtkintl.h"
25 #include "gtktypebuiltins.h"
26 #include "gtkprivate.h"
27 #include "gtkmarshalers.h"
28 #include "gtkalias.h"
29
30
31 /**
32 * SECTION:gtkfilechooser
33 * @Short_description: File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog
34 * @Title: GtkFileChooser
35 * @See_also: #GtkFileChooserDialog, #GtkFileChooserWidget, #GtkFileChooserButton
36 *
37 * #GtkFileChooser is an interface that can be implemented by file
38 * selection widgets. In GTK+, the main objects that implement this
39 * interface are #GtkFileChooserWidget, #GtkFileChooserDialog, and
40 * #GtkFileChooserButton. You do not need to write an object that
41 * implements the #GtkFileChooser interface unless you are trying to
42 * adapt an existing file selector to expose a standard programming
43 * interface.
44 *
45 * #GtkFileChooser allows for shortcuts to various places in the filesystem.
46 * In the default implementation these are displayed in the left pane. It
47 * may be a bit confusing at first that these shortcuts come from various
48 * sources and in various flavours, so lets explain the terminology here:
49 * <variablelist>
50 * <varlistentry>
51 * <term>Bookmarks</term>
52 * <listitem>
53 * are created by the user, by dragging folders from the
54 * right pane to the left pane, or by using the "Add". Bookmarks
55 * can be renamed and deleted by the user.
56 * </listitem>
57 * </varlistentry>
58 * <varlistentry>
59 * <term>Shortcuts</term>
60 * <listitem>
61 * can be provided by the application or by the underlying filesystem
62 * abstraction (e.g. both the gnome-vfs and the Windows filesystems
63 * provide "Desktop" shortcuts). Shortcuts cannot be modified by the
64 * user.
65 * </listitem>
66 * </varlistentry>
67 * <varlistentry>
68 * <term>Volumes</term>
69 * <listitem>
70 * are provided by the underlying filesystem abstraction. They are
71 * the "roots" of the filesystem.
72 * </listitem>
73 * </varlistentry>
74 * </variablelist>
75 *
76 * <refsect2 id="gtkfilechooser-encodings">
77 * <title>File Names and Encodings</title>
78 * When the user is finished selecting files in a
79 * #GtkFileChooser, your program can get the selected names
80 * either as filenames or as URIs. For URIs, the normal escaping
81 * rules are applied if the URI contains non-ASCII characters.
82 * However, filenames are <emphasis>always</emphasis> returned in
83 * the character set specified by the
84 * <envar>G_FILENAME_ENCODING</envar> environment variable.
85 * Please see the Glib documentation for more details about this
86 * variable.
87 * <note>
88 * This means that while you can pass the result of
89 * gtk_file_chooser_get_filename() to
90 * <function>open(2)</function> or
91 * <function>fopen(3)</function>, you may not be able to
92 * directly set it as the text of a #GtkLabel widget unless you
93 * convert it first to UTF-8, which all GTK+ widgets expect.
94 * You should use g_filename_to_utf8() to convert filenames
95 * into strings that can be passed to GTK+ widgets.
96 * </note>
97 * </refsect2>
98 * <refsect2 id="gtkfilechooser-preview">
99 * <title>Adding a Preview Widget</title>
100 * <para>
101 * You can add a custom preview widget to a file chooser and then
102 * get notification about when the preview needs to be updated.
103 * To install a preview widget, use
104 * gtk_file_chooser_set_preview_widget(). Then, connect to the
105 * #GtkFileChooser::update-preview signal to get notified when
106 * you need to update the contents of the preview.
107 * </para>
108 * <para>
109 * Your callback should use
110 * gtk_file_chooser_get_preview_filename() to see what needs
111 * previewing. Once you have generated the preview for the
112 * corresponding file, you must call
113 * gtk_file_chooser_set_preview_widget_active() with a boolean
114 * flag that indicates whether your callback could successfully
115 * generate a preview.
116 * </para>
117 * <example id="example-gtkfilechooser-preview">
118 * <title>Sample Usage</title>
119 * <programlisting>
120 * {
121 * GtkImage *preview;
122 *
123 * ...
124 *
125 * preview = gtk_image_new (<!-- -->);
126 *
127 * gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
128 * g_signal_connect (my_file_chooser, "update-preview",
129 * G_CALLBACK (update_preview_cb), preview);
130 * }
131 *
132 * static void
133 * update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
134 * {
135 * GtkWidget *preview;
136 * char *filename;
137 * GdkPixbuf *pixbuf;
138 * gboolean have_preview;
139 *
140 * preview = GTK_WIDGET (data);
141 * filename = gtk_file_chooser_get_preview_filename (file_chooser);
142 *
143 * pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
144 * have_preview = (pixbuf != NULL);
145 * g_free (filename);
146 *
147 * gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
148 * if (pixbuf)
149 * g_object_unref (pixbuf);
150 *
151 * gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
152 * }
153 * </programlisting>
154 * </example>
155 * </refsect2>
156 * <refsect2 id="gtkfilechooser-extra">
157 * <title>Adding Extra Widgets</title>
158 * <para>
159 * You can add extra widgets to a file chooser to provide options
160 * that are not present in the default design. For example, you
161 * can add a toggle button to give the user the option to open a
162 * file in read-only mode. You can use
163 * gtk_file_chooser_set_extra_widget() to insert additional
164 * widgets in a file chooser.
165 * </para>
166 * <example id="example-gtkfilechooser-extra">
167 * <title>Sample Usage</title>
168 * <programlisting>
169 *
170 * GtkWidget *toggle;
171 *
172 * ...
173 *
174 * toggle = gtk_check_button_new_with_label ("Open file read-only");
175 * gtk_widget_show (toggle);
176 * gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
177 * }
178 * </programlisting>
179 * </example>
180 * <note>
181 * If you want to set more than one extra widget in the file
182 * chooser, you can a container such as a #GtkVBox or a #GtkTable
183 * and include your widgets in it. Then, set the container as
184 * the whole extra widget.
185 * </note>
186 * </refsect2>
187 * <refsect2 id="gtkfilechooser-key-bindings">
188 * <title>Key Bindings</title>
189 * <para>
190 * Internally, GTK+ implements a file chooser's graphical user
191 * interface with the private
192 * <classname>GtkFileChooserDefaultClass</classname>. This
193 * widget has several <link linkend="gtk-Bindings">key
194 * bindings</link> and their associated signals. This section
195 * describes the available key binding signals.
196 * </para>
197 * <example id="gtkfilechooser-key-binding-example">
198 * <title>GtkFileChooser key binding example</title>
199 * <para>
200 * The default keys that activate the key-binding signals in
201 * <classname>GtkFileChooserDefaultClass</classname> are as
202 * follows:
203 * </para>
204 * <informaltable>
205 * <tgroup cols="2">
206 * <tbody>
207 * <row>
208 * <entry>Signal name</entry>
209 * <entry>Default key combinations</entry>
210 * </row>
211 * <row>
212 * <entry>location-popup</entry>
213 * <entry>
214 * <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> (empty path);
215 * <keycap>/</keycap> (path of "/")
216 * <footnote>
217 * Both the individual <keycap>/</keycap> key and the
218 * numeric keypad's "divide" key are supported.
219 * </footnote>;
220 * <keycap>~</keycap> (path of "~")
221 * </entry>
222 * </row>
223 * <row>
224 * <entry>up-folder</entry>
225 * <entry>
226 * <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>;
227 * <keycombo><keycap>Alt</keycap><keycap>Shift</keycap><keycap>Up</keycap></keycombo>
228 * <footnote>
229 * Both the individual Up key and the numeric
230 * keypad's Up key are supported.
231 * </footnote>;
232 * <keycap>Backspace</keycap>
233 * </entry>
234 * </row>
235 * <row>
236 * <entry>down-folder</entry>
237 * <entry>
238 * <keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>;
239 * <keycombo><keycap>Alt</keycap><keycap>Shift</keycap><keycap>Down</keycap></keycombo>
240 * <footnote>
241 * Both the individual Down key and the numeric
242 * keypad's Down key are supported.
243 * </footnote>
244 * </entry>
245 * </row>
246 * <row>
247 * <entry>home-folder</entry>
248 * <entry><keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo></entry>
249 * </row>
250 * <row>
251 * <entry>desktop-folder</entry>
252 * <entry><keycombo><keycap>Alt</keycap><keycap>D</keycap></keycombo></entry>
253 * </row>
254 * <row>
255 * <entry>quick-bookmark</entry>
256 * <entry><keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo> through <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo></entry>
257 * </row>
258 * </tbody>
259 * </tgroup>
260 * </informaltable>
261 * <para>
262 * You can change these defaults to something else. For
263 * example, to add a <keycap>Shift</keycap> modifier to a few
264 * of the default bindings, you can include the following
265 * fragment in your <filename>.gtkrc-3.0</filename> file:
266 * </para>
267 * <programlisting>
268 * binding "my-own-gtkfilechooser-bindings" {
269 * bind "<Alt><Shift>Up" {
270 * "up-folder" ()
271 * }
272 * bind "<Alt><Shift>Down" {
273 * "down-folder" ()
274 * }
275 * bind "<Alt><Shift>Home" {
276 * "home-folder" ()
277 * }
278 * }
279 *
280 * class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"
281 * </programlisting>
282 * </example>
283 * <refsect3 id="GtkFileChooserDefault-location-popup">
284 * <title>The "GtkFileChooserDefault::location-popup" signal</title>
285 * <programlisting>
286 * void user_function (GtkFileChooserDefault *chooser,
287 * const char *path,
288 * <link linkend="gpointer">gpointer</link> user_data);
289 * </programlisting>
290 * <para>
291 * This is used to make the file chooser show a "Location"
292 * dialog which the user can use to manually type the name of
293 * the file he wishes to select. The
294 * <parameter>path</parameter> argument is a string that gets
295 * put in the text entry for the file name. By default this is bound to
296 * <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
297 * with a <parameter>path</parameter> string of "" (the empty
298 * string). It is also bound to <keycap>/</keycap> with a
299 * <parameter>path</parameter> string of "<literal>/</literal>"
300 * (a slash): this lets you type <keycap>/</keycap> and
301 * immediately type a path name. On Unix systems, this is bound to
302 * <keycap>~</keycap> (tilde) with a <parameter>path</parameter> string
303 * of "~" itself for access to home directories.
304 * </para>
305 * <variablelist role="params">
306 * <varlistentry>
307 * <term><parameter>chooser</parameter> :</term>
308 * <listitem>
309 * <simpara>
310 * the object which received the signal.
311 * </simpara>
312 * </listitem>
313 * </varlistentry>
314 * <varlistentry>
315 * <term><parameter>path</parameter> :</term>
316 * <listitem>
317 * <simpara>
318 * default contents for the text entry for the file name
319 * </simpara>
320 * </listitem>
321 * </varlistentry>
322 * <varlistentry>
323 * <term><parameter>user_data</parameter> :</term>
324 * <listitem>
325 * <simpara>
326 * user data set when the signal handler was connected.
327 * </simpara>
328 * </listitem>
329 * </varlistentry>
330 * </variablelist>
331 * <note>
332 * You can create your own bindings for the
333 * #GtkFileChooserDefault::location-popup signal with custom
334 * <parameter>path</parameter> strings, and have a crude form
335 * of easily-to-type bookmarks. For example, say you access
336 * the path <filename>/home/username/misc</filename> very
337 * frequently. You could then create an <keycombo>
338 * <keycap>Alt</keycap> <keycap>M</keycap> </keycombo>
339 * shortcut by including the following in your
340 * <filename>.gtkrc-3.0</filename>:
341 * <programlisting>
342 * binding "misc-shortcut" {
343 * bind "<Alt>M" {
344 * "location-popup" ("/home/username/misc")
345 * }
346 * }
347 *
348 * class "GtkFileChooserDefault" binding "misc-shortcut"
349 * </programlisting>
350 * </note>
351 * </refsect3>
352 * <refsect3 id="GtkFileChooserDefault-up-folder">
353 * <title>The "GtkFileChooserDefault::up-folder" signal</title>
354 * <programlisting>
355 * void user_function (GtkFileChooserDefault *chooser,
356 * <link linkend="gpointer">gpointer</link> user_data);
357 * </programlisting>
358 * <para>
359 * This is used to make the file chooser go to the parent of
360 * the current folder in the file hierarchy. By default this
361 * is bound to <keycap>Backspace</keycap> and
362 * <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>
363 * (the Up key in the numeric keypad also works).
364 * </para>
365 * <variablelist role="params">
366 * <varlistentry>
367 * <term><parameter>chooser</parameter> :</term>
368 * <listitem>
369 * <simpara>
370 * the object which received the signal.
371 * </simpara>
372 * </listitem>
373 * </varlistentry>
374 * <varlistentry>
375 * <term><parameter>user_data</parameter> :</term>
376 * <listitem>
377 * <simpara>
378 * user data set when the signal handler was connected.
379 * </simpara>
380 * </listitem>
381 * </varlistentry>
382 * </variablelist>
383 * </refsect3>
384 * <refsect3 id="GtkFileChooserDefault-down-folder">
385 * <title>The "GtkFileChooserDefault::down-folder" signal</title>
386 * <programlisting>
387 * void user_function (GtkFileChooserDefault *chooser,
388 * <link linkend="gpointer">gpointer</link> user_data);
389 * </programlisting>
390 * <para>
391 * This is used to make the file chooser go to a child of the
392 * current folder in the file hierarchy. The subfolder that
393 * will be used is displayed in the path bar widget of the file
394 * chooser. For example, if the path bar is showing
395 * "/foo/<emphasis>bar/</emphasis>baz", then this will cause
396 * the file chooser to switch to the "baz" subfolder. By
397 * default this is bound to
398 * <keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>
399 * (the Down key in the numeric keypad also works).
400 * </para>
401 * <variablelist role="params">
402 * <varlistentry>
403 * <term><parameter>chooser</parameter> :</term>
404 * <listitem>
405 * <simpara>
406 * the object which received the signal.
407 * </simpara>
408 * </listitem>
409 * </varlistentry>
410 * <varlistentry>
411 * <term><parameter>user_data</parameter> :</term>
412 * <listitem>
413 * <simpara>
414 * user data set when the signal handler was connected.
415 * </simpara>
416 * </listitem>
417 * </varlistentry>
418 * </variablelist>
419 * </refsect3>
420 * <refsect3 id="GtkFileChooserDefault-home-folder">
421 * <title>The "GtkFileChooserDefault::home-folder" signal</title>
422 * <programlisting>
423 * void user_function (GtkFileChooserDefault *chooser,
424 * <link linkend="gpointer">gpointer</link> user_data);
425 * </programlisting>
426 * <para>
427 * This is used to make the file chooser show the user's home
428 * folder in the file list. By default this is bound to
429 * <keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo>
430 * (the Home key in the numeric keypad also works).
431 * </para>
432 * <variablelist role="params">
433 * <varlistentry>
434 * <term><parameter>chooser</parameter> :</term>
435 * <listitem>
436 * <simpara>
437 * the object which received the signal.
438 * </simpara>
439 * </listitem>
440 * </varlistentry>
441 * <varlistentry>
442 * <term><parameter>user_data</parameter> :</term>
443 * <listitem>
444 * <simpara>
445 * user data set when the signal handler was connected.
446 * </simpara>
447 * </listitem>
448 * </varlistentry>
449 * </variablelist>
450 * </refsect3>
451 * <refsect3 id="GtkFileChooserDefault-desktop-folder">
452 * <title>The "GtkFileChooserDefault::desktop-folder" signal</title>
453 * <programlisting>
454 * void user_function (GtkFileChooserDefault *chooser,
455 * <link linkend="gpointer">gpointer</link> user_data);
456 * </programlisting>
457 * <para>
458 * This is used to make the file chooser show the user's Desktop
459 * folder in the file list. By default this is bound to
460 * <keycombo><keycap>Alt</keycap><keycap>D</keycap></keycombo>.
461 * </para>
462 * <variablelist role="params">
463 * <varlistentry>
464 * <term><parameter>chooser</parameter> :</term>
465 * <listitem>
466 * <simpara>
467 * the object which received the signal.
468 * </simpara>
469 * </listitem>
470 * </varlistentry>
471 * <varlistentry>
472 * <term><parameter>user_data</parameter> :</term>
473 * <listitem>
474 * <simpara>
475 * user data set when the signal handler was connected.
476 * </simpara>
477 * </listitem>
478 * </varlistentry>
479 * </variablelist>
480 * </refsect3>
481 * <refsect3 id="GtkFileChooserDefault-quick-bookmark">
482 * <title>The "GtkFileChooserDefault::quick-bookmark" signal</title>
483 * <programlisting>
484 * void user_function (GtkFileChooserDefault *chooser,
485 * gint bookmark_index,
486 * <link linkend="gpointer">gpointer</link> user_data);
487 * </programlisting>
488 * <para>
489 * This is used to make the file chooser switch to the bookmark
490 * specified in the <parameter>bookmark_index</parameter> parameter.
491 * For example, if you have three bookmarks, you can pass 0, 1, 2 to
492 * this signal to switch to each of them, respectively. By default this is bound to
493 * <keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo>,
494 * <keycombo><keycap>Alt</keycap><keycap>2</keycap></keycombo>,
495 * etc. until
496 * <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo>. Note
497 * that in the default binding,
498 * that <keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo> is
499 * actually defined to switch to the bookmark at index 0, and so on
500 * successively;
501 * <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo> is
502 * defined to switch to the bookmark at index 10.
503 * </para>
504 * <variablelist role="params">
505 * <varlistentry>
506 * <term><parameter>chooser</parameter> :</term>
507 * <listitem>
508 * <simpara>
509 * the object which received the signal.
510 * </simpara>
511 * </listitem>
512 * </varlistentry>
513 * <varlistentry>
514 * <term><parameter>bookmark_indes</parameter> :</term>
515 * <listitem>
516 * <simpara>
517 * index of the bookmark to switch to; the indices start at 0.
518 * </simpara>
519 * </listitem>
520 * </varlistentry>
521 * <varlistentry>
522 * <term><parameter>user_data</parameter> :</term>
523 * <listitem>
524 * <simpara>
525 * user data set when the signal handler was connected.
526 * </simpara>
527 * </listitem>
528 * </varlistentry>
529 * </variablelist>
530 * </refsect3>
531 * </refsect2>
532 * <refsect2 id="gtkfilechooser-configuration-options">
533 * <title>Configuration Options</title>
534 * <para>
535 * In GTK+ 2.x, the file chooser saves its state and configuration options in a
536 * <filename>gtk-2.0/gtkfilechooser.ini</filename> file under the directory that
537 * g_get_user_config_dir() returns. (On Unix, this usually resolves to
538 * <filename>$HOME/username/.config/gtk-2.0/gtkfilechooser.ini</filename>.) While some of
539 * the available options can be changed directly through the file chooser's user
540 * interface, a couple are only editable by hand or by third-party tools (such
541 * as <ulink
542 * url="https://wiki.gnome.org/action/show/Apps/GnomeTweakTool">gnome-tweak-tool</ulink>).
543 * This section describes the available options.
544 * </para>
545 * <para>
546 * This is a sample of the contents of a <filename>gtkfilechooser.ini</filename>
547 * file. Note that all the following options go under a
548 * <literal>[Filechooser Settings]</literal> heading.
549 * </para>
550 * <programlisting>
551 * [Filechooser Settings]
552 * LocationMode=filename-entry
553 * ShowHidden=false
554 * ExpandFolders=true
555 * GeometryX=570
556 * GeometryY=273
557 * GeometryWidth=780
558 * GeometryHeight=585
559 * ShowSizeColumn=true
560 * SortColumn=name
561 * SortOrder=ascending
562 * StartupMode=recent
563 * </programlisting>
564 * <refsect3 id="gtkfilechooser-settings-location-mode">
565 * <title>LocationMode key</title>
566 * <para>
567 * The <literal>LocationMode</literal> key controls whether the file chooser
568 * shows just a path bar, or a visible entry for the filename as well, for the
569 * benefit of typing-oriented users. The possible string values for these modes
570 * are <literal>path-bar</literal> and <literal>filename-entry</literal>,
571 * respectively.
572 * </para>
573 * </refsect3>
574 * <refsect3 id="gtkfilechooser-settings-show-hidden">
575 * <title>ShowHidden key</title>
576 * <para>
577 * The <literal>ShowHidden</literal> key controls whether the file chooser shows
578 * hidden files or not. The value can be be <literal>true</literal> or
579 * <literal>false</literal>.
580 * </para>
581 * </refsect3>
582 * <refsect3 id="gtkfilechooser-settings-show-size-column">
583 * <title>ShowSizeColumn key</title>
584 * <para>
585 * The <literal>ShowSize</literal> key controls whether the file chooser shows
586 * a column with file sizes. The value can be be <literal>true</literal> or
587 * <literal>false</literal>.
588 * </para>
589 * </refsect3>
590 * <refsect3 id="gtkfilechooser-settings-geometry-keys">
591 * <title>Geometry keys</title>
592 * <para>
593 * The four keys <literal>GeometryX</literal>, <literal>GeometryY</literal>,
594 * <literal>GeometryWidth</literal>, <literal>GeometryHeight</literal> save the
595 * position and dimensions of the #GtkFileChooserDialog's window.
596 * </para>
597 * </refsect3>
598 * <refsect3 id="gtkfilechooser-settings-sort-column">
599 * <title>SortColumn key</title>
600 * <para>
601 * The <literal>SortColumn</literal> key can be one of the strings
602 * <literal>name</literal>, <literal>modified</literal>, or
603 * <literal>size</literal>. It controls which of the columns in the file
604 * chooser is used for sorting the list of files.
605 * </para>
606 * </refsect3>
607 * <refsect3 id="gtkfilechooser-settings-sort-order">
608 * <title>SortOrder key</title>
609 * <para>
610 * The <literal>SortOrder</literal> key can be one of the strings
611 * <literal>ascending</literal> or <literal>descending</literal>.
612 * </para>
613 * </refsect3>
614 * <refsect3 id="gtkfilechooser-settings-startup-mode">
615 * <title>StartupMode key</title>
616 * <para>
617 * The <literal>StartupMode</literal> key controls whether the file chooser
618 * starts up showing the list of recently-used files, or the contents of the
619 * current working directory. Respectively, the values can be
620 * <literal>recent</literal> or <literal>cwd</literal>.
621 * </para>
622 * </refsect3>
623 * </refsect2>
624 */
625
626
627 static void gtk_file_chooser_class_init (gpointer g_iface);
628
629 GType
gtk_file_chooser_get_type(void)630 gtk_file_chooser_get_type (void)
631 {
632 static GType file_chooser_type = 0;
633
634 if (!file_chooser_type)
635 {
636 file_chooser_type = g_type_register_static_simple (G_TYPE_INTERFACE,
637 I_("GtkFileChooser"),
638 sizeof (GtkFileChooserIface),
639 (GClassInitFunc) gtk_file_chooser_class_init,
640 0, NULL, 0);
641
642 g_type_interface_add_prerequisite (file_chooser_type, GTK_TYPE_WIDGET);
643 }
644
645 return file_chooser_type;
646 }
647
648 static gboolean
confirm_overwrite_accumulator(GSignalInvocationHint * ihint,GValue * return_accu,const GValue * handler_return,gpointer dummy)649 confirm_overwrite_accumulator (GSignalInvocationHint *ihint,
650 GValue *return_accu,
651 const GValue *handler_return,
652 gpointer dummy)
653 {
654 gboolean continue_emission;
655 GtkFileChooserConfirmation conf;
656
657 conf = g_value_get_enum (handler_return);
658 g_value_set_enum (return_accu, conf);
659 continue_emission = (conf == GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM);
660
661 return continue_emission;
662 }
663
664 static void
gtk_file_chooser_class_init(gpointer g_iface)665 gtk_file_chooser_class_init (gpointer g_iface)
666 {
667 GType iface_type = G_TYPE_FROM_INTERFACE (g_iface);
668
669 /**
670 * GtkFileChooser::current-folder-changed
671 * @chooser: the object which received the signal.
672 *
673 * This signal is emitted when the current folder in a #GtkFileChooser
674 * changes. This can happen due to the user performing some action that
675 * changes folders, such as selecting a bookmark or visiting a folder on the
676 * file list. It can also happen as a result of calling a function to
677 * explicitly change the current folder in a file chooser.
678 *
679 * Normally you do not need to connect to this signal, unless you need to keep
680 * track of which folder a file chooser is showing.
681 *
682 * See also: gtk_file_chooser_set_current_folder(),
683 * gtk_file_chooser_get_current_folder(),
684 * gtk_file_chooser_set_current_folder_uri(),
685 * gtk_file_chooser_get_current_folder_uri().
686 */
687 g_signal_new (I_("current-folder-changed"),
688 iface_type,
689 G_SIGNAL_RUN_LAST,
690 G_STRUCT_OFFSET (GtkFileChooserIface, current_folder_changed),
691 NULL, NULL,
692 g_cclosure_marshal_VOID__VOID,
693 G_TYPE_NONE, 0);
694
695 /**
696 * GtkFileChooser::selection-changed
697 * @chooser: the object which received the signal.
698 *
699 * This signal is emitted when there is a change in the set of selected files
700 * in a #GtkFileChooser. This can happen when the user modifies the selection
701 * with the mouse or the keyboard, or when explicitly calling functions to
702 * change the selection.
703 *
704 * Normally you do not need to connect to this signal, as it is easier to wait
705 * for the file chooser to finish running, and then to get the list of
706 * selected files using the functions mentioned below.
707 *
708 * See also: gtk_file_chooser_select_filename(),
709 * gtk_file_chooser_unselect_filename(), gtk_file_chooser_get_filename(),
710 * gtk_file_chooser_get_filenames(), gtk_file_chooser_select_uri(),
711 * gtk_file_chooser_unselect_uri(), gtk_file_chooser_get_uri(),
712 * gtk_file_chooser_get_uris().
713 */
714 g_signal_new (I_("selection-changed"),
715 iface_type,
716 G_SIGNAL_RUN_LAST,
717 G_STRUCT_OFFSET (GtkFileChooserIface, selection_changed),
718 NULL, NULL,
719 g_cclosure_marshal_VOID__VOID,
720 G_TYPE_NONE, 0);
721
722 /**
723 * GtkFileChooser::update-preview
724 * @chooser: the object which received the signal.
725 *
726 * This signal is emitted when the preview in a file chooser should be
727 * regenerated. For example, this can happen when the currently selected file
728 * changes. You should use this signal if you want your file chooser to have
729 * a preview widget.
730 *
731 * Once you have installed a preview widget with
732 * gtk_file_chooser_set_preview_widget(), you should update it when this
733 * signal is emitted. You can use the functions
734 * gtk_file_chooser_get_preview_filename() or
735 * gtk_file_chooser_get_preview_uri() to get the name of the file to preview.
736 * Your widget may not be able to preview all kinds of files; your callback
737 * must call gtk_file_chooser_set_preview_widget_active() to inform the file
738 * chooser about whether the preview was generated successfully or not.
739 *
740 * Please see the example code in <xref linkend="gtkfilechooser-preview"/>.
741 *
742 * See also: gtk_file_chooser_set_preview_widget(),
743 * gtk_file_chooser_set_preview_widget_active(),
744 * gtk_file_chooser_set_use_preview_label(),
745 * gtk_file_chooser_get_preview_filename(),
746 * gtk_file_chooser_get_preview_uri().
747 */
748 g_signal_new (I_("update-preview"),
749 iface_type,
750 G_SIGNAL_RUN_LAST,
751 G_STRUCT_OFFSET (GtkFileChooserIface, update_preview),
752 NULL, NULL,
753 g_cclosure_marshal_VOID__VOID,
754 G_TYPE_NONE, 0);
755
756 /**
757 * GtkFileChooser::file-activated
758 * @chooser: the object which received the signal.
759 *
760 * This signal is emitted when the user "activates" a file in the file
761 * chooser. This can happen by double-clicking on a file in the file list, or
762 * by pressing <keycap>Enter</keycap>.
763 *
764 * Normally you do not need to connect to this signal. It is used internally
765 * by #GtkFileChooserDialog to know when to activate the default button in the
766 * dialog.
767 *
768 * See also: gtk_file_chooser_get_filename(),
769 * gtk_file_chooser_get_filenames(), gtk_file_chooser_get_uri(),
770 * gtk_file_chooser_get_uris().
771 */
772 g_signal_new (I_("file-activated"),
773 iface_type,
774 G_SIGNAL_RUN_LAST,
775 G_STRUCT_OFFSET (GtkFileChooserIface, file_activated),
776 NULL, NULL,
777 g_cclosure_marshal_VOID__VOID,
778 G_TYPE_NONE, 0);
779
780 /**
781 * GtkFileChooser::confirm-overwrite:
782 * @chooser: the object which received the signal.
783 *
784 * This signal gets emitted whenever it is appropriate to present a
785 * confirmation dialog when the user has selected a file name that
786 * already exists. The signal only gets emitted when the file
787 * chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode.
788 *
789 * Most applications just need to turn on the
790 * #GtkFileChooser:do-overwrite-confirmation property (or call the
791 * gtk_file_chooser_set_do_overwrite_confirmation() function), and
792 * they will automatically get a stock confirmation dialog.
793 * Applications which need to customize this behavior should do
794 * that, and also connect to the #GtkFileChooser::confirm-overwrite
795 * signal.
796 *
797 * A signal handler for this signal must return a
798 * #GtkFileChooserConfirmation value, which indicates the action to
799 * take. If the handler determines that the user wants to select a
800 * different filename, it should return
801 * %GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN. If it determines
802 * that the user is satisfied with his choice of file name, it
803 * should return %GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME.
804 * On the other hand, if it determines that the stock confirmation
805 * dialog should be used, it should return
806 * %GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM. The following example
807 * illustrates this.
808 * <example id="gtkfilechooser-confirmation">
809 * <title>Custom confirmation</title>
810 * <programlisting>
811 * static GtkFileChooserConfirmation
812 * confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data)
813 * {
814 * char *uri;
815 *
816 * uri = gtk_file_chooser_get_uri (chooser);
817 *
818 * if (is_uri_read_only (uri))
819 * {
820 * if (user_wants_to_replace_read_only_file (uri))
821 * return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME;
822 * else
823 * return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN;
824 * } else
825 * return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; // fall back to the default dialog
826 * }
827 *
828 * ...
829 *
830 * chooser = gtk_file_chooser_dialog_new (...);
831 *
832 * gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
833 * g_signal_connect (chooser, "confirm-overwrite",
834 * G_CALLBACK (confirm_overwrite_callback), NULL);
835 *
836 * if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT)
837 * save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser));
838 *
839 * gtk_widget_destroy (chooser);
840 * </programlisting>
841 * </example>
842 *
843 * Returns: a #GtkFileChooserConfirmation value that indicates which
844 * action to take after emitting the signal.
845 *
846 * Since: 2.8
847 */
848 g_signal_new (I_("confirm-overwrite"),
849 iface_type,
850 G_SIGNAL_RUN_LAST,
851 G_STRUCT_OFFSET (GtkFileChooserIface, confirm_overwrite),
852 confirm_overwrite_accumulator, NULL,
853 _gtk_marshal_ENUM__VOID,
854 GTK_TYPE_FILE_CHOOSER_CONFIRMATION, 0);
855
856 g_object_interface_install_property (g_iface,
857 g_param_spec_enum ("action",
858 P_("Action"),
859 P_("The type of operation that the file selector is performing"),
860 GTK_TYPE_FILE_CHOOSER_ACTION,
861 GTK_FILE_CHOOSER_ACTION_OPEN,
862 GTK_PARAM_READWRITE));
863 g_object_interface_install_property (g_iface,
864 g_param_spec_string ("file-system-backend",
865 P_("File System Backend"),
866 P_("Name of file system backend to use"),
867 NULL,
868 GTK_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
869 g_object_interface_install_property (g_iface,
870 g_param_spec_object ("filter",
871 P_("Filter"),
872 P_("The current filter for selecting which files are displayed"),
873 GTK_TYPE_FILE_FILTER,
874 GTK_PARAM_READWRITE));
875 g_object_interface_install_property (g_iface,
876 g_param_spec_boolean ("local-only",
877 P_("Local Only"),
878 P_("Whether the selected file(s) should be limited to local file: URLs"),
879 TRUE,
880 GTK_PARAM_READWRITE));
881 g_object_interface_install_property (g_iface,
882 g_param_spec_object ("preview-widget",
883 P_("Preview widget"),
884 P_("Application supplied widget for custom previews."),
885 GTK_TYPE_WIDGET,
886 GTK_PARAM_READWRITE));
887 g_object_interface_install_property (g_iface,
888 g_param_spec_boolean ("preview-widget-active",
889 P_("Preview Widget Active"),
890 P_("Whether the application supplied widget for custom previews should be shown."),
891 TRUE,
892 GTK_PARAM_READWRITE));
893 g_object_interface_install_property (g_iface,
894 g_param_spec_boolean ("use-preview-label",
895 P_("Use Preview Label"),
896 P_("Whether to display a stock label with the name of the previewed file."),
897 TRUE,
898 GTK_PARAM_READWRITE));
899 g_object_interface_install_property (g_iface,
900 g_param_spec_object ("extra-widget",
901 P_("Extra widget"),
902 P_("Application supplied widget for extra options."),
903 GTK_TYPE_WIDGET,
904 GTK_PARAM_READWRITE));
905 g_object_interface_install_property (g_iface,
906 g_param_spec_boolean ("select-multiple",
907 P_("Select Multiple"),
908 P_("Whether to allow multiple files to be selected"),
909 FALSE,
910 GTK_PARAM_READWRITE));
911
912 g_object_interface_install_property (g_iface,
913 g_param_spec_boolean ("show-hidden",
914 P_("Show Hidden"),
915 P_("Whether the hidden files and folders should be displayed"),
916 FALSE,
917 GTK_PARAM_READWRITE));
918
919 /**
920 * GtkFileChooser:do-overwrite-confirmation:
921 *
922 * Whether a file chooser in %GTK_FILE_CHOOSER_ACTION_SAVE mode
923 * will present an overwrite confirmation dialog if the user
924 * selects a file name that already exists.
925 *
926 * Since: 2.8
927 */
928 g_object_interface_install_property (g_iface,
929 g_param_spec_boolean ("do-overwrite-confirmation",
930 P_("Do overwrite confirmation"),
931 P_("Whether a file chooser in save mode "
932 "will present an overwrite confirmation dialog "
933 "if necessary."),
934 FALSE,
935 GTK_PARAM_READWRITE));
936
937 /**
938 * GtkFileChooser:create-folders:
939 *
940 * Whether a file chooser not in %GTK_FILE_CHOOSER_ACTION_OPEN mode
941 * will offer the user to create new folders.
942 *
943 * Since: 2.18
944 */
945 g_object_interface_install_property (g_iface,
946 g_param_spec_boolean ("create-folders",
947 P_("Allow folders creation"),
948 P_("Whether a file chooser not in open mode "
949 "will offer the user to create new folders."),
950 TRUE,
951 GTK_PARAM_READWRITE));
952 }
953
954 /**
955 * gtk_file_chooser_error_quark:
956 *
957 * Registers an error quark for #GtkFileChooser if necessary.
958 *
959 * Return value: The error quark used for #GtkFileChooser errors.
960 *
961 * Since: 2.4
962 **/
963 GQuark
gtk_file_chooser_error_quark(void)964 gtk_file_chooser_error_quark (void)
965 {
966 return g_quark_from_static_string ("gtk-file-chooser-error-quark");
967 }
968
969 /**
970 * gtk_file_chooser_set_action:
971 * @chooser: a #GtkFileChooser
972 * @action: the action that the file selector is performing
973 *
974 * Sets the type of operation that the chooser is performing; the
975 * user interface is adapted to suit the selected action. For example,
976 * an option to create a new folder might be shown if the action is
977 * %GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is
978 * %GTK_FILE_CHOOSER_ACTION_OPEN.
979 *
980 * Since: 2.4
981 **/
982 void
gtk_file_chooser_set_action(GtkFileChooser * chooser,GtkFileChooserAction action)983 gtk_file_chooser_set_action (GtkFileChooser *chooser,
984 GtkFileChooserAction action)
985 {
986 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
987
988 g_object_set (chooser, "action", action, NULL);
989 }
990
991 /**
992 * gtk_file_chooser_get_action:
993 * @chooser: a #GtkFileChooser
994 *
995 * Gets the type of operation that the file chooser is performing; see
996 * gtk_file_chooser_set_action().
997 *
998 * Return value: the action that the file selector is performing
999 *
1000 * Since: 2.4
1001 **/
1002 GtkFileChooserAction
gtk_file_chooser_get_action(GtkFileChooser * chooser)1003 gtk_file_chooser_get_action (GtkFileChooser *chooser)
1004 {
1005 GtkFileChooserAction action;
1006
1007 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1008
1009 g_object_get (chooser, "action", &action, NULL);
1010
1011 return action;
1012 }
1013
1014 /**
1015 * gtk_file_chooser_set_local_only:
1016 * @chooser: a #GtkFileChooser
1017 * @local_only: %TRUE if only local files can be selected
1018 *
1019 * Sets whether only local files can be selected in the
1020 * file selector. If @local_only is %TRUE (the default),
1021 * then the selected file are files are guaranteed to be
1022 * accessible through the operating systems native file
1023 * file system and therefore the application only
1024 * needs to worry about the filename functions in
1025 * #GtkFileChooser, like gtk_file_chooser_get_filename(),
1026 * rather than the URI functions like
1027 * gtk_file_chooser_get_uri(),
1028 *
1029 * On some systems non-native files may still be
1030 * available using the native filesystem via a userspace
1031 * filesystem (FUSE).
1032 *
1033 * Since: 2.4
1034 **/
1035 void
gtk_file_chooser_set_local_only(GtkFileChooser * chooser,gboolean local_only)1036 gtk_file_chooser_set_local_only (GtkFileChooser *chooser,
1037 gboolean local_only)
1038 {
1039 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1040
1041 g_object_set (chooser, "local-only", local_only, NULL);
1042 }
1043
1044 /**
1045 * gtk_file_chooser_get_local_only:
1046 * @chooser: a #GtkFileChooser
1047 *
1048 * Gets whether only local files can be selected in the
1049 * file selector. See gtk_file_chooser_set_local_only()
1050 *
1051 * Return value: %TRUE if only local files can be selected.
1052 *
1053 * Since: 2.4
1054 **/
1055 gboolean
gtk_file_chooser_get_local_only(GtkFileChooser * chooser)1056 gtk_file_chooser_get_local_only (GtkFileChooser *chooser)
1057 {
1058 gboolean local_only;
1059
1060 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1061
1062 g_object_get (chooser, "local-only", &local_only, NULL);
1063
1064 return local_only;
1065 }
1066
1067 /**
1068 * gtk_file_chooser_set_select_multiple:
1069 * @chooser: a #GtkFileChooser
1070 * @select_multiple: %TRUE if multiple files can be selected.
1071 *
1072 * Sets whether multiple files can be selected in the file selector. This is
1073 * only relevant if the action is set to be %GTK_FILE_CHOOSER_ACTION_OPEN or
1074 * %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
1075 *
1076 * Since: 2.4
1077 **/
1078 void
gtk_file_chooser_set_select_multiple(GtkFileChooser * chooser,gboolean select_multiple)1079 gtk_file_chooser_set_select_multiple (GtkFileChooser *chooser,
1080 gboolean select_multiple)
1081 {
1082 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1083
1084 g_object_set (chooser, "select-multiple", select_multiple, NULL);
1085 }
1086
1087 /**
1088 * gtk_file_chooser_get_select_multiple:
1089 * @chooser: a #GtkFileChooser
1090 *
1091 * Gets whether multiple files can be selected in the file
1092 * selector. See gtk_file_chooser_set_select_multiple().
1093 *
1094 * Return value: %TRUE if multiple files can be selected.
1095 *
1096 * Since: 2.4
1097 **/
1098 gboolean
gtk_file_chooser_get_select_multiple(GtkFileChooser * chooser)1099 gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser)
1100 {
1101 gboolean select_multiple;
1102
1103 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1104
1105 g_object_get (chooser, "select-multiple", &select_multiple, NULL);
1106
1107 return select_multiple;
1108 }
1109
1110 /**
1111 * gtk_file_chooser_set_create_folders:
1112 * @chooser: a #GtkFileChooser
1113 * @create_folders: %TRUE if the New Folder button should be displayed
1114 *
1115 * Sets whether file choser will offer to create new folders.
1116 * This is only relevant if the action is not set to be
1117 * %GTK_FILE_CHOOSER_ACTION_OPEN.
1118 *
1119 * Since: 2.18
1120 **/
1121 void
gtk_file_chooser_set_create_folders(GtkFileChooser * chooser,gboolean create_folders)1122 gtk_file_chooser_set_create_folders (GtkFileChooser *chooser,
1123 gboolean create_folders)
1124 {
1125 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1126
1127 g_object_set (chooser, "create-folders", create_folders, NULL);
1128 }
1129
1130 /**
1131 * gtk_file_chooser_get_create_folders:
1132 * @chooser: a #GtkFileChooser
1133 *
1134 * Gets whether file choser will offer to create new folders.
1135 * See gtk_file_chooser_set_create_folders().
1136 *
1137 * Return value: %TRUE if the New Folder button should be displayed.
1138 *
1139 * Since: 2.18
1140 **/
1141 gboolean
gtk_file_chooser_get_create_folders(GtkFileChooser * chooser)1142 gtk_file_chooser_get_create_folders (GtkFileChooser *chooser)
1143 {
1144 gboolean create_folders;
1145
1146 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1147
1148 g_object_get (chooser, "create-folders", &create_folders, NULL);
1149
1150 return create_folders;
1151 }
1152
1153 /**
1154 * gtk_file_chooser_get_filename:
1155 * @chooser: a #GtkFileChooser
1156 *
1157 * Gets the filename for the currently selected file in
1158 * the file selector. If multiple files are selected,
1159 * one of the filenames will be returned at random.
1160 *
1161 * If the file chooser is in folder mode, this function returns the selected
1162 * folder.
1163 *
1164 * Return value: (type filename): The currently selected filename, or %NULL
1165 * if no file is selected, or the selected file can't
1166 * be represented with a local filename. Free with g_free().
1167 *
1168 * Since: 2.4
1169 **/
1170 gchar *
gtk_file_chooser_get_filename(GtkFileChooser * chooser)1171 gtk_file_chooser_get_filename (GtkFileChooser *chooser)
1172 {
1173 GFile *file;
1174 gchar *result = NULL;
1175
1176 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1177
1178 file = gtk_file_chooser_get_file (chooser);
1179
1180 if (file)
1181 {
1182 result = g_file_get_path (file);
1183 g_object_unref (file);
1184 }
1185
1186 return result;
1187 }
1188
1189 /**
1190 * gtk_file_chooser_set_filename:
1191 * @chooser: a #GtkFileChooser
1192 * @filename: (type filename): the filename to set as current
1193 *
1194 * Sets @filename as the current filename for the file chooser, by changing
1195 * to the file's parent folder and actually selecting the file in list. If
1196 * the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name
1197 * will also appear in the dialog's file name entry.
1198 *
1199 * If the file name isn't in the current folder of @chooser, then the current
1200 * folder of @chooser will be changed to the folder containing @filename. This
1201 * is equivalent to a sequence of gtk_file_chooser_unselect_all() followed by
1202 * gtk_file_chooser_select_filename().
1203 *
1204 * Note that the file must exist, or nothing will be done except
1205 * for the directory change.
1206 *
1207 * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
1208 * you should use this function if you already have a file name to which the
1209 * user may save; for example, when the user opens an existing file and then
1210 * does <guimenuitem>File/Save As...</guimenuitem> on it. If you don't have
1211 * a file name already — for example, if the user just created a new
1212 * file and is saving it for the first time, do not call this function.
1213 * Instead, use something similar to this:
1214 * |[
1215 * if (document_is_new)
1216 * {
1217 * /* the user just created a new document */
1218 * gtk_file_chooser_set_current_folder (chooser, default_folder_for_saving);
1219 * gtk_file_chooser_set_current_name (chooser, "Untitled document");
1220 * }
1221 * else
1222 * {
1223 * /* the user edited an existing document */
1224 * gtk_file_chooser_set_filename (chooser, existing_filename);
1225 * }
1226 * ]|
1227 *
1228 * Return value: %TRUE if both the folder could be changed and the file was
1229 * selected successfully, %FALSE otherwise.
1230 *
1231 * Since: 2.4
1232 **/
1233 gboolean
gtk_file_chooser_set_filename(GtkFileChooser * chooser,const gchar * filename)1234 gtk_file_chooser_set_filename (GtkFileChooser *chooser,
1235 const gchar *filename)
1236 {
1237 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1238
1239 gtk_file_chooser_unselect_all (chooser);
1240 return gtk_file_chooser_select_filename (chooser, filename);
1241 }
1242
1243 /**
1244 * gtk_file_chooser_select_filename:
1245 * @chooser: a #GtkFileChooser
1246 * @filename: (type filename): the filename to select
1247 *
1248 * Selects a filename. If the file name isn't in the current
1249 * folder of @chooser, then the current folder of @chooser will
1250 * be changed to the folder containing @filename.
1251 *
1252 * Return value: %TRUE if both the folder could be changed and the file was
1253 * selected successfully, %FALSE otherwise.
1254 *
1255 * Since: 2.4
1256 **/
1257 gboolean
gtk_file_chooser_select_filename(GtkFileChooser * chooser,const gchar * filename)1258 gtk_file_chooser_select_filename (GtkFileChooser *chooser,
1259 const gchar *filename)
1260 {
1261 GFile *file;
1262 gboolean result;
1263
1264 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1265 g_return_val_if_fail (filename != NULL, FALSE);
1266
1267 file = g_file_new_for_path (filename);
1268 result = gtk_file_chooser_select_file (chooser, file, NULL);
1269 g_object_unref (file);
1270
1271 return result;
1272 }
1273
1274 /**
1275 * gtk_file_chooser_unselect_filename:
1276 * @chooser: a #GtkFileChooser
1277 * @filename: (type filename): the filename to unselect
1278 *
1279 * Unselects a currently selected filename. If the filename
1280 * is not in the current directory, does not exist, or
1281 * is otherwise not currently selected, does nothing.
1282 *
1283 * Since: 2.4
1284 **/
1285 void
gtk_file_chooser_unselect_filename(GtkFileChooser * chooser,const char * filename)1286 gtk_file_chooser_unselect_filename (GtkFileChooser *chooser,
1287 const char *filename)
1288 {
1289 GFile *file;
1290
1291 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1292 g_return_if_fail (filename != NULL);
1293
1294 file = g_file_new_for_path (filename);
1295 gtk_file_chooser_unselect_file (chooser, file);
1296 g_object_unref (file);
1297 }
1298
1299 /* Converts a list of GFile* to a list of strings using the specified function */
1300 static GSList *
files_to_strings(GSList * files,gchar * (* convert_func)(GFile * file))1301 files_to_strings (GSList *files,
1302 gchar * (*convert_func) (GFile *file))
1303 {
1304 GSList *strings;
1305
1306 strings = NULL;
1307
1308 for (; files; files = files->next)
1309 {
1310 GFile *file;
1311 gchar *string;
1312
1313 file = files->data;
1314 string = (* convert_func) (file);
1315
1316 if (string)
1317 strings = g_slist_prepend (strings, string);
1318 }
1319
1320 return g_slist_reverse (strings);
1321 }
1322
1323 static gchar *
file_to_uri_with_native_path(GFile * file)1324 file_to_uri_with_native_path (GFile *file)
1325 {
1326 gchar *result = NULL;
1327 gchar *native;
1328
1329 native = g_file_get_path (file);
1330 if (native)
1331 {
1332 result = g_filename_to_uri (native, NULL, NULL); /* NULL-GError */
1333 g_free (native);
1334 }
1335
1336 return result;
1337 }
1338
1339 /**
1340 * gtk_file_chooser_get_filenames:
1341 * @chooser: a #GtkFileChooser
1342 *
1343 * Lists all the selected files and subfolders in the current folder of
1344 * @chooser. The returned names are full absolute paths. If files in the current
1345 * folder cannot be represented as local filenames they will be ignored. (See
1346 * gtk_file_chooser_get_uris())
1347 *
1348 * Return value: (element-type filename) (transfer full): a #GSList
1349 * containing the filenames of all selected files and subfolders in
1350 * the current folder. Free the returned list with g_slist_free(),
1351 * and the filenames with g_free().
1352 *
1353 * Since: 2.4
1354 **/
1355 GSList *
gtk_file_chooser_get_filenames(GtkFileChooser * chooser)1356 gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
1357 {
1358 GSList *files, *result;
1359
1360 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1361
1362 files = gtk_file_chooser_get_files (chooser);
1363
1364 result = files_to_strings (files, g_file_get_path);
1365 g_slist_foreach (files, (GFunc) g_object_unref, NULL);
1366 g_slist_free (files);
1367
1368 return result;
1369 }
1370
1371 /**
1372 * gtk_file_chooser_set_current_folder:
1373 * @chooser: a #GtkFileChooser
1374 * @filename: (type filename): the full path of the new current folder
1375 *
1376 * Sets the current folder for @chooser from a local filename.
1377 * The user will be shown the full contents of the current folder,
1378 * plus user interface elements for navigating to other folders.
1379 *
1380 * Return value: %TRUE if the folder could be changed successfully, %FALSE
1381 * otherwise.
1382 *
1383 * Since: 2.4
1384 **/
1385 gboolean
gtk_file_chooser_set_current_folder(GtkFileChooser * chooser,const gchar * filename)1386 gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
1387 const gchar *filename)
1388 {
1389 GFile *file;
1390 gboolean result;
1391
1392 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1393 g_return_val_if_fail (filename != NULL, FALSE);
1394
1395 file = g_file_new_for_path (filename);
1396 result = gtk_file_chooser_set_current_folder_file (chooser, file, NULL);
1397 g_object_unref (file);
1398
1399 return result;
1400 }
1401
1402 /**
1403 * gtk_file_chooser_get_current_folder:
1404 * @chooser: a #GtkFileChooser
1405 *
1406 * Gets the current folder of @chooser as a local filename.
1407 * See gtk_file_chooser_set_current_folder().
1408 *
1409 * Note that this is the folder that the file chooser is currently displaying
1410 * (e.g. "/home/username/Documents"), which is <emphasis>not the same</emphasis>
1411 * as the currently-selected folder if the chooser is in
1412 * %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER mode
1413 * (e.g. "/home/username/Documents/selected-folder/". To get the
1414 * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the
1415 * usual way to get the selection.
1416 *
1417 * Return value: (type filename): the full path of the current folder,
1418 * or %NULL if the current path cannot be represented as a local
1419 * filename. Free with g_free(). This function will also return
1420 * %NULL if the file chooser was unable to load the last folder that
1421 * was requested from it; for example, as would be for calling
1422 * gtk_file_chooser_set_current_folder() on a nonexistent folder.
1423 *
1424 * Since: 2.4
1425 **/
1426 gchar *
gtk_file_chooser_get_current_folder(GtkFileChooser * chooser)1427 gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
1428 {
1429 GFile *file;
1430 gchar *filename;
1431
1432 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1433
1434 file = gtk_file_chooser_get_current_folder_file (chooser);
1435 if (!file)
1436 return NULL;
1437
1438 filename = g_file_get_path (file);
1439 g_object_unref (file);
1440
1441 return filename;
1442 }
1443
1444 /**
1445 * gtk_file_chooser_set_current_name:
1446 * @chooser: a #GtkFileChooser
1447 * @name: (type filename): the filename to use, as a UTF-8 string
1448 *
1449 * Sets the current name in the file selector, as if entered
1450 * by the user. Note that the name passed in here is a UTF-8
1451 * string rather than a filename. This function is meant for
1452 * such uses as a suggested name in a "Save As..." dialog.
1453 *
1454 * If you want to preselect a particular existing file, you should use
1455 * gtk_file_chooser_set_filename() or gtk_file_chooser_set_uri() instead.
1456 * Please see the documentation for those functions for an example of using
1457 * gtk_file_chooser_set_current_name() as well.
1458 *
1459 * Since: 2.4
1460 **/
1461 void
gtk_file_chooser_set_current_name(GtkFileChooser * chooser,const gchar * name)1462 gtk_file_chooser_set_current_name (GtkFileChooser *chooser,
1463 const gchar *name)
1464 {
1465 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1466 g_return_if_fail (name != NULL);
1467
1468 GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_name (chooser, name);
1469 }
1470
1471 /**
1472 * gtk_file_chooser_get_uri:
1473 * @chooser: a #GtkFileChooser
1474 *
1475 * Gets the URI for the currently selected file in
1476 * the file selector. If multiple files are selected,
1477 * one of the filenames will be returned at random.
1478 *
1479 * If the file chooser is in folder mode, this function returns the selected
1480 * folder.
1481 *
1482 * Return value: The currently selected URI, or %NULL
1483 * if no file is selected. If gtk_file_chooser_set_local_only() is set to %TRUE
1484 * (the default) a local URI will be returned for any FUSE locations.
1485 * Free with g_free()
1486 *
1487 * Since: 2.4
1488 **/
1489 gchar *
gtk_file_chooser_get_uri(GtkFileChooser * chooser)1490 gtk_file_chooser_get_uri (GtkFileChooser *chooser)
1491 {
1492 GFile *file;
1493 gchar *result = NULL;
1494
1495 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1496
1497 file = gtk_file_chooser_get_file (chooser);
1498 if (file)
1499 {
1500 if (gtk_file_chooser_get_local_only (chooser))
1501 {
1502 gchar *local = g_file_get_path (file);
1503 if (local)
1504 {
1505 result = g_filename_to_uri (local, NULL, NULL);
1506 g_free (local);
1507 }
1508 }
1509 else
1510 {
1511 result = g_file_get_uri (file);
1512 }
1513 g_object_unref (file);
1514 }
1515
1516 return result;
1517 }
1518
1519 /**
1520 * gtk_file_chooser_set_uri:
1521 * @chooser: a #GtkFileChooser
1522 * @uri: the URI to set as current
1523 *
1524 * Sets the file referred to by @uri as the current file for the file chooser,
1525 * by changing to the URI's parent folder and actually selecting the URI in the
1526 * list. If the @chooser is %GTK_FILE_CHOOSER_ACTION_SAVE mode, the URI's base
1527 * name will also appear in the dialog's file name entry.
1528 *
1529 * If the URI isn't in the current folder of @chooser, then the current folder
1530 * of @chooser will be changed to the folder containing @uri. This is equivalent
1531 * to a sequence of gtk_file_chooser_unselect_all() followed by
1532 * gtk_file_chooser_select_uri().
1533 *
1534 * Note that the URI must exist, or nothing will be done except for the
1535 * directory change.
1536 * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
1537 * you should use this function if you already have a file name to which the
1538 * user may save; for example, when the user opens an existing file and then
1539 * does <guimenuitem>File/Save As...</guimenuitem> on it. If you don't have
1540 * a file name already — for example, if the user just created a new
1541 * file and is saving it for the first time, do not call this function.
1542 * Instead, use something similar to this:
1543 * |[
1544 * if (document_is_new)
1545 * {
1546 * /* the user just created a new document */
1547 * gtk_file_chooser_set_current_folder_uri (chooser, default_folder_for_saving);
1548 * gtk_file_chooser_set_current_name (chooser, "Untitled document");
1549 * }
1550 * else
1551 * {
1552 * /* the user edited an existing document */
1553 * gtk_file_chooser_set_uri (chooser, existing_uri);
1554 * }
1555 * ]|
1556 *
1557 * Return value: %TRUE if both the folder could be changed and the URI was
1558 * selected successfully, %FALSE otherwise.
1559 *
1560 * Since: 2.4
1561 **/
1562 gboolean
gtk_file_chooser_set_uri(GtkFileChooser * chooser,const char * uri)1563 gtk_file_chooser_set_uri (GtkFileChooser *chooser,
1564 const char *uri)
1565 {
1566 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1567
1568 gtk_file_chooser_unselect_all (chooser);
1569 return gtk_file_chooser_select_uri (chooser, uri);
1570 }
1571
1572 /**
1573 * gtk_file_chooser_select_uri:
1574 * @chooser: a #GtkFileChooser
1575 * @uri: the URI to select
1576 *
1577 * Selects the file to by @uri. If the URI doesn't refer to a
1578 * file in the current folder of @chooser, then the current folder of
1579 * @chooser will be changed to the folder containing @filename.
1580 *
1581 * Return value: %TRUE if both the folder could be changed and the URI was
1582 * selected successfully, %FALSE otherwise.
1583 *
1584 * Since: 2.4
1585 **/
1586 gboolean
gtk_file_chooser_select_uri(GtkFileChooser * chooser,const char * uri)1587 gtk_file_chooser_select_uri (GtkFileChooser *chooser,
1588 const char *uri)
1589 {
1590 GFile *file;
1591 gboolean result;
1592
1593 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1594 g_return_val_if_fail (uri != NULL, FALSE);
1595
1596 file = g_file_new_for_uri (uri);
1597 result = gtk_file_chooser_select_file (chooser, file, NULL);
1598 g_object_unref (file);
1599
1600 return result;
1601 }
1602
1603 /**
1604 * gtk_file_chooser_unselect_uri:
1605 * @chooser: a #GtkFileChooser
1606 * @uri: the URI to unselect
1607 *
1608 * Unselects the file referred to by @uri. If the file
1609 * is not in the current directory, does not exist, or
1610 * is otherwise not currently selected, does nothing.
1611 *
1612 * Since: 2.4
1613 **/
1614 void
gtk_file_chooser_unselect_uri(GtkFileChooser * chooser,const char * uri)1615 gtk_file_chooser_unselect_uri (GtkFileChooser *chooser,
1616 const char *uri)
1617 {
1618 GFile *file;
1619
1620 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1621 g_return_if_fail (uri != NULL);
1622
1623 file = g_file_new_for_uri (uri);
1624 gtk_file_chooser_unselect_file (chooser, file);
1625 g_object_unref (file);
1626 }
1627
1628 /**
1629 * gtk_file_chooser_select_all:
1630 * @chooser: a #GtkFileChooser
1631 *
1632 * Selects all the files in the current folder of a file chooser.
1633 *
1634 * Since: 2.4
1635 **/
1636 void
gtk_file_chooser_select_all(GtkFileChooser * chooser)1637 gtk_file_chooser_select_all (GtkFileChooser *chooser)
1638 {
1639 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1640
1641 GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_all (chooser);
1642 }
1643
1644 /**
1645 * gtk_file_chooser_unselect_all:
1646 * @chooser: a #GtkFileChooser
1647 *
1648 * Unselects all the files in the current folder of a file chooser.
1649 *
1650 * Since: 2.4
1651 **/
1652 void
gtk_file_chooser_unselect_all(GtkFileChooser * chooser)1653 gtk_file_chooser_unselect_all (GtkFileChooser *chooser)
1654 {
1655
1656 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1657
1658 GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_all (chooser);
1659 }
1660
1661 /**
1662 * gtk_file_chooser_get_uris:
1663 * @chooser: a #GtkFileChooser
1664 *
1665 * Lists all the selected files and subfolders in the current folder of
1666 * @chooser. The returned names are full absolute URIs.
1667 *
1668 * Return value: (element-type utf8) (transfer full): a #GSList containing the URIs of all selected
1669 * files and subfolders in the current folder. Free the returned list
1670 * with g_slist_free(), and the filenames with g_free().
1671 *
1672 * Since: 2.4
1673 **/
1674 GSList *
gtk_file_chooser_get_uris(GtkFileChooser * chooser)1675 gtk_file_chooser_get_uris (GtkFileChooser *chooser)
1676 {
1677 GSList *files, *result;
1678
1679 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1680
1681 files = gtk_file_chooser_get_files (chooser);
1682
1683 if (gtk_file_chooser_get_local_only (chooser))
1684 result = files_to_strings (files, file_to_uri_with_native_path);
1685 else
1686 result = files_to_strings (files, g_file_get_uri);
1687
1688 g_slist_foreach (files, (GFunc) g_object_unref, NULL);
1689 g_slist_free (files);
1690
1691 return result;
1692 }
1693
1694 /**
1695 * gtk_file_chooser_set_current_folder_uri:
1696 * @chooser: a #GtkFileChooser
1697 * @uri: the URI for the new current folder
1698 *
1699 * Sets the current folder for @chooser from an URI.
1700 * The user will be shown the full contents of the current folder,
1701 * plus user interface elements for navigating to other folders.
1702 *
1703 * Return value: %TRUE if the folder could be changed successfully, %FALSE
1704 * otherwise.
1705 *
1706 * Since: 2.4
1707 **/
1708 gboolean
gtk_file_chooser_set_current_folder_uri(GtkFileChooser * chooser,const gchar * uri)1709 gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser,
1710 const gchar *uri)
1711 {
1712 GFile *file;
1713 gboolean result;
1714
1715 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1716 g_return_val_if_fail (uri != NULL, FALSE);
1717
1718 file = g_file_new_for_uri (uri);
1719 result = gtk_file_chooser_set_current_folder_file (chooser, file, NULL);
1720 g_object_unref (file);
1721
1722 return result;
1723 }
1724
1725 /**
1726 * gtk_file_chooser_get_current_folder_uri:
1727 * @chooser: a #GtkFileChooser
1728 *
1729 * Gets the current folder of @chooser as an URI.
1730 * See gtk_file_chooser_set_current_folder_uri().
1731 *
1732 * Note that this is the folder that the file chooser is currently displaying
1733 * (e.g. "file:///home/username/Documents"), which is <emphasis>not the same</emphasis>
1734 * as the currently-selected folder if the chooser is in
1735 * %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER mode
1736 * (e.g. "file:///home/username/Documents/selected-folder/". To get the
1737 * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the
1738 * usual way to get the selection.
1739 *
1740 * Return value: the URI for the current folder. Free with g_free(). This
1741 * function will also return %NULL if the file chooser was unable to load the
1742 * last folder that was requested from it; for example, as would be for calling
1743 * gtk_file_chooser_set_current_folder_uri() on a nonexistent folder.
1744 *
1745 * Since: 2.4
1746 */
1747 gchar *
gtk_file_chooser_get_current_folder_uri(GtkFileChooser * chooser)1748 gtk_file_chooser_get_current_folder_uri (GtkFileChooser *chooser)
1749 {
1750 GFile *file;
1751 gchar *uri;
1752
1753 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1754
1755 file = gtk_file_chooser_get_current_folder_file (chooser);
1756 if (!file)
1757 return NULL;
1758
1759 uri = g_file_get_uri (file);
1760 g_object_unref (file);
1761
1762 return uri;
1763 }
1764
1765 /**
1766 * gtk_file_chooser_set_current_folder_file:
1767 * @chooser: a #GtkFileChooser
1768 * @file: the #GFile for the new folder
1769 * @error: (allow-none): location to store error, or %NULL.
1770 *
1771 * Sets the current folder for @chooser from a #GFile.
1772 * Internal function, see gtk_file_chooser_set_current_folder_uri().
1773 *
1774 * Return value: %TRUE if the folder could be changed successfully, %FALSE
1775 * otherwise.
1776 *
1777 * Since: 2.14
1778 **/
1779 gboolean
gtk_file_chooser_set_current_folder_file(GtkFileChooser * chooser,GFile * file,GError ** error)1780 gtk_file_chooser_set_current_folder_file (GtkFileChooser *chooser,
1781 GFile *file,
1782 GError **error)
1783 {
1784 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1785 g_return_val_if_fail (G_IS_FILE (file), FALSE);
1786 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1787
1788 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_folder (chooser, file, error);
1789 }
1790
1791 /**
1792 * gtk_file_chooser_get_current_folder_file:
1793 * @chooser: a #GtkFileChooser
1794 *
1795 * Gets the current folder of @chooser as #GFile.
1796 * See gtk_file_chooser_get_current_folder_uri().
1797 *
1798 * Return value: (transfer full): the #GFile for the current folder.
1799 *
1800 * Since: 2.14
1801 */
1802 GFile *
gtk_file_chooser_get_current_folder_file(GtkFileChooser * chooser)1803 gtk_file_chooser_get_current_folder_file (GtkFileChooser *chooser)
1804 {
1805 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1806
1807 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_folder (chooser);
1808 }
1809
1810 /**
1811 * gtk_file_chooser_select_file:
1812 * @chooser: a #GtkFileChooser
1813 * @file: the file to select
1814 * @error: (allow-none): location to store error, or %NULL
1815 *
1816 * Selects the file referred to by @file. An internal function. See
1817 * _gtk_file_chooser_select_uri().
1818 *
1819 * Return value: %TRUE if both the folder could be changed and the path was
1820 * selected successfully, %FALSE otherwise.
1821 *
1822 * Since: 2.14
1823 **/
1824 gboolean
gtk_file_chooser_select_file(GtkFileChooser * chooser,GFile * file,GError ** error)1825 gtk_file_chooser_select_file (GtkFileChooser *chooser,
1826 GFile *file,
1827 GError **error)
1828 {
1829 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1830 g_return_val_if_fail (G_IS_FILE (file), FALSE);
1831 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1832
1833 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_file (chooser, file, error);
1834 }
1835
1836 /**
1837 * gtk_file_chooser_unselect_file:
1838 * @chooser: a #GtkFileChooser
1839 * @file: a #GFile
1840 *
1841 * Unselects the file referred to by @file. If the file is not in the current
1842 * directory, does not exist, or is otherwise not currently selected, does nothing.
1843 *
1844 * Since: 2.14
1845 **/
1846 void
gtk_file_chooser_unselect_file(GtkFileChooser * chooser,GFile * file)1847 gtk_file_chooser_unselect_file (GtkFileChooser *chooser,
1848 GFile *file)
1849 {
1850 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
1851 g_return_if_fail (G_IS_FILE (file));
1852
1853 GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_file (chooser, file);
1854 }
1855
1856 /**
1857 * gtk_file_chooser_get_files:
1858 * @chooser: a #GtkFileChooser
1859 *
1860 * Lists all the selected files and subfolders in the current folder of @chooser
1861 * as #GFile. An internal function, see gtk_file_chooser_get_uris().
1862 *
1863 * Return value: (element-type GFile) (transfer full): a #GSList
1864 * containing a #GFile for each selected file and subfolder in the
1865 * current folder. Free the returned list with g_slist_free(), and
1866 * the files with g_object_unref().
1867 *
1868 * Since: 2.14
1869 **/
1870 GSList *
gtk_file_chooser_get_files(GtkFileChooser * chooser)1871 gtk_file_chooser_get_files (GtkFileChooser *chooser)
1872 {
1873 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1874
1875 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_files (chooser);
1876 }
1877
1878 /**
1879 * gtk_file_chooser_set_file:
1880 * @chooser: a #GtkFileChooser
1881 * @file: the #GFile to set as current
1882 * @error: (allow-none): location to store the error, or %NULL to ignore errors.
1883 *
1884 * Sets @file as the current filename for the file chooser, by changing
1885 * to the file's parent folder and actually selecting the file in list. If
1886 * the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name
1887 * will also appear in the dialog's file name entry.
1888 *
1889 * If the file name isn't in the current folder of @chooser, then the current
1890 * folder of @chooser will be changed to the folder containing @filename. This
1891 * is equivalent to a sequence of gtk_file_chooser_unselect_all() followed by
1892 * gtk_file_chooser_select_filename().
1893 *
1894 * Note that the file must exist, or nothing will be done except
1895 * for the directory change.
1896 *
1897 * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
1898 * you should use this function if you already have a file name to which the
1899 * user may save; for example, when the user opens an existing file and then
1900 * does <guimenuitem>File/Save As...</guimenuitem> on it. If you don't have
1901 * a file name already — for example, if the user just created a new
1902 * file and is saving it for the first time, do not call this function.
1903 * Instead, use something similar to this:
1904 * |[
1905 * if (document_is_new)
1906 * {
1907 * /* the user just created a new document */
1908 * gtk_file_chooser_set_current_folder_file (chooser, default_file_for_saving);
1909 * gtk_file_chooser_set_current_name (chooser, "Untitled document");
1910 * }
1911 * else
1912 * {
1913 * /* the user edited an existing document */
1914 * gtk_file_chooser_set_file (chooser, existing_file);
1915 * }
1916 * ]|
1917 *
1918 * Return value: %TRUE if both the folder could be changed and the file was
1919 * selected successfully, %FALSE otherwise.
1920 *
1921 * Since: 2.14
1922 **/
1923 gboolean
gtk_file_chooser_set_file(GtkFileChooser * chooser,GFile * file,GError ** error)1924 gtk_file_chooser_set_file (GtkFileChooser *chooser,
1925 GFile *file,
1926 GError **error)
1927 {
1928 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
1929 g_return_val_if_fail (G_IS_FILE (file), FALSE);
1930 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1931
1932 gtk_file_chooser_unselect_all (chooser);
1933 return gtk_file_chooser_select_file (chooser, file, error);
1934 }
1935
1936 /**
1937 * gtk_file_chooser_get_file:
1938 * @chooser: a #GtkFileChooser
1939 *
1940 * Gets the #GFile for the currently selected file in
1941 * the file selector. If multiple files are selected,
1942 * one of the files will be returned at random.
1943 *
1944 * If the file chooser is in folder mode, this function returns the selected
1945 * folder.
1946 *
1947 * Returns: (transfer full): a selected #GFile. You own the returned file;
1948 * use g_object_unref() to release it.
1949 *
1950 * Since: 2.14
1951 **/
1952 GFile *
gtk_file_chooser_get_file(GtkFileChooser * chooser)1953 gtk_file_chooser_get_file (GtkFileChooser *chooser)
1954 {
1955 GSList *list;
1956 GFile *result = NULL;
1957
1958 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1959
1960 list = gtk_file_chooser_get_files (chooser);
1961 if (list)
1962 {
1963 result = list->data;
1964 list = g_slist_delete_link (list, list);
1965
1966 g_slist_foreach (list, (GFunc) g_object_unref, NULL);
1967 g_slist_free (list);
1968 }
1969
1970 return result;
1971 }
1972
1973 /**
1974 * _gtk_file_chooser_get_file_system:
1975 * @chooser: a #GtkFileChooser
1976 *
1977 * Gets the #GtkFileSystem of @chooser; this is an internal
1978 * implementation detail, used for conversion between paths
1979 * and filenames and URIs.
1980 *
1981 * Return value: the file system for @chooser.
1982 *
1983 * Since: 2.4
1984 **/
1985 GtkFileSystem *
_gtk_file_chooser_get_file_system(GtkFileChooser * chooser)1986 _gtk_file_chooser_get_file_system (GtkFileChooser *chooser)
1987 {
1988 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
1989
1990 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_file_system (chooser);
1991 }
1992
1993 /* Preview widget
1994 */
1995 /**
1996 * gtk_file_chooser_set_preview_widget:
1997 * @chooser: a #GtkFileChooser
1998 * @preview_widget: widget for displaying preview.
1999 *
2000 * Sets an application-supplied widget to use to display a custom preview
2001 * of the currently selected file. To implement a preview, after setting the
2002 * preview widget, you connect to the #GtkFileChooser::update-preview
2003 * signal, and call gtk_file_chooser_get_preview_filename() or
2004 * gtk_file_chooser_get_preview_uri() on each change. If you can
2005 * display a preview of the new file, update your widget and
2006 * set the preview active using gtk_file_chooser_set_preview_widget_active().
2007 * Otherwise, set the preview inactive.
2008 *
2009 * When there is no application-supplied preview widget, or the
2010 * application-supplied preview widget is not active, the file chooser
2011 * may display an internally generated preview of the current file or
2012 * it may display no preview at all.
2013 *
2014 * Since: 2.4
2015 **/
2016 void
gtk_file_chooser_set_preview_widget(GtkFileChooser * chooser,GtkWidget * preview_widget)2017 gtk_file_chooser_set_preview_widget (GtkFileChooser *chooser,
2018 GtkWidget *preview_widget)
2019 {
2020 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2021
2022 g_object_set (chooser, "preview-widget", preview_widget, NULL);
2023 }
2024
2025 /**
2026 * gtk_file_chooser_get_preview_widget:
2027 * @chooser: a #GtkFileChooser
2028 *
2029 * Gets the current preview widget; see
2030 * gtk_file_chooser_set_preview_widget().
2031 *
2032 * Return value: (transfer none): the current preview widget, or %NULL
2033 *
2034 * Since: 2.4
2035 **/
2036 GtkWidget *
gtk_file_chooser_get_preview_widget(GtkFileChooser * chooser)2037 gtk_file_chooser_get_preview_widget (GtkFileChooser *chooser)
2038 {
2039 GtkWidget *preview_widget;
2040
2041 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2042
2043 g_object_get (chooser, "preview-widget", &preview_widget, NULL);
2044
2045 /* Horrid hack; g_object_get() refs returned objects but
2046 * that contradicts the memory management conventions
2047 * for accessors.
2048 */
2049 if (preview_widget)
2050 g_object_unref (preview_widget);
2051
2052 return preview_widget;
2053 }
2054
2055 /**
2056 * gtk_file_chooser_set_preview_widget_active:
2057 * @chooser: a #GtkFileChooser
2058 * @active: whether to display the user-specified preview widget
2059 *
2060 * Sets whether the preview widget set by
2061 * gtk_file_chooser_set_preview_widget() should be shown for the
2062 * current filename. When @active is set to false, the file chooser
2063 * may display an internally generated preview of the current file
2064 * or it may display no preview at all. See
2065 * gtk_file_chooser_set_preview_widget() for more details.
2066 *
2067 * Since: 2.4
2068 **/
2069 void
gtk_file_chooser_set_preview_widget_active(GtkFileChooser * chooser,gboolean active)2070 gtk_file_chooser_set_preview_widget_active (GtkFileChooser *chooser,
2071 gboolean active)
2072 {
2073 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2074
2075 g_object_set (chooser, "preview-widget-active", active, NULL);
2076 }
2077
2078 /**
2079 * gtk_file_chooser_get_preview_widget_active:
2080 * @chooser: a #GtkFileChooser
2081 *
2082 * Gets whether the preview widget set by gtk_file_chooser_set_preview_widget()
2083 * should be shown for the current filename. See
2084 * gtk_file_chooser_set_preview_widget_active().
2085 *
2086 * Return value: %TRUE if the preview widget is active for the current filename.
2087 *
2088 * Since: 2.4
2089 **/
2090 gboolean
gtk_file_chooser_get_preview_widget_active(GtkFileChooser * chooser)2091 gtk_file_chooser_get_preview_widget_active (GtkFileChooser *chooser)
2092 {
2093 gboolean active;
2094
2095 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2096
2097 g_object_get (chooser, "preview-widget-active", &active, NULL);
2098
2099 return active;
2100 }
2101
2102 /**
2103 * gtk_file_chooser_set_use_preview_label:
2104 * @chooser: a #GtkFileChooser
2105 * @use_label: whether to display a stock label with the name of the previewed file
2106 *
2107 * Sets whether the file chooser should display a stock label with the name of
2108 * the file that is being previewed; the default is %TRUE. Applications that
2109 * want to draw the whole preview area themselves should set this to %FALSE and
2110 * display the name themselves in their preview widget.
2111 *
2112 * See also: gtk_file_chooser_set_preview_widget()
2113 *
2114 * Since: 2.4
2115 **/
2116 void
gtk_file_chooser_set_use_preview_label(GtkFileChooser * chooser,gboolean use_label)2117 gtk_file_chooser_set_use_preview_label (GtkFileChooser *chooser,
2118 gboolean use_label)
2119 {
2120 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2121
2122 g_object_set (chooser, "use-preview-label", use_label, NULL);
2123 }
2124
2125 /**
2126 * gtk_file_chooser_get_use_preview_label:
2127 * @chooser: a #GtkFileChooser
2128 *
2129 * Gets whether a stock label should be drawn with the name of the previewed
2130 * file. See gtk_file_chooser_set_use_preview_label().
2131 *
2132 * Return value: %TRUE if the file chooser is set to display a label with the
2133 * name of the previewed file, %FALSE otherwise.
2134 **/
2135 gboolean
gtk_file_chooser_get_use_preview_label(GtkFileChooser * chooser)2136 gtk_file_chooser_get_use_preview_label (GtkFileChooser *chooser)
2137 {
2138 gboolean use_label;
2139
2140 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2141
2142 g_object_get (chooser, "use-preview-label", &use_label, NULL);
2143
2144 return use_label;
2145 }
2146
2147 /**
2148 * gtk_file_chooser_get_preview_file:
2149 * @chooser: a #GtkFileChooser
2150 *
2151 * Gets the #GFile that should be previewed in a custom preview
2152 * Internal function, see gtk_file_chooser_get_preview_uri().
2153 *
2154 * Return value: (transfer full): the #GFile for the file to preview,
2155 * or %NULL if no file is selected. Free with g_object_unref().
2156 *
2157 * Since: 2.14
2158 **/
2159 GFile *
gtk_file_chooser_get_preview_file(GtkFileChooser * chooser)2160 gtk_file_chooser_get_preview_file (GtkFileChooser *chooser)
2161 {
2162 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2163
2164 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_preview_file (chooser);
2165 }
2166
2167 /**
2168 * _gtk_file_chooser_add_shortcut_folder:
2169 * @chooser: a #GtkFileChooser
2170 * @file: file for the folder to add
2171 * @error: (allow-none): location to store error, or %NULL
2172 *
2173 * Adds a folder to be displayed with the shortcut folders in a file chooser.
2174 * Internal function, see gtk_file_chooser_add_shortcut_folder().
2175 *
2176 * Return value: %TRUE if the folder could be added successfully, %FALSE
2177 * otherwise.
2178 *
2179 * Since: 2.4
2180 **/
2181 gboolean
_gtk_file_chooser_add_shortcut_folder(GtkFileChooser * chooser,GFile * file,GError ** error)2182 _gtk_file_chooser_add_shortcut_folder (GtkFileChooser *chooser,
2183 GFile *file,
2184 GError **error)
2185 {
2186 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2187 g_return_val_if_fail (G_IS_FILE (file), FALSE);
2188
2189 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_shortcut_folder (chooser, file, error);
2190 }
2191
2192 /**
2193 * _gtk_file_chooser_remove_shortcut_folder:
2194 * @chooser: a #GtkFileChooser
2195 * @file: file for the folder to remove
2196 * @error: (allow-none): location to store error, or %NULL
2197 *
2198 * Removes a folder from the shortcut folders in a file chooser. Internal
2199 * function, see gtk_file_chooser_remove_shortcut_folder().
2200 *
2201 * Return value: %TRUE if the folder could be removed successfully, %FALSE
2202 * otherwise.
2203 *
2204 * Since: 2.4
2205 **/
2206 gboolean
_gtk_file_chooser_remove_shortcut_folder(GtkFileChooser * chooser,GFile * file,GError ** error)2207 _gtk_file_chooser_remove_shortcut_folder (GtkFileChooser *chooser,
2208 GFile *file,
2209 GError **error)
2210 {
2211 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2212 g_return_val_if_fail (G_IS_FILE (file), FALSE);
2213
2214 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_shortcut_folder (chooser, file, error);
2215 }
2216
2217 /**
2218 * gtk_file_chooser_get_preview_filename:
2219 * @chooser: a #GtkFileChooser
2220 *
2221 * Gets the filename that should be previewed in a custom preview
2222 * widget. See gtk_file_chooser_set_preview_widget().
2223 *
2224 * Return value: (type filename): the filename to preview, or %NULL if
2225 * no file is selected, or if the selected file cannot be represented
2226 * as a local filename. Free with g_free()
2227 *
2228 * Since: 2.4
2229 **/
2230 char *
gtk_file_chooser_get_preview_filename(GtkFileChooser * chooser)2231 gtk_file_chooser_get_preview_filename (GtkFileChooser *chooser)
2232 {
2233 GFile *file;
2234 gchar *result = NULL;
2235
2236 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2237
2238 file = gtk_file_chooser_get_preview_file (chooser);
2239 if (file)
2240 {
2241 result = g_file_get_path (file);
2242 g_object_unref (file);
2243 }
2244
2245 return result;
2246 }
2247
2248 /**
2249 * gtk_file_chooser_get_preview_uri:
2250 * @chooser: a #GtkFileChooser
2251 *
2252 * Gets the URI that should be previewed in a custom preview
2253 * widget. See gtk_file_chooser_set_preview_widget().
2254 *
2255 * Return value: the URI for the file to preview, or %NULL if no file is
2256 * selected. Free with g_free().
2257 *
2258 * Since: 2.4
2259 **/
2260 char *
gtk_file_chooser_get_preview_uri(GtkFileChooser * chooser)2261 gtk_file_chooser_get_preview_uri (GtkFileChooser *chooser)
2262 {
2263 GFile *file;
2264 gchar *result = NULL;
2265
2266 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2267
2268 file = gtk_file_chooser_get_preview_file (chooser);
2269 if (file)
2270 {
2271 result = g_file_get_uri (file);
2272 g_object_unref (file);
2273 }
2274
2275 return result;
2276 }
2277
2278 /**
2279 * gtk_file_chooser_set_extra_widget:
2280 * @chooser: a #GtkFileChooser
2281 * @extra_widget: widget for extra options
2282 *
2283 * Sets an application-supplied widget to provide extra options to the user.
2284 *
2285 * Since: 2.4
2286 **/
2287 void
gtk_file_chooser_set_extra_widget(GtkFileChooser * chooser,GtkWidget * extra_widget)2288 gtk_file_chooser_set_extra_widget (GtkFileChooser *chooser,
2289 GtkWidget *extra_widget)
2290 {
2291 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2292
2293 g_object_set (chooser, "extra-widget", extra_widget, NULL);
2294 }
2295
2296 /**
2297 * gtk_file_chooser_get_extra_widget:
2298 * @chooser: a #GtkFileChooser
2299 *
2300 * Gets the current preview widget; see
2301 * gtk_file_chooser_set_extra_widget().
2302 *
2303 * Return value: (transfer none): the current extra widget, or %NULL
2304 *
2305 * Since: 2.4
2306 **/
2307 GtkWidget *
gtk_file_chooser_get_extra_widget(GtkFileChooser * chooser)2308 gtk_file_chooser_get_extra_widget (GtkFileChooser *chooser)
2309 {
2310 GtkWidget *extra_widget;
2311
2312 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2313
2314 g_object_get (chooser, "extra-widget", &extra_widget, NULL);
2315
2316 /* Horrid hack; g_object_get() refs returned objects but
2317 * that contradicts the memory management conventions
2318 * for accessors.
2319 */
2320 if (extra_widget)
2321 g_object_unref (extra_widget);
2322
2323 return extra_widget;
2324 }
2325
2326 /**
2327 * gtk_file_chooser_add_filter:
2328 * @chooser: a #GtkFileChooser
2329 * @filter: a #GtkFileFilter
2330 *
2331 * Adds @filter to the list of filters that the user can select between.
2332 * When a filter is selected, only files that are passed by that
2333 * filter are displayed.
2334 *
2335 * Note that the @chooser takes ownership of the filter, so you have to
2336 * ref and sink it if you want to keep a reference.
2337 *
2338 * Since: 2.4
2339 **/
2340 void
gtk_file_chooser_add_filter(GtkFileChooser * chooser,GtkFileFilter * filter)2341 gtk_file_chooser_add_filter (GtkFileChooser *chooser,
2342 GtkFileFilter *filter)
2343 {
2344 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2345
2346 GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_filter (chooser, filter);
2347 }
2348
2349 /**
2350 * gtk_file_chooser_remove_filter:
2351 * @chooser: a #GtkFileChooser
2352 * @filter: a #GtkFileFilter
2353 *
2354 * Removes @filter from the list of filters that the user can select between.
2355 *
2356 * Since: 2.4
2357 **/
2358 void
gtk_file_chooser_remove_filter(GtkFileChooser * chooser,GtkFileFilter * filter)2359 gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
2360 GtkFileFilter *filter)
2361 {
2362 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2363
2364 GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_filter (chooser, filter);
2365 }
2366
2367 /**
2368 * gtk_file_chooser_list_filters:
2369 * @chooser: a #GtkFileChooser
2370 *
2371 * Lists the current set of user-selectable filters; see
2372 * gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter().
2373 *
2374 * Return value: (element-type GtkFileFilter) (transfer container): a
2375 * #GSList containing the current set of user selectable filters. The
2376 * contents of the list are owned by GTK+, but you must free the list
2377 * itself with g_slist_free() when you are done with it.
2378 *
2379 * Since: 2.4
2380 **/
2381 GSList *
gtk_file_chooser_list_filters(GtkFileChooser * chooser)2382 gtk_file_chooser_list_filters (GtkFileChooser *chooser)
2383 {
2384 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2385
2386 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->list_filters (chooser);
2387 }
2388
2389 /**
2390 * gtk_file_chooser_set_filter:
2391 * @chooser: a #GtkFileChooser
2392 * @filter: a #GtkFileFilter
2393 *
2394 * Sets the current filter; only the files that pass the
2395 * filter will be displayed. If the user-selectable list of filters
2396 * is non-empty, then the filter should be one of the filters
2397 * in that list. Setting the current filter when the list of
2398 * filters is empty is useful if you want to restrict the displayed
2399 * set of files without letting the user change it.
2400 *
2401 * Since: 2.4
2402 **/
2403 void
gtk_file_chooser_set_filter(GtkFileChooser * chooser,GtkFileFilter * filter)2404 gtk_file_chooser_set_filter (GtkFileChooser *chooser,
2405 GtkFileFilter *filter)
2406 {
2407 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2408 g_return_if_fail (GTK_IS_FILE_FILTER (filter));
2409
2410 g_object_set (chooser, "filter", filter, NULL);
2411 }
2412
2413 /**
2414 * gtk_file_chooser_get_filter:
2415 * @chooser: a #GtkFileChooser
2416 *
2417 * Gets the current filter; see gtk_file_chooser_set_filter().
2418 *
2419 * Return value: (transfer none): the current filter, or %NULL
2420 *
2421 * Since: 2.4
2422 **/
2423 GtkFileFilter *
gtk_file_chooser_get_filter(GtkFileChooser * chooser)2424 gtk_file_chooser_get_filter (GtkFileChooser *chooser)
2425 {
2426 GtkFileFilter *filter;
2427
2428 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2429
2430 g_object_get (chooser, "filter", &filter, NULL);
2431 /* Horrid hack; g_object_get() refs returned objects but
2432 * that contradicts the memory management conventions
2433 * for accessors.
2434 */
2435 if (filter)
2436 g_object_unref (filter);
2437
2438 return filter;
2439 }
2440
2441 /**
2442 * gtk_file_chooser_add_shortcut_folder:
2443 * @chooser: a #GtkFileChooser
2444 * @folder: (type filename): filename of the folder to add
2445 * @error: (allow-none): location to store error, or %NULL
2446 *
2447 * Adds a folder to be displayed with the shortcut folders in a file chooser.
2448 * Note that shortcut folders do not get saved, as they are provided by the
2449 * application. For example, you can use this to add a
2450 * "/usr/share/mydrawprogram/Clipart" folder to the volume list.
2451 *
2452 * Return value: %TRUE if the folder could be added successfully, %FALSE
2453 * otherwise. In the latter case, the @error will be set as appropriate.
2454 *
2455 * Since: 2.4
2456 **/
2457 gboolean
gtk_file_chooser_add_shortcut_folder(GtkFileChooser * chooser,const char * folder,GError ** error)2458 gtk_file_chooser_add_shortcut_folder (GtkFileChooser *chooser,
2459 const char *folder,
2460 GError **error)
2461 {
2462 GFile *file;
2463 gboolean result;
2464
2465 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2466 g_return_val_if_fail (folder != NULL, FALSE);
2467
2468 file = g_file_new_for_path (folder);
2469 result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_shortcut_folder (chooser, file, error);
2470 g_object_unref (file);
2471
2472 return result;
2473 }
2474
2475 /**
2476 * gtk_file_chooser_remove_shortcut_folder:
2477 * @chooser: a #GtkFileChooser
2478 * @folder: (type filename): filename of the folder to remove
2479 * @error: (allow-none): location to store error, or %NULL
2480 *
2481 * Removes a folder from a file chooser's list of shortcut folders.
2482 *
2483 * Return value: %TRUE if the operation succeeds, %FALSE otherwise.
2484 * In the latter case, the @error will be set as appropriate.
2485 *
2486 * See also: gtk_file_chooser_add_shortcut_folder()
2487 *
2488 * Since: 2.4
2489 **/
2490 gboolean
gtk_file_chooser_remove_shortcut_folder(GtkFileChooser * chooser,const char * folder,GError ** error)2491 gtk_file_chooser_remove_shortcut_folder (GtkFileChooser *chooser,
2492 const char *folder,
2493 GError **error)
2494 {
2495 GFile *file;
2496 gboolean result;
2497
2498 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2499 g_return_val_if_fail (folder != NULL, FALSE);
2500
2501 file = g_file_new_for_path (folder);
2502 result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_shortcut_folder (chooser, file, error);
2503 g_object_unref (file);
2504
2505 return result;
2506 }
2507
2508 /**
2509 * gtk_file_chooser_list_shortcut_folders:
2510 * @chooser: a #GtkFileChooser
2511 *
2512 * Queries the list of shortcut folders in the file chooser, as set by
2513 * gtk_file_chooser_add_shortcut_folder().
2514 *
2515 * Return value: (element-type filename) (transfer full): A list of
2516 * folder filenames, or %NULL if there are no shortcut folders. Free
2517 * the returned list with g_slist_free(), and the filenames with
2518 * g_free().
2519 *
2520 * Since: 2.4
2521 **/
2522 GSList *
gtk_file_chooser_list_shortcut_folders(GtkFileChooser * chooser)2523 gtk_file_chooser_list_shortcut_folders (GtkFileChooser *chooser)
2524 {
2525 GSList *folders;
2526 GSList *result;
2527
2528 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2529
2530 folders = _gtk_file_chooser_list_shortcut_folder_files (chooser);
2531
2532 result = files_to_strings (folders, g_file_get_path);
2533 g_slist_foreach (folders, (GFunc) g_object_unref, NULL);
2534 g_slist_free (folders);
2535
2536 return result;
2537 }
2538
2539 /**
2540 * gtk_file_chooser_add_shortcut_folder_uri:
2541 * @chooser: a #GtkFileChooser
2542 * @uri: URI of the folder to add
2543 * @error: (allow-none): location to store error, or %NULL
2544 *
2545 * Adds a folder URI to be displayed with the shortcut folders in a file
2546 * chooser. Note that shortcut folders do not get saved, as they are provided
2547 * by the application. For example, you can use this to add a
2548 * "file:///usr/share/mydrawprogram/Clipart" folder to the volume list.
2549 *
2550 * Return value: %TRUE if the folder could be added successfully, %FALSE
2551 * otherwise. In the latter case, the @error will be set as appropriate.
2552 *
2553 * Since: 2.4
2554 **/
2555 gboolean
gtk_file_chooser_add_shortcut_folder_uri(GtkFileChooser * chooser,const char * uri,GError ** error)2556 gtk_file_chooser_add_shortcut_folder_uri (GtkFileChooser *chooser,
2557 const char *uri,
2558 GError **error)
2559 {
2560 GFile *file;
2561 gboolean result;
2562
2563 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2564 g_return_val_if_fail (uri != NULL, FALSE);
2565
2566 file = g_file_new_for_uri (uri);
2567 result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->add_shortcut_folder (chooser, file, error);
2568 g_object_unref (file);
2569
2570 return result;
2571 }
2572
2573 /**
2574 * gtk_file_chooser_remove_shortcut_folder_uri:
2575 * @chooser: a #GtkFileChooser
2576 * @uri: URI of the folder to remove
2577 * @error: (allow-none): location to store error, or %NULL
2578 *
2579 * Removes a folder URI from a file chooser's list of shortcut folders.
2580 *
2581 * Return value: %TRUE if the operation succeeds, %FALSE otherwise.
2582 * In the latter case, the @error will be set as appropriate.
2583 *
2584 * See also: gtk_file_chooser_add_shortcut_folder_uri()
2585 *
2586 * Since: 2.4
2587 **/
2588 gboolean
gtk_file_chooser_remove_shortcut_folder_uri(GtkFileChooser * chooser,const char * uri,GError ** error)2589 gtk_file_chooser_remove_shortcut_folder_uri (GtkFileChooser *chooser,
2590 const char *uri,
2591 GError **error)
2592 {
2593 GFile *file;
2594 gboolean result;
2595
2596 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2597 g_return_val_if_fail (uri != NULL, FALSE);
2598
2599 file = g_file_new_for_uri (uri);
2600 result = GTK_FILE_CHOOSER_GET_IFACE (chooser)->remove_shortcut_folder (chooser, file, error);
2601 g_object_unref (file);
2602
2603 return result;
2604 }
2605
2606 /**
2607 * gtk_file_chooser_list_shortcut_folder_uris:
2608 * @chooser: a #GtkFileChooser
2609 *
2610 * Queries the list of shortcut folders in the file chooser, as set by
2611 * gtk_file_chooser_add_shortcut_folder_uri().
2612 *
2613 * Return value: (element-type utf8) (transfer full): A list of folder
2614 * URIs, or %NULL if there are no shortcut folders. Free the returned
2615 * list with g_slist_free(), and the URIs with g_free().
2616 *
2617 * Since: 2.4
2618 **/
2619 GSList *
gtk_file_chooser_list_shortcut_folder_uris(GtkFileChooser * chooser)2620 gtk_file_chooser_list_shortcut_folder_uris (GtkFileChooser *chooser)
2621 {
2622 GSList *folders;
2623 GSList *result;
2624
2625 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2626
2627 folders = _gtk_file_chooser_list_shortcut_folder_files (chooser);
2628
2629 result = files_to_strings (folders, g_file_get_uri);
2630 g_slist_foreach (folders, (GFunc) g_object_unref, NULL);
2631 g_slist_free (folders);
2632
2633 return result;
2634 }
2635
2636 GSList *
_gtk_file_chooser_list_shortcut_folder_files(GtkFileChooser * chooser)2637 _gtk_file_chooser_list_shortcut_folder_files (GtkFileChooser *chooser)
2638 {
2639 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
2640
2641 return GTK_FILE_CHOOSER_GET_IFACE (chooser)->list_shortcut_folders (chooser);
2642 }
2643
2644 /**
2645 * gtk_file_chooser_set_show_hidden:
2646 * @chooser: a #GtkFileChooser
2647 * @show_hidden: %TRUE if hidden files and folders should be displayed.
2648 *
2649 * Sets whether hidden files and folders are displayed in the file selector.
2650 *
2651 * Since: 2.6
2652 **/
2653 void
gtk_file_chooser_set_show_hidden(GtkFileChooser * chooser,gboolean show_hidden)2654 gtk_file_chooser_set_show_hidden (GtkFileChooser *chooser,
2655 gboolean show_hidden)
2656 {
2657 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2658
2659 g_object_set (chooser, "show-hidden", show_hidden, NULL);
2660 }
2661
2662 /**
2663 * gtk_file_chooser_get_show_hidden:
2664 * @chooser: a #GtkFileChooser
2665 *
2666 * Gets whether hidden files and folders are displayed in the file selector.
2667 * See gtk_file_chooser_set_show_hidden().
2668 *
2669 * Return value: %TRUE if hidden files and folders are displayed.
2670 *
2671 * Since: 2.6
2672 **/
2673 gboolean
gtk_file_chooser_get_show_hidden(GtkFileChooser * chooser)2674 gtk_file_chooser_get_show_hidden (GtkFileChooser *chooser)
2675 {
2676 gboolean show_hidden;
2677
2678 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2679
2680 g_object_get (chooser, "show-hidden", &show_hidden, NULL);
2681
2682 return show_hidden;
2683 }
2684
2685 /**
2686 * gtk_file_chooser_set_do_overwrite_confirmation:
2687 * @chooser: a #GtkFileChooser
2688 * @do_overwrite_confirmation: whether to confirm overwriting in save mode
2689 *
2690 * Sets whether a file chooser in %GTK_FILE_CHOOSER_ACTION_SAVE mode will present
2691 * a confirmation dialog if the user types a file name that already exists. This
2692 * is %FALSE by default.
2693 *
2694 * Regardless of this setting, the @chooser will emit the
2695 * #GtkFileChooser::confirm-overwrite signal when appropriate.
2696 *
2697 * If all you need is the stock confirmation dialog, set this property to %TRUE.
2698 * You can override the way confirmation is done by actually handling the
2699 * #GtkFileChooser::confirm-overwrite signal; please refer to its documentation
2700 * for the details.
2701 *
2702 * Since: 2.8
2703 **/
2704 void
gtk_file_chooser_set_do_overwrite_confirmation(GtkFileChooser * chooser,gboolean do_overwrite_confirmation)2705 gtk_file_chooser_set_do_overwrite_confirmation (GtkFileChooser *chooser,
2706 gboolean do_overwrite_confirmation)
2707 {
2708 g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
2709
2710 g_object_set (chooser, "do-overwrite-confirmation", do_overwrite_confirmation, NULL);
2711 }
2712
2713 /**
2714 * gtk_file_chooser_get_do_overwrite_confirmation:
2715 * @chooser: a #GtkFileChooser
2716 *
2717 * Queries whether a file chooser is set to confirm for overwriting when the user
2718 * types a file name that already exists.
2719 *
2720 * Return value: %TRUE if the file chooser will present a confirmation dialog;
2721 * %FALSE otherwise.
2722 *
2723 * Since: 2.8
2724 **/
2725 gboolean
gtk_file_chooser_get_do_overwrite_confirmation(GtkFileChooser * chooser)2726 gtk_file_chooser_get_do_overwrite_confirmation (GtkFileChooser *chooser)
2727 {
2728 gboolean do_overwrite_confirmation;
2729
2730 g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
2731
2732 g_object_get (chooser, "do-overwrite-confirmation", &do_overwrite_confirmation, NULL);
2733
2734 return do_overwrite_confirmation;
2735 }
2736
2737 #if defined (G_OS_WIN32) && !defined (_WIN64)
2738
2739 /* DLL ABI stability backward compatibility versions */
2740
2741 #undef gtk_file_chooser_get_filename
2742
2743 gchar *
gtk_file_chooser_get_filename(GtkFileChooser * chooser)2744 gtk_file_chooser_get_filename (GtkFileChooser *chooser)
2745 {
2746 gchar *utf8_filename = gtk_file_chooser_get_filename_utf8 (chooser);
2747 gchar *retval = g_locale_from_utf8 (utf8_filename, -1, NULL, NULL, NULL);
2748
2749 g_free (utf8_filename);
2750
2751 return retval;
2752 }
2753
2754 #undef gtk_file_chooser_set_filename
2755
2756 gboolean
gtk_file_chooser_set_filename(GtkFileChooser * chooser,const gchar * filename)2757 gtk_file_chooser_set_filename (GtkFileChooser *chooser,
2758 const gchar *filename)
2759 {
2760 gchar *utf8_filename = g_locale_to_utf8 (filename, -1, NULL, NULL, NULL);
2761 gboolean retval = gtk_file_chooser_set_filename_utf8 (chooser, utf8_filename);
2762
2763 g_free (utf8_filename);
2764
2765 return retval;
2766 }
2767
2768 #undef gtk_file_chooser_select_filename
2769
2770 gboolean
gtk_file_chooser_select_filename(GtkFileChooser * chooser,const gchar * filename)2771 gtk_file_chooser_select_filename (GtkFileChooser *chooser,
2772 const gchar *filename)
2773 {
2774 gchar *utf8_filename = g_locale_to_utf8 (filename, -1, NULL, NULL, NULL);
2775 gboolean retval = gtk_file_chooser_select_filename_utf8 (chooser, utf8_filename);
2776
2777 g_free (utf8_filename);
2778
2779 return retval;
2780 }
2781
2782 #undef gtk_file_chooser_unselect_filename
2783
2784 void
gtk_file_chooser_unselect_filename(GtkFileChooser * chooser,const char * filename)2785 gtk_file_chooser_unselect_filename (GtkFileChooser *chooser,
2786 const char *filename)
2787 {
2788 gchar *utf8_filename = g_locale_to_utf8 (filename, -1, NULL, NULL, NULL);
2789
2790 gtk_file_chooser_unselect_filename_utf8 (chooser, utf8_filename);
2791 g_free (utf8_filename);
2792 }
2793
2794 #undef gtk_file_chooser_get_filenames
2795
2796 GSList *
gtk_file_chooser_get_filenames(GtkFileChooser * chooser)2797 gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
2798 {
2799 GSList *list = gtk_file_chooser_get_filenames_utf8 (chooser);
2800 GSList *rover = list;
2801
2802 while (rover)
2803 {
2804 gchar *tem = (gchar *) rover->data;
2805 rover->data = g_locale_from_utf8 ((gchar *) rover->data, -1, NULL, NULL, NULL);
2806 g_free (tem);
2807 rover = rover->next;
2808 }
2809
2810 return list;
2811 }
2812
2813 #undef gtk_file_chooser_set_current_folder
2814
2815 gboolean
gtk_file_chooser_set_current_folder(GtkFileChooser * chooser,const gchar * filename)2816 gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
2817 const gchar *filename)
2818 {
2819 gchar *utf8_filename = g_locale_to_utf8 (filename, -1, NULL, NULL, NULL);
2820 gboolean retval = gtk_file_chooser_set_current_folder_utf8 (chooser, utf8_filename);
2821
2822 g_free (utf8_filename);
2823
2824 return retval;
2825 }
2826
2827 #undef gtk_file_chooser_get_current_folder
2828
2829 gchar *
gtk_file_chooser_get_current_folder(GtkFileChooser * chooser)2830 gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
2831 {
2832 gchar *utf8_folder = gtk_file_chooser_get_current_folder_utf8 (chooser);
2833 gchar *retval = g_locale_from_utf8 (utf8_folder, -1, NULL, NULL, NULL);
2834
2835 g_free (utf8_folder);
2836
2837 return retval;
2838 }
2839
2840 #undef gtk_file_chooser_get_preview_filename
2841
2842 char *
gtk_file_chooser_get_preview_filename(GtkFileChooser * chooser)2843 gtk_file_chooser_get_preview_filename (GtkFileChooser *chooser)
2844 {
2845 char *utf8_filename = gtk_file_chooser_get_preview_filename_utf8 (chooser);
2846 char *retval = g_locale_from_utf8 (utf8_filename, -1, NULL, NULL, NULL);
2847
2848 g_free (utf8_filename);
2849
2850 return retval;
2851 }
2852
2853 #undef gtk_file_chooser_add_shortcut_folder
2854
2855 gboolean
gtk_file_chooser_add_shortcut_folder(GtkFileChooser * chooser,const char * folder,GError ** error)2856 gtk_file_chooser_add_shortcut_folder (GtkFileChooser *chooser,
2857 const char *folder,
2858 GError **error)
2859 {
2860 char *utf8_folder = g_locale_to_utf8 (folder, -1, NULL, NULL, NULL);
2861 gboolean retval =
2862 gtk_file_chooser_add_shortcut_folder_utf8 (chooser, utf8_folder, error);
2863
2864 g_free (utf8_folder);
2865
2866 return retval;
2867 }
2868
2869 #undef gtk_file_chooser_remove_shortcut_folder
2870
2871 gboolean
gtk_file_chooser_remove_shortcut_folder(GtkFileChooser * chooser,const char * folder,GError ** error)2872 gtk_file_chooser_remove_shortcut_folder (GtkFileChooser *chooser,
2873 const char *folder,
2874 GError **error)
2875 {
2876 char *utf8_folder = g_locale_to_utf8 (folder, -1, NULL, NULL, NULL);
2877 gboolean retval =
2878 gtk_file_chooser_remove_shortcut_folder_utf8 (chooser, utf8_folder, error);
2879
2880 g_free (utf8_folder);
2881
2882 return retval;
2883 }
2884
2885 #undef gtk_file_chooser_list_shortcut_folders
2886
2887 GSList *
gtk_file_chooser_list_shortcut_folders(GtkFileChooser * chooser)2888 gtk_file_chooser_list_shortcut_folders (GtkFileChooser *chooser)
2889 {
2890 GSList *list = gtk_file_chooser_list_shortcut_folders_utf8 (chooser);
2891 GSList *rover = list;
2892
2893 while (rover)
2894 {
2895 gchar *tem = (gchar *) rover->data;
2896 rover->data = g_locale_from_utf8 ((gchar *) rover->data, -1, NULL, NULL, NULL);
2897 g_free (tem);
2898 rover = rover->next;
2899 }
2900
2901 return list;
2902 }
2903
2904 #endif
2905
2906 #define __GTK_FILE_CHOOSER_C__
2907 #include "gtkaliasdef.c"
2908