1/* $Id: filechooser.hg,v 1.23 2006/04/18 13:28:56 murrayc Exp $ */ 2 3/* Copyright (C) 2003 The gtkmm Development Team 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.1 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 Free 17 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 18 */ 19 20#include <gtkmm/widget.h> 21#include <gtkmm/filefilter.h> 22#include <glibmm/interface.h> 23#include <giomm/file.h> 24 25 26_DEFS(gtkmm,gtk) 27_PINCLUDE(glibmm/private/interface_p.h) 28 29namespace Gtk 30{ 31 32_WRAP_ENUM(FileChooserAction, GtkFileChooserAction) 33_WRAP_ENUM(FileChooserConfirmation, GtkFileChooserConfirmation) 34 35//Note that GTK_FILE_SYSTEM_ERROR is not currently public GTK+ API and should 36//never be instantiated by the GTK+ C API. 37 38/** Exception class for Gdk::FileChooser errors. 39 */ 40_WRAP_GERROR(FileChooserError,GtkFileChooserError,GTK_FILE_CHOOSER_ERROR) 41 42/** 43 * Gtk::FileChooser is an interface that can be implemented by file selection 44 * widgets. In gtkmm, the main objects that implement this interface are 45 * FileChooserWidget and FileChooserDialog. You do not need to write an 46 * object that implements the FileChooser interface unless you are trying to 47 * adapt an existing file selector to expose a standard programming interface. 48 * 49 * @par File Names and Encodings 50 * When the user is finished selecting files in a FileChooser, your program 51 * can get the selected names either as filenames or as URIs. For URIs, the 52 * normal escaping rules are applied if the URI contains non-ASCII characters. 53 * However, filenames are always returned in the character set specified by the 54 * G_FILENAME_ENCODING environment variable. Please see the Glib documentation 55 * for more details about this variable. 56 * 57 * @par Important 58 * This means that while you can pass the result of FileChooser::get_filename() 59 * to <tt>open(2)</tt> or <tt>fopen(3)</tt>, you may not be able to directly 60 * set it as the text of a Gtk::Label widget unless you convert it first to 61 * UTF-8, which all gtkmm widgets expect. You should use 62 * Glib::filename_to_utf8() to convert filenames into strings that can be 63 * passed to gtkmm widgets. 64 * 65 * @note 66 * The gtkmm FileChooser API is broken in that methods return Glib::ustring 67 * even though the returned string is not necessarily UTF-8 encoded. Any 68 * FileChooser method that takes or returns a filename (not a URI) should 69 * have std::string as parameter or return type. Fortunately this mistake 70 * doesn't prevent you from handling filenames correctly in your application. 71 * Just pretend that the API uses std::string and call Glib::filename_to_utf8() 72 * or Glib::filename_from_utf8() as appropriate. 73 * 74 * See http://bugzilla.gnome.org/show_bug.cgi?id=142138 for more information. 75 */ 76class FileChooser : public Glib::Interface 77{ 78 _CLASS_INTERFACE(FileChooser, GtkFileChooser, GTK_FILE_CHOOSER, GtkFileChooserClass) 79public: 80 81 _WRAP_METHOD(void set_action(FileChooserAction action), gtk_file_chooser_set_action) 82 _WRAP_METHOD(FileChooserAction get_action() const, gtk_file_chooser_get_action) 83 _WRAP_METHOD(void set_local_only(bool local_only = true), gtk_file_chooser_set_local_only) 84 _WRAP_METHOD(bool get_local_only() const, gtk_file_chooser_get_local_only) 85 _WRAP_METHOD(void set_select_multiple(bool select_multiple = true), gtk_file_chooser_set_select_multiple) 86 _WRAP_METHOD(bool get_select_multiple() const, gtk_file_chooser_get_select_multiple) 87 88 _WRAP_METHOD(void set_show_hidden(bool show_hidden = true), gtk_file_chooser_set_show_hidden) 89 _WRAP_METHOD(bool get_show_hidden() const, gtk_file_chooser_get_show_hidden) 90 91 _WRAP_METHOD(void set_do_overwrite_confirmation(bool do_overwrite_confirmation = true), gtk_file_chooser_set_do_overwrite_confirmation) 92 _WRAP_METHOD(bool get_do_overwrite_confirmation() const, gtk_file_chooser_get_do_overwrite_confirmation) 93 94 _WRAP_METHOD(void set_create_folders(bool create_folders = true), gtk_file_chooser_set_create_folders) 95 _WRAP_METHOD(bool get_create_folders() const, gtk_file_chooser_get_create_folders) 96 97 _WRAP_METHOD(void set_current_name(const Glib::ustring& name), gtk_file_chooser_set_current_name) 98 _WRAP_METHOD(Glib::ustring get_filename() const, gtk_file_chooser_get_filename) 99 _WRAP_METHOD(bool set_filename(const Glib::ustring& filename), gtk_file_chooser_set_filename) 100 _WRAP_METHOD(bool select_filename(const Glib::ustring& filename), gtk_file_chooser_select_filename) 101 _WRAP_METHOD(void unselect_filename(const Glib::ustring& filename), gtk_file_chooser_unselect_filename) 102 _WRAP_METHOD(void select_all(), gtk_file_chooser_select_all) 103 _WRAP_METHOD(void unselect_all(), gtk_file_chooser_unselect_all) 104 _WRAP_METHOD(Glib::SListHandle<Glib::ustring> get_filenames() const, gtk_file_chooser_get_filenames) 105 _WRAP_METHOD(bool set_current_folder(const Glib::ustring& filename), gtk_file_chooser_set_current_folder) 106 _WRAP_METHOD(Glib::ustring get_current_folder() const, gtk_file_chooser_get_current_folder) 107 108 109/* URI manipulation 110 */ 111 _WRAP_METHOD(Glib::ustring get_uri() const, gtk_file_chooser_get_uri) 112 _WRAP_METHOD(bool set_uri(const Glib::ustring& uri), gtk_file_chooser_set_uri) 113 _WRAP_METHOD(bool select_uri(const Glib::ustring& uri), gtk_file_chooser_select_uri) 114 _WRAP_METHOD(void unselect_uri(const Glib::ustring& uri), gtk_file_chooser_unselect_uri) 115 _WRAP_METHOD(Glib::SListHandle<Glib::ustring> get_uris() const, gtk_file_chooser_get_uris) 116 117 _WRAP_METHOD(bool set_current_folder_uri(const Glib::ustring& uri), gtk_file_chooser_set_current_folder_uri) 118 _WRAP_METHOD(Glib::ustring get_current_folder_uri() const, gtk_file_chooser_get_current_folder_uri) 119 120 _WRAP_METHOD(bool set_file(const Glib::RefPtr<const Gio::File>& uri), gtk_file_chooser_set_file, errthrow) 121 122 _WRAP_METHOD(bool select_file(const Glib::RefPtr<const Gio::File>& file), gtk_file_chooser_select_file, errthrow) 123 _WRAP_METHOD(void unselect_file(const Glib::RefPtr<const Gio::File>& file), gtk_file_chooser_unselect_file) 124 125#m4 _CONVERSION(`GSList*',`Glib::SListHandle< Glib::RefPtr<Gio::File> >',`Glib::SListHandle< Glib::RefPtr<Gio::File> >($3, Glib::OWNERSHIP_DEEP)') 126 _WRAP_METHOD(Glib::SListHandle< Glib::RefPtr<Gio::File> > get_files(), gtk_file_chooser_get_files) 127 128 _WRAP_METHOD(bool set_current_folder_file(const Glib::RefPtr<const Gio::File>& file), gtk_file_chooser_set_current_folder_file, errthrow) 129 130 //No refreturn is needed here, because the C function provides a reference: 131 _WRAP_METHOD(Glib::RefPtr<Gio::File> get_current_folder_file(), gtk_file_chooser_get_current_folder_file) 132 133 //No refreturn is needed here, because the C function provides a reference: 134 _WRAP_METHOD(Glib::RefPtr<Gio::File> get_file(), gtk_file_chooser_get_file) 135 _WRAP_METHOD(Glib::RefPtr<const Gio::File> get_file() const, gtk_file_chooser_get_file, constversion) 136 137/* Preview widget 138 */ 139 _WRAP_METHOD(void set_preview_widget(Gtk::Widget& preview_widget), gtk_file_chooser_set_preview_widget) 140 141 _WRAP_METHOD(Gtk::Widget* get_preview_widget(), gtk_file_chooser_get_preview_widget) 142 _WRAP_METHOD(const Gtk::Widget* get_preview_widget() const, gtk_file_chooser_get_preview_widget, constversion) 143 144 _WRAP_METHOD(void set_preview_widget_active(bool active = true), gtk_file_chooser_set_preview_widget_active) 145 _WRAP_METHOD(bool get_preview_widget_active() const, gtk_file_chooser_get_preview_widget_active) 146 147 _WRAP_METHOD(void set_use_preview_label(bool use_label = true), gtk_file_chooser_set_use_preview_label) 148 _WRAP_METHOD(bool get_use_preview_label() const, gtk_file_chooser_get_use_preview_label) 149 150 _WRAP_METHOD(Glib::ustring get_preview_filename() const, gtk_file_chooser_get_preview_filename) 151 _WRAP_METHOD(Glib::ustring get_preview_uri() const, gtk_file_chooser_get_preview_uri) 152 153 //No refreturn is needed here, because the C function provides a reference: 154 _WRAP_METHOD(Glib::RefPtr<Gio::File> get_preview_file(), gtk_file_chooser_get_preview_file) 155 _WRAP_METHOD(Glib::RefPtr<const Gio::File> get_preview_file() const, gtk_file_chooser_get_preview_file, constversion) 156 157/* Extra widget 158 */ 159 _WRAP_METHOD(void set_extra_widget(Gtk::Widget& extra_widget), gtk_file_chooser_set_extra_widget) 160 _WRAP_METHOD(Gtk::Widget* get_extra_widget(), gtk_file_chooser_get_extra_widget) 161 _WRAP_METHOD(const Gtk::Widget* get_extra_widget() const, gtk_file_chooser_get_extra_widget, constversion) 162 163/* List of user selectable filters 164 */ 165 _WRAP_METHOD(void add_filter(const FileFilter& filter), gtk_file_chooser_add_filter) 166 _WRAP_METHOD(void remove_filter (const FileFilter& filter), gtk_file_chooser_remove_filter) 167 168 _WRAP_METHOD(Glib::SListHandle< FileFilter* > list_filters(), gtk_file_chooser_list_filters) 169 _WRAP_METHOD(Glib::SListHandle< const FileFilter* > list_filters() const, gtk_file_chooser_list_filters) 170 171/* Current filter 172 */ 173 _WRAP_METHOD(void set_filter(const FileFilter& filter), gtk_file_chooser_set_filter) 174 _WRAP_METHOD(FileFilter* get_filter(), gtk_file_chooser_get_filter) 175 _WRAP_METHOD(const FileFilter* get_filter() const, gtk_file_chooser_get_filter, constversion) 176 177/* Per-application shortcut folders */ 178 179 _WRAP_METHOD(bool add_shortcut_folder(const Glib::ustring& folder), gtk_file_chooser_add_shortcut_folder, errthrow) 180 _WRAP_METHOD(bool remove_shortcut_folder(const Glib::ustring& folder), gtk_file_chooser_remove_shortcut_folder, errthrow) 181 _WRAP_METHOD(Glib::SListHandle<Glib::ustring> list_shortcut_folders() const, gtk_file_chooser_list_shortcut_folders) 182 183 _WRAP_METHOD(bool add_shortcut_folder_uri(const Glib::ustring& uri), gtk_file_chooser_add_shortcut_folder_uri, errthrow) 184 _WRAP_METHOD(bool remove_shortcut_folder_uri(const Glib::ustring& uri), gtk_file_chooser_remove_shortcut_folder_uri, errthrow) 185 _WRAP_METHOD(Glib::SListHandle<Glib::ustring> list_shortcut_folder_uris() const, gtk_file_chooser_list_shortcut_folder_uris) 186 187 188 /** This signal is emitted when the current folder in a FileChooser 189 * changes. This can happen due to the user performing some action that 190 * changes folders, such as selecting a bookmark or visiting a folder on the 191 * file list. It can also happen as a result of calling a function to 192 * explicitly change the current folder in a file chooser. 193 * 194 * Normally you do not need to connect to this signal, unless you need to keep 195 * track of which folder a file chooser is showing. 196 * 197 * @see set_current_folder(), get_current_folder(), 198 * set_current_folder_uri(), get_current_folder_uri(). 199 */ 200 _WRAP_SIGNAL(void current_folder_changed(), "current_folder_changed", no_default_handler) 201 202 /** This signal is emitted when there is a change in the set of selected files 203 * in a #GtkFileChooser. This can happen when the user modifies the selection 204 * with the mouse or the keyboard, or when explicitly calling functions to 205 * change the selection. 206 * 207 * Normally you do not need to connect to this signal, as it is easier to wait 208 * for the file chooser to finish running, and then to get the list of 209 * selected files using the functions mentioned below. 210 * 211 * @see select_filename(), unselect_filename(), get_filename(), 212 * get_filenames(), select_uri(), 213 * unselect_uri(), get_uri(), 214 * get_uris(). 215 */ 216 _WRAP_SIGNAL(void selection_changed(), "selection_changed", no_default_handler) 217 218 /** This signal is emitted when the preview in a file chooser should be 219 * regenerated. For example, this can happen when the currently selected file 220 * changes. You should use this signal if you want your file chooser to have 221 * a preview widget. 222 * 223 * Once you have installed a preview widget with 224 * set_preview_widget(), you should update it when this 225 * signal is emitted. You can use the functions 226 * get_preview_filename() or get_preview_uri() to get the name of the file to preview. 227 * Your widget may not be able to preview all kinds of files; your signal handler 228 * must call set_preview_wiget_active() to inform the file 229 * chooser about whether the preview was generated successfully or not. 230 * 231 * @see set_preview_widget(), set_preview_widget_active(), 232 * set_use_preview_label(), get_preview_filename(), get_preview_uri(). 233 */ 234 _WRAP_SIGNAL(void update_preview(), "update_preview", no_default_handler) 235 236 /** This signal is emitted when the user "activates" a file in the file 237 * chooser. This can happen by double-clicking on a file in the file list, or 238 * by pressing <keycap>Enter</keycap>. 239 * 240 * Normally you do not need to connect to this signal. It is used internally 241 * by FileChooserDialog to know when to activate the default button in the 242 * dialog. 243 * 244 * @see get_filename(), get_filenames(), get_uri(), get_uris(). 245 */ 246 _WRAP_SIGNAL(void file_activated(), "file_activated", no_default_handler) 247 248 _WRAP_SIGNAL(FileChooserConfirmation confirm_overwrite(), "confirm-overwrite", no_default_handler) 249 250 _WRAP_PROPERTY("action", FileChooserAction) 251 //TODO: _WRAP_PROPERTY("file-system-backend", FileSystem) //FileSystem is not really public API. 252 _WRAP_PROPERTY("filter", FileFilter*) 253 _WRAP_PROPERTY("local-only", bool) 254 _WRAP_PROPERTY("preview-widget", Widget*) 255 _WRAP_PROPERTY("preview-widget-active", bool) 256 _WRAP_PROPERTY("use-preview-label", bool) 257 _WRAP_PROPERTY("extra-widget", Widget*) 258 _WRAP_PROPERTY("select-multiple", bool) 259 _WRAP_PROPERTY("show-hidden", bool) 260 _WRAP_PROPERTY("do-overwrite-confirmation", bool) 261 _WRAP_PROPERTY("create-folders", bool) 262}; 263 264} // namespace Gtk 265