1/* GTK - The GIMP Toolkit
2 * gtkfilechooser.h: 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, see <http://www.gnu.org/licenses/>.
17 */
18
19#ifndef __GTK_FILE_CHOOSER_H__
20#define __GTK_FILE_CHOOSER_H__
21
22#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
23#error "Only <gtk/gtk.h> can be included directly."
24#endif
25
26#include <gtk/gtkfilefilter.h>
27#include <gtk/gtkwidget.h>
28
29G_BEGIN_DECLS
30
31#define GTK_TYPE_FILE_CHOOSER (gtk_file_chooser_get_type ())
32#define GTK_FILE_CHOOSER(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_FILE_CHOOSER, GtkFileChooser))
33#define GTK_IS_FILE_CHOOSER(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_FILE_CHOOSER))
34
35typedef struct _GtkFileChooser GtkFileChooser;
36
37/**
38 * GtkFileChooserAction:
39 * @GTK_FILE_CHOOSER_ACTION_OPEN: Indicates open mode. The file chooser
40 * will only let the user pick an existing file.
41 * @GTK_FILE_CHOOSER_ACTION_SAVE: Indicates save mode. The file chooser
42 * will let the user pick an existing file, or type in a new
43 * filename.
44 * @GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER: Indicates an Open mode for
45 * selecting folders. The file chooser will let the user pick an
46 * existing folder.
47 * @GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER: Indicates a mode for creating a
48 * new folder. The file chooser will let the user name an existing or
49 * new folder.
50 *
51 * Describes whether a #GtkFileChooser is being used to open existing files
52 * or to save to a possibly new file.
53 */
54typedef enum
55{
56 GTK_FILE_CHOOSER_ACTION_OPEN,
57 GTK_FILE_CHOOSER_ACTION_SAVE,
58 GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER,
59 GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER
60} GtkFileChooserAction;
61
62/**
63 * GtkFileChooserConfirmation:
64 * @GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM: The file chooser will present
65 * its stock dialog to confirm about overwriting an existing file.
66 * @GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME: The file chooser will
67 * terminate and accept the user’s choice of a file name.
68 * @GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN: The file chooser will
69 * continue running, so as to let the user select another file name.
70 *
71 * Used as a return value of handlers for the
72 * #GtkFileChooser::confirm-overwrite signal of a #GtkFileChooser. This
73 * value determines whether the file chooser will present the stock
74 * confirmation dialog, accept the user’s choice of a filename, or
75 * let the user choose another filename.
76 *
77 * Since: 2.8
78 */
79typedef enum
80{
81 GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM,
82 GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME,
83 GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN
84} GtkFileChooserConfirmation;
85
86GDK_AVAILABLE_IN_ALL
87GType gtk_file_chooser_get_type (void) G_GNUC_CONST;
88
89/* GError enumeration for GtkFileChooser */
90/**
91 * GTK_FILE_CHOOSER_ERROR:
92 *
93 * Used to get the #GError quark for #GtkFileChooser errors.
94 */
95#define GTK_FILE_CHOOSER_ERROR (gtk_file_chooser_error_quark ())
96
97/**
98 * GtkFileChooserError:
99 * @GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist.
100 * @GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename.
101 * @GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS: Indicates a duplicate path (e.g. when
102 * adding a bookmark).
103 * @GTK_FILE_CHOOSER_ERROR_INCOMPLETE_HOSTNAME: Indicates an incomplete hostname (e.g. "http://foo" without a slash after that).
104 *
105 * These identify the various errors that can occur while calling
106 * #GtkFileChooser functions.
107 */
108typedef enum {
109 GTK_FILE_CHOOSER_ERROR_NONEXISTENT,
110 GTK_FILE_CHOOSER_ERROR_BAD_FILENAME,
111 GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS,
112 GTK_FILE_CHOOSER_ERROR_INCOMPLETE_HOSTNAME
113} GtkFileChooserError;
114
115GDK_AVAILABLE_IN_ALL
116GQuark gtk_file_chooser_error_quark (void);
117
118/* Configuration
119 */
120GDK_AVAILABLE_IN_ALL
121void gtk_file_chooser_set_action (GtkFileChooser *chooser,
122 GtkFileChooserAction action);
123GDK_AVAILABLE_IN_ALL
124GtkFileChooserAction gtk_file_chooser_get_action (GtkFileChooser *chooser);
125GDK_AVAILABLE_IN_ALL
126void gtk_file_chooser_set_local_only (GtkFileChooser *chooser,
127 gboolean local_only);
128GDK_AVAILABLE_IN_ALL
129gboolean gtk_file_chooser_get_local_only (GtkFileChooser *chooser);
130GDK_AVAILABLE_IN_ALL
131void gtk_file_chooser_set_select_multiple (GtkFileChooser *chooser,
132 gboolean select_multiple);
133GDK_AVAILABLE_IN_ALL
134gboolean gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser);
135GDK_AVAILABLE_IN_ALL
136void gtk_file_chooser_set_show_hidden (GtkFileChooser *chooser,
137 gboolean show_hidden);
138GDK_AVAILABLE_IN_ALL
139gboolean gtk_file_chooser_get_show_hidden (GtkFileChooser *chooser);
140
141GDK_AVAILABLE_IN_ALL
142void gtk_file_chooser_set_do_overwrite_confirmation (GtkFileChooser *chooser,
143 gboolean do_overwrite_confirmation);
144GDK_AVAILABLE_IN_ALL
145gboolean gtk_file_chooser_get_do_overwrite_confirmation (GtkFileChooser *chooser);
146
147GDK_AVAILABLE_IN_ALL
148void gtk_file_chooser_set_create_folders (GtkFileChooser *chooser,
149 gboolean create_folders);
150GDK_AVAILABLE_IN_ALL
151gboolean gtk_file_chooser_get_create_folders (GtkFileChooser *chooser);
152
153/* Suggested name for the Save-type actions
154 */
155GDK_AVAILABLE_IN_ALL
156void gtk_file_chooser_set_current_name (GtkFileChooser *chooser,
157 const gchar *name);
158GDK_AVAILABLE_IN_3_10
159gchar *gtk_file_chooser_get_current_name (GtkFileChooser *chooser);
160
161/* Filename manipulation
162 */
163GDK_AVAILABLE_IN_ALL
164gchar * gtk_file_chooser_get_filename (GtkFileChooser *chooser);
165GDK_AVAILABLE_IN_ALL
166gboolean gtk_file_chooser_set_filename (GtkFileChooser *chooser,
167 const char *filename);
168GDK_AVAILABLE_IN_ALL
169gboolean gtk_file_chooser_select_filename (GtkFileChooser *chooser,
170 const char *filename);
171GDK_AVAILABLE_IN_ALL
172void gtk_file_chooser_unselect_filename (GtkFileChooser *chooser,
173 const char *filename);
174GDK_AVAILABLE_IN_ALL
175void gtk_file_chooser_select_all (GtkFileChooser *chooser);
176GDK_AVAILABLE_IN_ALL
177void gtk_file_chooser_unselect_all (GtkFileChooser *chooser);
178GDK_AVAILABLE_IN_ALL
179GSList * gtk_file_chooser_get_filenames (GtkFileChooser *chooser);
180GDK_AVAILABLE_IN_ALL
181gboolean gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
182 const gchar *filename);
183GDK_AVAILABLE_IN_ALL
184gchar * gtk_file_chooser_get_current_folder (GtkFileChooser *chooser);
185
186
187/* URI manipulation
188 */
189GDK_AVAILABLE_IN_ALL
190gchar * gtk_file_chooser_get_uri (GtkFileChooser *chooser);
191GDK_AVAILABLE_IN_ALL
192gboolean gtk_file_chooser_set_uri (GtkFileChooser *chooser,
193 const char *uri);
194GDK_AVAILABLE_IN_ALL
195gboolean gtk_file_chooser_select_uri (GtkFileChooser *chooser,
196 const char *uri);
197GDK_AVAILABLE_IN_ALL
198void gtk_file_chooser_unselect_uri (GtkFileChooser *chooser,
199 const char *uri);
200GDK_AVAILABLE_IN_ALL
201GSList * gtk_file_chooser_get_uris (GtkFileChooser *chooser);
202GDK_AVAILABLE_IN_ALL
203gboolean gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser,
204 const gchar *uri);
205GDK_AVAILABLE_IN_ALL
206gchar * gtk_file_chooser_get_current_folder_uri (GtkFileChooser *chooser);
207
208/* GFile manipulation */
209GDK_AVAILABLE_IN_ALL
210GFile * gtk_file_chooser_get_file (GtkFileChooser *chooser);
211GDK_AVAILABLE_IN_ALL
212gboolean gtk_file_chooser_set_file (GtkFileChooser *chooser,
213 GFile *file,
214 GError **error);
215GDK_AVAILABLE_IN_ALL
216gboolean gtk_file_chooser_select_file (GtkFileChooser *chooser,
217 GFile *file,
218 GError **error);
219GDK_AVAILABLE_IN_ALL
220void gtk_file_chooser_unselect_file (GtkFileChooser *chooser,
221 GFile *file);
222GDK_AVAILABLE_IN_ALL
223GSList * gtk_file_chooser_get_files (GtkFileChooser *chooser);
224GDK_AVAILABLE_IN_ALL
225gboolean gtk_file_chooser_set_current_folder_file (GtkFileChooser *chooser,
226 GFile *file,
227 GError **error);
228GDK_AVAILABLE_IN_ALL
229GFile * gtk_file_chooser_get_current_folder_file (GtkFileChooser *chooser);
230
231/* Preview widget
232 */
233GDK_AVAILABLE_IN_ALL
234void gtk_file_chooser_set_preview_widget (GtkFileChooser *chooser,
235 GtkWidget *preview_widget);
236GDK_AVAILABLE_IN_ALL
237GtkWidget *gtk_file_chooser_get_preview_widget (GtkFileChooser *chooser);
238GDK_AVAILABLE_IN_ALL
239void gtk_file_chooser_set_preview_widget_active (GtkFileChooser *chooser,
240 gboolean active);
241GDK_AVAILABLE_IN_ALL
242gboolean gtk_file_chooser_get_preview_widget_active (GtkFileChooser *chooser);
243GDK_AVAILABLE_IN_ALL
244void gtk_file_chooser_set_use_preview_label (GtkFileChooser *chooser,
245 gboolean use_label);
246GDK_AVAILABLE_IN_ALL
247gboolean gtk_file_chooser_get_use_preview_label (GtkFileChooser *chooser);
248
249GDK_AVAILABLE_IN_ALL
250char *gtk_file_chooser_get_preview_filename (GtkFileChooser *chooser);
251GDK_AVAILABLE_IN_ALL
252char *gtk_file_chooser_get_preview_uri (GtkFileChooser *chooser);
253GDK_AVAILABLE_IN_ALL
254GFile *gtk_file_chooser_get_preview_file (GtkFileChooser *chooser);
255
256/* Extra widget
257 */
258GDK_AVAILABLE_IN_ALL
259void gtk_file_chooser_set_extra_widget (GtkFileChooser *chooser,
260 GtkWidget *extra_widget);
261GDK_AVAILABLE_IN_ALL
262GtkWidget *gtk_file_chooser_get_extra_widget (GtkFileChooser *chooser);
263
264/* List of user selectable filters
265 */
266GDK_AVAILABLE_IN_ALL
267void gtk_file_chooser_add_filter (GtkFileChooser *chooser,
268 GtkFileFilter *filter);
269GDK_AVAILABLE_IN_ALL
270void gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
271 GtkFileFilter *filter);
272GDK_AVAILABLE_IN_ALL
273GSList *gtk_file_chooser_list_filters (GtkFileChooser *chooser);
274
275/* Current filter
276 */
277GDK_AVAILABLE_IN_ALL
278void gtk_file_chooser_set_filter (GtkFileChooser *chooser,
279 GtkFileFilter *filter);
280GDK_AVAILABLE_IN_ALL
281GtkFileFilter *gtk_file_chooser_get_filter (GtkFileChooser *chooser);
282
283/* Per-application shortcut folders */
284
285GDK_AVAILABLE_IN_ALL
286gboolean gtk_file_chooser_add_shortcut_folder (GtkFileChooser *chooser,
287 const char *folder,
288 GError **error);
289GDK_AVAILABLE_IN_ALL
290gboolean gtk_file_chooser_remove_shortcut_folder (GtkFileChooser *chooser,
291 const char *folder,
292 GError **error);
293GDK_AVAILABLE_IN_ALL
294GSList *gtk_file_chooser_list_shortcut_folders (GtkFileChooser *chooser);
295
296GDK_AVAILABLE_IN_ALL
297gboolean gtk_file_chooser_add_shortcut_folder_uri (GtkFileChooser *chooser,
298 const char *uri,
299 GError **error);
300GDK_AVAILABLE_IN_ALL
301gboolean gtk_file_chooser_remove_shortcut_folder_uri (GtkFileChooser *chooser,
302 const char *uri,
303 GError **error);
304GDK_AVAILABLE_IN_ALL
305GSList *gtk_file_chooser_list_shortcut_folder_uris (GtkFileChooser *chooser);
306
307GDK_AVAILABLE_IN_3_22
308void gtk_file_chooser_add_choice (GtkFileChooser *chooser,
309 const char *id,
310 const char *label,
311 const char **options,
312 const char **option_labels);
313GDK_AVAILABLE_IN_3_22
314void gtk_file_chooser_remove_choice (GtkFileChooser *chooser,
315 const char *id);
316GDK_AVAILABLE_IN_3_22
317void gtk_file_chooser_set_choice (GtkFileChooser *chooser,
318 const char *id,
319 const char *option);
320GDK_AVAILABLE_IN_3_22
321const char *gtk_file_chooser_get_choice (GtkFileChooser *chooser,
322 const char *id);
323
324G_END_DECLS
325
326#endif /* __GTK_FILE_CHOOSER_H__ */
327

source code of include/gtk-3.0/gtk/gtkfilechooser.h