2
// Generated by gtkmmproc -- DO NOT MODIFY!
3
#ifndef _GTKMM_FILECHOOSER_H
4
#define _GTKMM_FILECHOOSER_H
9
/* $Id: filechooser.hg,v 1.23 2006/04/18 13:28:56 murrayc Exp $ */
11
/* Copyright (C) 2003 The gtkmm Development Team
13
* This library is free software; you can redistribute it and/or
14
* modify it under the terms of the GNU Lesser General Public
15
* License as published by the Free Software Foundation; either
16
* version 2.1 of the License, or (at your option) any later version.
18
* This library is distributed in the hope that it will be useful,
19
* but WITHOUT ANY WARRANTY; without even the implied warranty of
20
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21
* Lesser General Public License for more details.
23
* You should have received a copy of the GNU Lesser General Public
24
* License along with this library; if not, write to the Free
25
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
28
#include <gtkmm/widget.h>
29
#include <gtkmm/filefilter.h>
30
#include <glibmm/interface.h>
31
#include <giomm/file.h>
34
#ifndef DOXYGEN_SHOULD_SKIP_THIS
35
typedef struct _GtkFileChooser GtkFileChooser;
36
typedef struct _GtkFileChooserClass GtkFileChooserClass;
37
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
41
{ class FileChooser_Class; } // namespace Gtk
45
/** @addtogroup gtkmmEnums gtkmm Enums and Flags */
50
enum FileChooserAction
52
FILE_CHOOSER_ACTION_OPEN,
53
FILE_CHOOSER_ACTION_SAVE,
54
FILE_CHOOSER_ACTION_SELECT_FOLDER,
55
FILE_CHOOSER_ACTION_CREATE_FOLDER
61
#ifndef DOXYGEN_SHOULD_SKIP_THIS
66
class Value<Gtk::FileChooserAction> : public Glib::Value_Enum<Gtk::FileChooserAction>
69
static GType value_type() G_GNUC_CONST;
73
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
82
enum FileChooserConfirmation
84
FILE_CHOOSER_CONFIRMATION_CONFIRM,
85
FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME,
86
FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN
92
#ifndef DOXYGEN_SHOULD_SKIP_THIS
97
class Value<Gtk::FileChooserConfirmation> : public Glib::Value_Enum<Gtk::FileChooserConfirmation>
100
static GType value_type() G_GNUC_CONST;
104
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
111
//Note that GTK_FILE_SYSTEM_ERROR is not currently public GTK+ API and should
112
//never be instantiated by the GTK+ C API.
114
/** Exception class for Gdk::FileChooser errors.
116
class FileChooserError : public Glib::Error
127
FileChooserError(Code error_code, const Glib::ustring& error_message);
128
explicit FileChooserError(GError* gobject);
131
#ifndef DOXYGEN_SHOULD_SKIP_THIS
134
static void throw_func(GError* gobject);
136
friend void wrap_init(); // uses throw_func()
138
#endif //DOXYGEN_SHOULD_SKIP_THIS
143
#ifndef DOXYGEN_SHOULD_SKIP_THIS
148
class Value<Gtk::FileChooserError::Code> : public Glib::Value_Enum<Gtk::FileChooserError::Code>
151
static GType value_type() G_GNUC_CONST;
155
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
163
* Gtk::FileChooser is an interface that can be implemented by file selection
164
* widgets. In gtkmm, the main objects that implement this interface are
165
* FileChooserWidget and FileChooserDialog. You do not need to write an
166
* object that implements the FileChooser interface unless you are trying to
167
* adapt an existing file selector to expose a standard programming interface.
169
* @par File Names and Encodings
170
* When the user is finished selecting files in a FileChooser, your program
171
* can get the selected names either as filenames or as URIs. For URIs, the
172
* normal escaping rules are applied if the URI contains non-ASCII characters.
173
* However, filenames are always returned in the character set specified by the
174
* G_FILENAME_ENCODING environment variable. Please see the Glib documentation
175
* for more details about this variable.
178
* This means that while you can pass the result of FileChooser::get_filename()
179
* to <tt>open(2)</tt> or <tt>fopen(3)</tt>, you may not be able to directly
180
* set it as the text of a Gtk::Label widget unless you convert it first to
181
* UTF-8, which all gtkmm widgets expect. You should use
182
* Glib::filename_to_utf8() to convert filenames into strings that can be
183
* passed to gtkmm widgets.
186
* The gtkmm FileChooser API is broken in that methods return Glib::ustring
187
* even though the returned string is not necessarily UTF-8 encoded. Any
188
* FileChooser method that takes or returns a filename (not a URI) should
189
* have std::string as parameter or return type. Fortunately this mistake
190
* doesn't prevent you from handling filenames correctly in your application.
191
* Just pretend that the API uses std::string and call Glib::filename_to_utf8()
192
* or Glib::filename_from_utf8() as appropriate.
194
* See http://bugzilla.gnome.org/show_bug.cgi?id=142138 for more information.
197
class FileChooser : public Glib::Interface
200
#ifndef DOXYGEN_SHOULD_SKIP_THIS
203
typedef FileChooser CppObjectType;
204
typedef FileChooser_Class CppClassType;
205
typedef GtkFileChooser BaseObjectType;
206
typedef GtkFileChooserClass BaseClassType;
209
friend class FileChooser_Class;
210
static CppClassType filechooser_class_;
213
FileChooser(const FileChooser&);
214
FileChooser& operator=(const FileChooser&);
217
FileChooser(); // you must derive from this class
219
/** Called by constructors of derived classes. Provide the result of
220
* the Class init() function to ensure that it is properly
223
* @param interface_class The Class object for the derived type.
225
explicit FileChooser(const Glib::Interface_Class& interface_class);
228
// This is public so that C++ wrapper instances can be
229
// created for C instances of unwrapped types.
230
// For instance, if an unexpected C type implements the C interface.
231
explicit FileChooser(GtkFileChooser* castitem);
234
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
237
virtual ~FileChooser();
239
static void add_interface(GType gtype_implementer);
241
#ifndef DOXYGEN_SHOULD_SKIP_THIS
242
static GType get_type() G_GNUC_CONST;
243
static GType get_base_type() G_GNUC_CONST;
246
///Provides access to the underlying C GObject.
247
GtkFileChooser* gobj() { return reinterpret_cast<GtkFileChooser*>(gobject_); }
249
///Provides access to the underlying C GObject.
250
const GtkFileChooser* gobj() const { return reinterpret_cast<GtkFileChooser*>(gobject_); }
257
/** Sets the type of operation that the chooser is performing; the
258
* user interface is adapted to suit the selected action. For example,
259
* an option to create a new folder might be shown if the action is
260
* Gtk::FILE_CHOOSER_ACTION_SAVE but not if the action is
261
* Gtk::FILE_CHOOSER_ACTION_OPEN.
264
* @param action The action that the file selector is performing.
266
void set_action(FileChooserAction action);
268
/** Gets the type of operation that the file chooser is performing; see
272
* @return The action that the file selector is performing.
274
FileChooserAction get_action() const;
276
/** Sets whether only local files can be selected in the
277
* file selector. If @a local_only is <tt>true</tt> (the default),
278
* then the selected file are files are guaranteed to be
279
* accessible through the operating systems native file
280
* file system and therefore the application only
281
* needs to worry about the filename functions in
282
* Gtk::FileChooser, like get_filename(),
283
* rather than the URI functions like
287
* @param local_only <tt>true</tt> if only local files can be selected.
289
void set_local_only(bool local_only = true);
291
/** Gets whether only local files can be selected in the
292
* file selector. See set_local_only()
295
* @return <tt>true</tt> if only local files can be selected.
297
bool get_local_only() const;
299
/** Sets whether multiple files can be selected in the file selector. This is
300
* only relevant if the action is set to be Gtk::FILE_CHOOSER_ACTION_OPEN or
301
* Gtk::FILE_CHOOSER_ACTION_SELECT_FOLDER.
304
* @param select_multiple <tt>true</tt> if multiple files can be selected.
306
void set_select_multiple(bool select_multiple = true);
308
/** Gets whether multiple files can be selected in the file
309
* selector. See set_select_multiple().
312
* @return <tt>true</tt> if multiple files can be selected.
314
bool get_select_multiple() const;
317
/** Sets whether hidden files and folders are displayed in the file selector.
320
* @param show_hidden <tt>true</tt> if hidden files and folders should be displayed.
322
void set_show_hidden(bool show_hidden = true);
324
/** Gets whether hidden files and folders are displayed in the file selector.
325
* See set_show_hidden().
328
* @return <tt>true</tt> if hidden files and folders are displayed.
330
bool get_show_hidden() const;
333
/** Sets whether a file chooser in Gtk::FILE_CHOOSER_ACTION_SAVE mode will present
334
* a confirmation dialog if the user types a file name that already exists. This
335
* is <tt>false</tt> by default.
337
* Regardless of this setting, the @a chooser will emit the
338
* Gtk::FileChooser::confirm-overwrite signal when appropriate.
340
* If all you need is the stock confirmation dialog, set this property to <tt>true</tt>.
341
* You can override the way confirmation is done by actually handling the
342
* Gtk::FileChooser::confirm-overwrite signal; please refer to its documentation
346
* @param do_overwrite_confirmation Whether to confirm overwriting in save mode.
348
void set_do_overwrite_confirmation(bool do_overwrite_confirmation = true);
350
/** Queries whether a file chooser is set to confirm for overwriting when the user
351
* types a file name that already exists.
354
* @return <tt>true</tt> if the file chooser will present a confirmation dialog;
355
* <tt>false</tt> otherwise.
357
bool get_do_overwrite_confirmation() const;
360
/** Sets whether file choser will offer to create new folders.
361
* This is only relevant if the action is not set to be
362
* Gtk::FILE_CHOOSER_ACTION_OPEN.
365
* @param create_folders <tt>true</tt> if the New Folder button should be displayed.
367
void set_create_folders(bool create_folders = true);
369
/** Gets whether file choser will offer to create new folders.
370
* See set_create_folders().
373
* @return <tt>true</tt> if the New Folder button should be displayed.
375
bool get_create_folders() const;
378
/** Sets the current name in the file selector, as if entered
379
* by the user. Note that the name passed in here is a UTF-8
380
* string rather than a filename. This function is meant for
381
* such uses as a suggested name in a "Save As..." dialog.
383
* If you want to preselect a particular existing file, you should use
384
* set_filename() or set_uri() instead.
385
* Please see the documentation for those functions for an example of using
386
* set_current_name() as well.
389
* @param name The filename to use, as a UTF-8 string.
391
void set_current_name(const Glib::ustring& name);
393
/** Gets the filename for the currently selected file in
394
* the file selector. If multiple files are selected,
395
* one of the filenames will be returned at random.
397
* If the file chooser is in folder mode, this function returns the selected
401
* @return The currently selected filename, or an empty string
402
* if no file is selected, or the selected file can't
403
* be represented with a local filename.
405
Glib::ustring get_filename() const;
407
/** Sets @a filename as the current filename for the file chooser, by changing
408
* to the file's parent folder and actually selecting the file in list. If
409
* the @a chooser is in Gtk::FILE_CHOOSER_ACTION_SAVE mode, the file's base name
410
* will also appear in the dialog's file name entry.
412
* If the file name isn't in the current folder of @a chooser, then the current
413
* folder of @a chooser will be changed to the folder containing @a filename. This
414
* is equivalent to a sequence of unselect_all() followed by
417
* Note that the file must exist, or nothing will be done except
418
* for the directory change.
420
* If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
421
* you should use this function if you already have a file name to which the
422
* user may save; for example, when the user opens an existing file and then
423
* does <guimenuitem>File/Save As...</guimenuitem> on it. If you don't have
424
* a file name already — for example, if the user just created a new
425
* file and is saving it for the first time, do not call this function.
426
* Instead, use something similar to this:
428
* if (document_is_new)
430
* / * the user just created a new document * /
431
* gtk_file_chooser_set_current_folder (chooser, default_folder_for_saving);
432
* gtk_file_chooser_set_current_name (chooser, "Untitled document");
436
* / * the user edited an existing document * /
437
* gtk_file_chooser_set_filename (chooser, existing_filename);
442
* @param filename The filename to set as current.
443
* @return <tt>true</tt> if both the folder could be changed and the file was
444
* selected successfully, <tt>false</tt> otherwise.
446
bool set_filename(const Glib::ustring& filename);
448
/** Selects a filename. If the file name isn't in the current
449
* folder of @a chooser, then the current folder of @a chooser will
450
* be changed to the folder containing @a filename.
453
* @param filename The filename to select.
454
* @return <tt>true</tt> if both the folder could be changed and the file was
455
* selected successfully, <tt>false</tt> otherwise.
457
bool select_filename(const Glib::ustring& filename);
459
/** Unselects a currently selected filename. If the filename
460
* is not in the current directory, does not exist, or
461
* is otherwise not currently selected, does nothing.
464
* @param filename The filename to unselect.
466
void unselect_filename(const Glib::ustring& filename);
468
/** Selects all the files in the current folder of a file chooser.
474
/** Unselects all the files in the current folder of a file chooser.
480
/** Lists all the selected files and subfolders in the current folder of
481
* @a chooser. The returned names are full absolute paths. If files in the current
482
* folder cannot be represented as local filenames they will be ignored. (See
484
* @return A list containing the filenames of all selected
485
* files and subfolders in the current folder.
489
Glib::SListHandle<Glib::ustring> get_filenames() const;
491
/** Sets the current folder for @a chooser from a local filename.
492
* The user will be shown the full contents of the current folder,
493
* plus user interface elements for navigating to other folders.
496
* @param filename The full path of the new current folder.
497
* @return <tt>true</tt> if the folder could be changed successfully, <tt>false</tt>
500
bool set_current_folder(const Glib::ustring& filename);
502
/** Gets the current folder of @a chooser as a local filename.
503
* See set_current_folder().
504
* @return The full path of the current folder, possibly empty if the current
505
* path cannot be represented as a local filename. This function may also return
506
* and empty string if the file chooser was unable to load the last folder that was
507
* requested from it; for example, as would be for calling
508
* set_current_folder() on a nonexistent folder.
512
Glib::ustring get_current_folder() const;
518
/** Gets the URI for the currently selected file in
519
* the file selector. If multiple files are selected,
520
* one of the filenames will be returned at random.
522
* If the file chooser is in folder mode, this function returns the selected
526
* @return The currently selected URI, or an empty string
527
* if no file is selected.
529
Glib::ustring get_uri() const;
531
/** Sets the file referred to by @a uri as the current file for the file chooser,
532
* by changing to the URI's parent folder and actually selecting the URI in the
533
* list. If the @a chooser is Gtk::FILE_CHOOSER_ACTION_SAVE mode, the URI's base
534
* name will also appear in the dialog's file name entry.
536
* If the URI isn't in the current folder of @a chooser, then the current folder
537
* of @a chooser will be changed to the folder containing @a uri. This is equivalent
538
* to a sequence of unselect_all() followed by
541
* Note that the URI must exist, or nothing will be done except for the
543
* If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
544
* you should use this function if you already have a file name to which the
545
* user may save; for example, when the user opens an existing file and then
546
* does <guimenuitem>File/Save As...</guimenuitem> on it. If you don't have
547
* a file name already — for example, if the user just created a new
548
* file and is saving it for the first time, do not call this function.
549
* Instead, use something similar to this:
551
* if (document_is_new)
553
* / * the user just created a new document * /
554
* gtk_file_chooser_set_current_folder_uri (chooser, default_folder_for_saving);
555
* gtk_file_chooser_set_current_name (chooser, "Untitled document");
559
* / * the user edited an existing document * /
560
* gtk_file_chooser_set_uri (chooser, existing_uri);
565
* @param uri The URI to set as current.
566
* @return <tt>true</tt> if both the folder could be changed and the URI was
567
* selected successfully, <tt>false</tt> otherwise.
569
bool set_uri(const Glib::ustring& uri);
571
/** Selects the file to by @a uri. If the URI doesn't refer to a
572
* file in the current folder of @a chooser, then the current folder of
573
* @a chooser will be changed to the folder containing @a filename.
576
* @param uri The URI to select.
577
* @return <tt>true</tt> if both the folder could be changed and the URI was
578
* selected successfully, <tt>false</tt> otherwise.
580
bool select_uri(const Glib::ustring& uri);
582
/** Unselects the file referred to by @a uri. If the file
583
* is not in the current directory, does not exist, or
584
* is otherwise not currently selected, does nothing.
587
* @param uri The URI to unselect.
589
void unselect_uri(const Glib::ustring& uri);
591
/** Lists all the selected files and subfolders in the current folder of
592
* @a chooser. The returned names are full absolute URIs.
593
* @return A list containing the URIs of all selected
594
* files and subfolders in the current folder.
598
Glib::SListHandle<Glib::ustring> get_uris() const;
601
/** Sets the current folder for @a chooser from an URI.
602
* The user will be shown the full contents of the current folder,
603
* plus user interface elements for navigating to other folders.
606
* @param uri The URI for the new current folder.
607
* @return <tt>true</tt> if the folder could be changed successfully, <tt>false</tt>
610
bool set_current_folder_uri(const Glib::ustring& uri);
612
/** Gets the current folder of @a chooser as an URI.
613
* See set_current_folder_uri().
615
* Note that this is the folder that the file chooser is currently displaying
616
* (e.g. "file:///home/username/Documents"), which is <em>not the same</em>
617
* as the currently-selected folder if the chooser is in
618
* Gtk::FILE_CHOOSER_SELECT_FOLDER mode
619
* (e.g. "file:///home/username/Documents/selected-folder/". To get the
620
* currently-selected folder in that mode, use get_uri() as the
621
* usual way to get the selection.
624
* @return The URI for the current folder.
626
Glib::ustring get_current_folder_uri() const;
629
/** Sets @a file as the current filename for the file chooser, by changing
630
* to the file's parent folder and actually selecting the file in list. If
631
* the @a chooser is in Gtk::FILE_CHOOSER_ACTION_SAVE mode, the file's base name
632
* will also appear in the dialog's file name entry.
634
* If the file name isn't in the current folder of @a chooser, then the current
635
* folder of @a chooser will be changed to the folder containing @a filename. This
636
* is equivalent to a sequence of unselect_all() followed by
639
* Note that the file must exist, or nothing will be done except
640
* for the directory change.
642
* If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
643
* you should use this function if you already have a file name to which the
644
* user may save; for example, when the user opens an existing file and then
645
* does <guimenuitem>File/Save As...</guimenuitem> on it. If you don't have
646
* a file name already — for example, if the user just created a new
647
* file and is saving it for the first time, do not call this function.
648
* Instead, use something similar to this:
650
* if (document_is_new)
652
* / * the user just created a new document * /
653
* gtk_file_chooser_set_current_folder_file (chooser, default_file_for_saving);
654
* gtk_file_chooser_set_current_name (chooser, "Untitled document");
658
* / * the user edited an existing document * /
659
* gtk_file_chooser_set_file (chooser, existing_file);
664
* @param file The File to set as current.
665
* @return <tt>true</tt> if both the folder could be changed and the file was
666
* selected successfully, <tt>false</tt> otherwise.
668
bool set_file(const Glib::RefPtr<const Gio::File>& uri);
671
/** Selects the file referred to by @a file. An internal function. See
672
* _gtk_file_chooser_select_uri().
675
* @param file The file to select.
676
* @return <tt>true</tt> if both the folder could be changed and the path was
677
* selected successfully, <tt>false</tt> otherwise.
679
bool select_file(const Glib::RefPtr<const Gio::File>& file);
681
/** Unselects the file referred to by @a file. If the file is not in the current
682
* directory, does not exist, or is otherwise not currently selected, does nothing.
685
* @param file A File.
687
void unselect_file(const Glib::RefPtr<const Gio::File>& file);
690
/** Lists all the selected files and subfolders in the current folder of @a chooser
691
* as File. An internal function, see get_uris().
695
* containing a File for each selected file and subfolder in the
696
* current folder. Free the returned list with Glib::slist_free(), and
697
* the files with Glib::object_unref().
699
Glib::SListHandle< Glib::RefPtr<Gio::File> > get_files();
702
/** Sets the current folder for @a chooser from a File.
703
* Internal function, see set_current_folder_uri().
706
* @param file The File for the new folder.
707
* @return <tt>true</tt> if the folder could be changed successfully, <tt>false</tt>
710
bool set_current_folder_file(const Glib::RefPtr<const Gio::File>& file);
712
//No refreturn is needed here, because the C function provides a reference:
714
/** Gets the current folder of @a chooser as File.
715
* See get_current_folder_uri().
718
* @return The File for the current folder.
720
Glib::RefPtr<Gio::File> get_current_folder_file();
722
//No refreturn is needed here, because the C function provides a reference:
724
/** Gets the File for the currently selected file in
725
* the file selector. If multiple files are selected,
726
* one of the files will be returned at random.
728
* If the file chooser is in folder mode, this function returns the selected
732
* @return A selected File. You own the returned file;
733
* use Glib::object_unref() to release it.
735
Glib::RefPtr<Gio::File> get_file();
737
/** Gets the File for the currently selected file in
738
* the file selector. If multiple files are selected,
739
* one of the files will be returned at random.
741
* If the file chooser is in folder mode, this function returns the selected
745
* @return A selected File. You own the returned file;
746
* use Glib::object_unref() to release it.
748
Glib::RefPtr<const Gio::File> get_file() const;
753
/** Sets an application-supplied widget to use to display a custom preview
754
* of the currently selected file. To implement a preview, after setting the
755
* preview widget, you connect to the Gtk::FileChooser::update-preview
756
* signal, and call get_preview_filename() or
757
* get_preview_uri() on each change. If you can
758
* display a preview of the new file, update your widget and
759
* set the preview active using set_preview_widget_active().
760
* Otherwise, set the preview inactive.
762
* When there is no application-supplied preview widget, or the
763
* application-supplied preview widget is not active, the file chooser
764
* may display an internally generated preview of the current file or
765
* it may display no preview at all.
768
* @param preview_widget Widget for displaying preview.
770
void set_preview_widget(Gtk::Widget& preview_widget);
773
/** Gets the current preview widget; see
774
* set_preview_widget().
777
* @return The current preview widget, or <tt>0</tt>.
779
Gtk::Widget* get_preview_widget();
781
/** Gets the current preview widget; see
782
* set_preview_widget().
785
* @return The current preview widget, or <tt>0</tt>.
787
const Gtk::Widget* get_preview_widget() const;
790
/** Sets whether the preview widget set by
791
* set_preview_widget() should be shown for the
792
* current filename. When @a active is set to false, the file chooser
793
* may display an internally generated preview of the current file
794
* or it may display no preview at all. See
795
* set_preview_widget() for more details.
798
* @param active Whether to display the user-specified preview widget.
800
void set_preview_widget_active(bool active = true);
802
/** Gets whether the preview widget set by set_preview_widget()
803
* should be shown for the current filename. See
804
* set_preview_widget_active().
807
* @return <tt>true</tt> if the preview widget is active for the current filename.
809
bool get_preview_widget_active() const;
812
/** Sets whether the file chooser should display a stock label with the name of
813
* the file that is being previewed; the default is <tt>true</tt>. Applications that
814
* want to draw the whole preview area themselves should set this to <tt>false</tt> and
815
* display the name themselves in their preview widget.
817
* See also: set_preview_widget()
820
* @param use_label Whether to display a stock label with the name of the previewed file.
822
void set_use_preview_label(bool use_label = true);
824
/** Gets whether a stock label should be drawn with the name of the previewed
825
* file. See set_use_preview_label().
826
* @return <tt>true</tt> if the file chooser is set to display a label with the
827
* name of the previewed file, <tt>false</tt> otherwise.
829
bool get_use_preview_label() const;
832
/** Gets the filename that should be previewed in a custom preview
833
* widget. See set_preview_widget().
836
* @return The filename to preview, or an empty string if no file
837
* is selected, or if the selected file cannot be represented
838
* as a local filename.
840
Glib::ustring get_preview_filename() const;
842
/** Gets the URI that should be previewed in a custom preview
843
* widget. See set_preview_widget().
846
* @return The URI for the file to preview, or an empty string if no file is
849
Glib::ustring get_preview_uri() const;
851
//No refreturn is needed here, because the C function provides a reference:
853
/** Gets the File that should be previewed in a custom preview
854
* Internal function, see get_preview_uri().
857
* @return The File for the file to preview,
858
* or <tt>0</tt> if no file is selected. Free with Glib::object_unref().
860
Glib::RefPtr<Gio::File> get_preview_file();
862
/** Gets the File that should be previewed in a custom preview
863
* Internal function, see get_preview_uri().
866
* @return The File for the file to preview,
867
* or <tt>0</tt> if no file is selected. Free with Glib::object_unref().
869
Glib::RefPtr<const Gio::File> get_preview_file() const;
874
/** Sets an application-supplied widget to provide extra options to the user.
877
* @param extra_widget Widget for extra options.
879
void set_extra_widget(Gtk::Widget& extra_widget);
881
/** Gets the current preview widget; see
882
* set_extra_widget().
885
* @return The current extra widget, or <tt>0</tt>.
887
Gtk::Widget* get_extra_widget();
889
/** Gets the current preview widget; see
890
* set_extra_widget().
893
* @return The current extra widget, or <tt>0</tt>.
895
const Gtk::Widget* get_extra_widget() const;
897
/* List of user selectable filters
900
/** Adds @a filter to the list of filters that the user can select between.
901
* When a filter is selected, only files that are passed by that
902
* filter are displayed.
904
* Note that the @a chooser takes ownership of the filter, so you have to
905
* ref and sink it if you want to keep a reference.
908
* @param filter A Gtk::FileFilter.
910
void add_filter(const FileFilter& filter);
912
/** Removes @a filter from the list of filters that the user can select between.
915
* @param filter A Gtk::FileFilter.
917
void remove_filter(const FileFilter& filter);
920
/** Lists the current set of user-selectable filters; see
921
* add_filter(), remove_filter().
922
* @return A list containing the current set of
923
* user selectable filters.
927
Glib::SListHandle< FileFilter* > list_filters();
929
/** Lists the current set of user-selectable filters; see
930
* add_filter(), remove_filter().
931
* @return A list containing the current set of
932
* user selectable filters.
936
Glib::SListHandle< const FileFilter* > list_filters() const;
941
/** Sets the current filter; only the files that pass the
942
* filter will be displayed. If the user-selectable list of filters
943
* is non-empty, then the filter should be one of the filters
944
* in that list. Setting the current filter when the list of
945
* filters is empty is useful if you want to restrict the displayed
946
* set of files without letting the user change it.
949
* @param filter A Gtk::FileFilter.
951
void set_filter(const FileFilter& filter);
953
/** Gets the current filter; see set_filter().
956
* @return The current filter, or <tt>0</tt>.
958
FileFilter* get_filter();
960
/** Gets the current filter; see set_filter().
963
* @return The current filter, or <tt>0</tt>.
965
const FileFilter* get_filter() const;
967
/* Per-application shortcut folders */
970
/** Adds a folder to be displayed with the shortcut folders in a file chooser.
971
* Note that shortcut folders do not get saved, as they are provided by the
972
* application. For example, you can use this to add a
973
* "/usr/share/mydrawprogram/Clipart" folder to the volume list.
976
* @param folder Filename of the folder to add.
977
* @return <tt>true</tt> if the folder could be added successfully, <tt>false</tt>
978
* otherwise. In the latter case, the @a error will be set as appropriate.
980
bool add_shortcut_folder(const Glib::ustring& folder);
982
/** Removes a folder from a file chooser's list of shortcut folders.
985
* @param folder Filename of the folder to remove.
986
* @return <tt>true</tt> if the operation succeeds, <tt>false</tt> otherwise.
987
* In the latter case, the @a error will be set as appropriate.
989
* See also: add_shortcut_folder().
991
bool remove_shortcut_folder(const Glib::ustring& folder);
993
/** Queries the list of shortcut folders in the file chooser, as set by
994
* add_shortcut_folder().
997
* @return A list of folder filenames, if there are any shortcut
1000
Glib::SListHandle<Glib::ustring> list_shortcut_folders() const;
1003
/** Adds a folder URI to be displayed with the shortcut folders in a file
1004
* chooser. Note that shortcut folders do not get saved, as they are provided
1005
* by the application. For example, you can use this to add a
1006
* "file:///usr/share/mydrawprogram/Clipart" folder to the volume list.
1009
* @param uri URI of the folder to add.
1010
* @return <tt>true</tt> if the folder could be added successfully, <tt>false</tt>
1011
* otherwise. In the latter case, the @a error will be set as appropriate.
1013
bool add_shortcut_folder_uri(const Glib::ustring& uri);
1015
/** Removes a folder URI from a file chooser's list of shortcut folders.
1018
* @param uri URI of the folder to remove.
1019
* @return <tt>true</tt> if the operation succeeds, <tt>false</tt> otherwise.
1020
* In the latter case, the @a error will be set as appropriate.
1022
* See also: add_shortcut_folder_uri().
1024
bool remove_shortcut_folder_uri(const Glib::ustring& uri);
1026
/** Queries the list of shortcut folders in the file chooser, as set by
1027
* add_shortcut_folder_uri().
1028
* @return A list of folder URIs
1032
Glib::SListHandle<Glib::ustring> list_shortcut_folder_uris() const;
1035
/** This signal is emitted when the current folder in a FileChooser
1036
* changes. This can happen due to the user performing some action that
1037
* changes folders, such as selecting a bookmark or visiting a folder on the
1038
* file list. It can also happen as a result of calling a function to
1039
* explicitly change the current folder in a file chooser.
1041
* Normally you do not need to connect to this signal, unless you need to keep
1042
* track of which folder a file chooser is showing.
1044
* @see set_current_folder(), get_current_folder(),
1045
* set_current_folder_uri(), get_current_folder_uri().
1048
* <tt>void on_my_%current_folder_changed()</tt>
1051
Glib::SignalProxy0< void > signal_current_folder_changed();
1054
/** This signal is emitted when there is a change in the set of selected files
1055
* in a #GtkFileChooser. This can happen when the user modifies the selection
1056
* with the mouse or the keyboard, or when explicitly calling functions to
1057
* change the selection.
1059
* Normally you do not need to connect to this signal, as it is easier to wait
1060
* for the file chooser to finish running, and then to get the list of
1061
* selected files using the functions mentioned below.
1063
* @see select_filename(), unselect_filename(), get_filename(),
1064
* get_filenames(), select_uri(),
1065
* unselect_uri(), get_uri(),
1069
* <tt>void on_my_%selection_changed()</tt>
1072
Glib::SignalProxy0< void > signal_selection_changed();
1075
/** This signal is emitted when the preview in a file chooser should be
1076
* regenerated. For example, this can happen when the currently selected file
1077
* changes. You should use this signal if you want your file chooser to have
1080
* Once you have installed a preview widget with
1081
* set_preview_widget(), you should update it when this
1082
* signal is emitted. You can use the functions
1083
* get_preview_filename() or get_preview_uri() to get the name of the file to preview.
1084
* Your widget may not be able to preview all kinds of files; your signal handler
1085
* must call set_preview_wiget_active() to inform the file
1086
* chooser about whether the preview was generated successfully or not.
1088
* @see set_preview_widget(), set_preview_widget_active(),
1089
* set_use_preview_label(), get_preview_filename(), get_preview_uri().
1092
* <tt>void on_my_%update_preview()</tt>
1095
Glib::SignalProxy0< void > signal_update_preview();
1098
/** This signal is emitted when the user "activates" a file in the file
1099
* chooser. This can happen by double-clicking on a file in the file list, or
1100
* by pressing <keycap>Enter</keycap>.
1102
* Normally you do not need to connect to this signal. It is used internally
1103
* by FileChooserDialog to know when to activate the default button in the
1106
* @see get_filename(), get_filenames(), get_uri(), get_uris().
1109
* <tt>void on_my_%file_activated()</tt>
1112
Glib::SignalProxy0< void > signal_file_activated();
1117
* <tt>FileChooserConfirmation on_my_%confirm_overwrite()</tt>
1120
Glib::SignalProxy0< FileChooserConfirmation > signal_confirm_overwrite();
1123
#ifdef GLIBMM_PROPERTIES_ENABLED
1124
/** The type of operation that the file selector is performing.
1126
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1127
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1128
* the value of the property changes.
1130
Glib::PropertyProxy<FileChooserAction> property_action() ;
1131
#endif //#GLIBMM_PROPERTIES_ENABLED
1133
#ifdef GLIBMM_PROPERTIES_ENABLED
1134
/** The type of operation that the file selector is performing.
1136
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1137
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1138
* the value of the property changes.
1140
Glib::PropertyProxy_ReadOnly<FileChooserAction> property_action() const;
1141
#endif //#GLIBMM_PROPERTIES_ENABLED
1143
//TODO: _WRAP_PROPERTY("file-system-backend", FileSystem) //FileSystem is not really public API.
1144
#ifdef GLIBMM_PROPERTIES_ENABLED
1145
/** The current filter for selecting which files are displayed.
1147
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1148
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1149
* the value of the property changes.
1151
Glib::PropertyProxy<FileFilter*> property_filter() ;
1152
#endif //#GLIBMM_PROPERTIES_ENABLED
1154
#ifdef GLIBMM_PROPERTIES_ENABLED
1155
/** The current filter for selecting which files are displayed.
1157
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1158
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1159
* the value of the property changes.
1161
Glib::PropertyProxy_ReadOnly<FileFilter*> property_filter() const;
1162
#endif //#GLIBMM_PROPERTIES_ENABLED
1164
#ifdef GLIBMM_PROPERTIES_ENABLED
1165
/** Whether the selected file(s) should be limited to local file: URLs.
1167
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1168
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1169
* the value of the property changes.
1171
Glib::PropertyProxy<bool> property_local_only() ;
1172
#endif //#GLIBMM_PROPERTIES_ENABLED
1174
#ifdef GLIBMM_PROPERTIES_ENABLED
1175
/** Whether the selected file(s) should be limited to local file: URLs.
1177
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1178
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1179
* the value of the property changes.
1181
Glib::PropertyProxy_ReadOnly<bool> property_local_only() const;
1182
#endif //#GLIBMM_PROPERTIES_ENABLED
1184
#ifdef GLIBMM_PROPERTIES_ENABLED
1185
/** Application supplied widget for custom previews.
1187
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1188
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1189
* the value of the property changes.
1191
Glib::PropertyProxy<Widget*> property_preview_widget() ;
1192
#endif //#GLIBMM_PROPERTIES_ENABLED
1194
#ifdef GLIBMM_PROPERTIES_ENABLED
1195
/** Application supplied widget for custom previews.
1197
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1198
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1199
* the value of the property changes.
1201
Glib::PropertyProxy_ReadOnly<Widget*> property_preview_widget() const;
1202
#endif //#GLIBMM_PROPERTIES_ENABLED
1204
#ifdef GLIBMM_PROPERTIES_ENABLED
1205
/** Whether the application supplied widget for custom previews should be shown.
1207
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1208
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1209
* the value of the property changes.
1211
Glib::PropertyProxy<bool> property_preview_widget_active() ;
1212
#endif //#GLIBMM_PROPERTIES_ENABLED
1214
#ifdef GLIBMM_PROPERTIES_ENABLED
1215
/** Whether the application supplied widget for custom previews should be shown.
1217
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1218
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1219
* the value of the property changes.
1221
Glib::PropertyProxy_ReadOnly<bool> property_preview_widget_active() const;
1222
#endif //#GLIBMM_PROPERTIES_ENABLED
1224
#ifdef GLIBMM_PROPERTIES_ENABLED
1225
/** Whether to display a stock label with the name of the previewed file.
1227
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1228
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1229
* the value of the property changes.
1231
Glib::PropertyProxy<bool> property_use_preview_label() ;
1232
#endif //#GLIBMM_PROPERTIES_ENABLED
1234
#ifdef GLIBMM_PROPERTIES_ENABLED
1235
/** Whether to display a stock label with the name of the previewed file.
1237
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1238
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1239
* the value of the property changes.
1241
Glib::PropertyProxy_ReadOnly<bool> property_use_preview_label() const;
1242
#endif //#GLIBMM_PROPERTIES_ENABLED
1244
#ifdef GLIBMM_PROPERTIES_ENABLED
1245
/** Application supplied widget for extra options.
1247
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1248
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1249
* the value of the property changes.
1251
Glib::PropertyProxy<Widget*> property_extra_widget() ;
1252
#endif //#GLIBMM_PROPERTIES_ENABLED
1254
#ifdef GLIBMM_PROPERTIES_ENABLED
1255
/** Application supplied widget for extra options.
1257
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1258
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1259
* the value of the property changes.
1261
Glib::PropertyProxy_ReadOnly<Widget*> property_extra_widget() const;
1262
#endif //#GLIBMM_PROPERTIES_ENABLED
1264
#ifdef GLIBMM_PROPERTIES_ENABLED
1265
/** Whether to allow multiple files to be selected.
1267
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1268
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1269
* the value of the property changes.
1271
Glib::PropertyProxy<bool> property_select_multiple() ;
1272
#endif //#GLIBMM_PROPERTIES_ENABLED
1274
#ifdef GLIBMM_PROPERTIES_ENABLED
1275
/** Whether to allow multiple files to be selected.
1277
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1278
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1279
* the value of the property changes.
1281
Glib::PropertyProxy_ReadOnly<bool> property_select_multiple() const;
1282
#endif //#GLIBMM_PROPERTIES_ENABLED
1284
#ifdef GLIBMM_PROPERTIES_ENABLED
1285
/** Whether the hidden files and folders should be displayed.
1287
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1288
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1289
* the value of the property changes.
1291
Glib::PropertyProxy<bool> property_show_hidden() ;
1292
#endif //#GLIBMM_PROPERTIES_ENABLED
1294
#ifdef GLIBMM_PROPERTIES_ENABLED
1295
/** Whether the hidden files and folders should be displayed.
1297
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1298
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1299
* the value of the property changes.
1301
Glib::PropertyProxy_ReadOnly<bool> property_show_hidden() const;
1302
#endif //#GLIBMM_PROPERTIES_ENABLED
1304
#ifdef GLIBMM_PROPERTIES_ENABLED
1305
/** Whether a file chooser in save mode will present an overwrite confirmation dialog if necessary.
1307
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1308
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1309
* the value of the property changes.
1311
Glib::PropertyProxy<bool> property_do_overwrite_confirmation() ;
1312
#endif //#GLIBMM_PROPERTIES_ENABLED
1314
#ifdef GLIBMM_PROPERTIES_ENABLED
1315
/** Whether a file chooser in save mode will present an overwrite confirmation dialog if necessary.
1317
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1318
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1319
* the value of the property changes.
1321
Glib::PropertyProxy_ReadOnly<bool> property_do_overwrite_confirmation() const;
1322
#endif //#GLIBMM_PROPERTIES_ENABLED
1324
#ifdef GLIBMM_PROPERTIES_ENABLED
1325
/** Whether a file chooser not in open mode will offer the user to create new folders.
1327
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1328
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1329
* the value of the property changes.
1331
Glib::PropertyProxy<bool> property_create_folders() ;
1332
#endif //#GLIBMM_PROPERTIES_ENABLED
1334
#ifdef GLIBMM_PROPERTIES_ENABLED
1335
/** Whether a file chooser not in open mode will offer the user to create new folders.
1337
* You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1338
* @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1339
* the value of the property changes.
1341
Glib::PropertyProxy_ReadOnly<bool> property_create_folders() const;
1342
#endif //#GLIBMM_PROPERTIES_ENABLED
1348
//C++ methods used to invoke GTK+ virtual functions:
1351
//GTK+ Virtual Functions (override these to change behaviour):
1353
//Default Signal Handlers::
1363
/** A Glib::wrap() method for this object.
1365
* @param object The C instance.
1366
* @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
1367
* @result A C++ instance that wraps this C instance.
1369
* @relates Gtk::FileChooser
1371
Glib::RefPtr<Gtk::FileChooser> wrap(GtkFileChooser* object, bool take_copy = false);
1376
#endif /* _GTKMM_FILECHOOSER_H */
added
removed
include/gtkmm-2.4/gtkmm/filechooser.h
