1 2@c %start of fragment 3 4@node GtkFileChooser 5@chapter GtkFileChooser 6File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog 7 8@section Overview 9@code{<gtk-file-chooser>} is an interface that can be implemented by file 10selection widgets. In GTK+, the main objects that implement this interface are 11@code{<gtk-file-chooser-widget>}, @code{<gtk-file-chooser-dialog>}, and 12@code{<gtk-file-chooser-button>}. You do not need to write an object that 13implements the @code{<gtk-file-chooser>} interface unless you are trying to 14adapt an existing file selector to expose a standard programming interface. 15 16@code{<gtk-file-chooser>} allows for shortcuts to various places in the 17filesystem. In the default implementation these are displayed in the left pane. 18It may be a bit confusing at first taht these shortcuts come from various 19sources and in various flavours, so lets explain the terminology here: 20 21@table @var 22@item Shortcuts 23 24@c %start of fragment 25 26 27@c %end of fragment 28@item Volumes 29 30@c %start of fragment 31 32 33@c %end of fragment 34@end table 35 36are created by the user, by dragging folders from the right pane to the left 37pane, or by using the "Add". Bookmarks can be renamed and deleted by the user. 38 39can be provided by the application or by the underlying filesystem abstraction 40(e.g. both the gnome-vfs and the Windows filesystems provide "Desktop" 41shortcuts). Shortcuts cannot be modified by the user. 42 43are provided by the underlying filesystem abstraction. They are the "roots" of 44the filesystem. 45 46@section File Names and Encodings 47When the user is finished selecting files in a @code{<gtk-file-chooser>}, your 48program can get the selected names either as filenames or as URIs. For URIs, the 49normal escaping rules are applied if the URI contains non-ASCII characters. 50However, filenames are @emph{always} returned in the character set specified by 51the @env{G_FILENAME_ENCODING} environment variable. Please see the Glib 52documentation for more details about this variable. 53 54This means that while you can pass the result of 55@code{gtk-file-chooser-get-filename} to @code{open(2)} or @code{fopen(3)}, you 56may not be able to directly set it as the text of a @code{<gtk-label>} widget 57unless you convert it first to UTF-8, which all GTK+ widgets expect. You should 58use @code{g-filename-to-utf8} to convert filenames into strings that can be 59passed to GTK+ widgets. 60 61@section Adding a Preview Widget 62You can add a custom preview widget to a file chooser and then get notification 63about when the preview needs to be updated. To install a preview widget, use 64@code{gtk-file-chooser-set-preview-widget}. Then, connect to the 65@code{<gtk-file-chooser::update-preview>} signal to get notified when you need 66to update the contents of the preview. 67 68Your callback should use @code{gtk-file-chooser-get-preview-filename} to see 69what needs previewing. Once you have generated the preview for the corresponding 70file, you must call @code{gtk-file-chooser-set-preview-widget-active} with a 71boolean flag that indicates whether your callback could successfully generate a 72preview. 73 74@example 75 76@{ 77 GtkImage *preview; 78 79 ... 80 81 preview = gtk_image_new (); 82 83 gtk_file_chooser_set_preview_widget (my_file_chooser, preview); 84 g_signal_connect (my_file_chooser, "update-preview", 85 G_CALLBACK (update_preview_cb), preview); 86@} 87 88static void 89update_preview_cb (GtkFileChooser *file_chooser, gpointer data) 90@{ 91 GtkWidget *preview; 92 char *filename; 93 GdkPixbuf *pixbuf; 94 gboolean have_preview; 95 96 preview = GTK_WIDGET (data); 97 filename = gtk_file_chooser_get_preview_filename (file_chooser); 98 99 pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL); 100 have_preview = (pixbuf != NULL); 101 g_free (filename); 102 103 gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf); 104 if (pixbuf) 105 gobject_unref (pixbuf); 106 107 gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview); 108@} 109 110@end example 111 112@section Adding Extra Widgets 113You can add extra widgets to a file chooser to provide options that are not 114present in the default design. For example, you can add a toggle button to give 115the user the option to open a file in read-only mode. You can use 116@code{gtk-file-chooser-set-extra-widget} to insert additional widgets in a file 117chooser. 118 119@example 120 121@{ 122 GtkWidget *toggle; 123 124 ... 125 126 toggle = gtk_check_button_new_with_label ("Open file read-only"); 127 gtk_widget_show (toggle); 128 gtk_file_chooser_set_extra_widget (my_file_chooser, toggle); 129@} 130 131@end example 132 133If you want to set more than one extra widget in the file chooser, you can a 134container such as a GtkVBox or a GtkTable and include your widgets in it. Then, 135set the container as the whole extra widget. 136 137@section Key Bindings 138Internally, GTK+ implements a file chooser's graphical user interface with the 139private . This widget has several key bindings and their associated signals. 140This section describes the available key binding signals. 141 142The default keys that activate the key-binding signals in are as follows: 143 144Both the individual key and the numeric keypad's "divide" key are supported. 145 146Both the individual Up key and the numeric keypad's Up key are supported. 147 148You can change these defaults to something else. For example, to add a modifier 149to a few of the default bindings, you can include the following fragment in your 150@file{.gtkrc-2.0} file: 151 152@example 153 154binding "my-own-gtkfilechooser-bindings" @{ 155 bind "<Alt><Shift>Up" @{ 156 "up-folder" () 157 @} 158 bind "<Alt><Shift>Down" @{ 159 "down-folder" () 160 @} 161 bind "<Alt><Shift>Home" @{ 162 "home-folder" () 163 @} 164@} 165 166class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings" 167 168@end example 169 170@subsection The "GtkFileChooserDefault::location-popup" signal 171@example 172 173 void user_function (GtkFileChooserDefault *chooser, 174 const char *path, 175 gpointer user_data); 176 177@end example 178 179This is used to make the file chooser show a "Location" dialog which the user 180can use to manually type the name of the file he wishes to select. The 181@var{path} argument is a string that gets put in the text entry for the file 182name. By default this is bound to with a @var{path} string of "" (the empty 183string). It is also bound to with a @var{path} string of "@samp{/}" (a slash): 184this lets you type and immediately type a path name. On Unix systems, this is 185bound to (tilde) with a @var{path} string of "~" itself for access to home 186directories. 187 188@table @var 189@item chooser 190the object which received the signal. 191 192@item path 193default contents for the text entry for the file name 194 195@item user-data 196user data set when the signal handler was connected. 197 198@end table 199 200You can create your own bindings for the signal with custom @var{path} strings, 201and have a crude form of easily-to-type bookmarks. For example, say you access 202the path @file{/home/username/misc} very frequently. You could then create an 203shortcut by including the following in your @file{.gtkrc-2.0}: 204 205@example 206 207binding "misc-shortcut" @{ 208 bind "<Alt>M" @{ 209 "location-popup" ("/home/username/misc") 210 @} 211@} 212 213class "GtkFileChooserDefault" binding "misc-shortcut" 214 215@end example 216 217@subsection The "GtkFileChooserDefault::up-folder" signal 218@example 219 220 void user_function (GtkFileChooserDefault *chooser, 221 gpointer user_data); 222 223@end example 224 225This is used to make the file chooser go to the parent of the current folder in 226the file hierarchy. By default this is bound to and (the Up key in the numeric 227keypad also works). 228 229@table @var 230@item chooser 231the object which received the signal. 232 233@item user-data 234user data set when the signal handler was connected. 235 236@end table 237 238@subsection The "GtkFileChooserDefault::down-folder" signal 239@example 240 241 void user_function (GtkFileChooserDefault *chooser, 242 gpointer user_data); 243 244@end example 245 246This is used to make the file chooser go to a child of the current folder in the 247file hierarchy. The subfolder that will be used is displayed in the path bar 248widget of the file chooser. For example, if the path bar is showing 249"/foo/@emph{bar/}baz", then this will cause the file chooser to switch to the 250"baz" subfolder. By default this is bound to (the Down key in the numeric keypad 251also works). 252 253@table @var 254@item chooser 255the object which received the signal. 256 257@item user-data 258user data set when the signal handler was connected. 259 260@end table 261 262@subsection The "GtkFileChooserDefault::home-folder" signal 263@example 264 265 void user_function (GtkFileChooserDefault *chooser, 266 gpointer user_data); 267 268@end example 269 270This is used to make the file chooser show the user's home folder in the file 271list. By default this is bound to (the Home key in the numeric keypad also 272works). 273 274@table @var 275@item chooser 276the object which received the signal. 277 278@item user-data 279user data set when the signal handler was connected. 280 281@end table 282 283@subsection The "GtkFileChooserDefault::desktop-folder" signal 284@example 285 286 void user_function (GtkFileChooserDefault *chooser, 287 gpointer user_data); 288 289@end example 290 291This is used to make the file chooser show the user's Desktop folder in the file 292list. By default this is bound to . 293 294@table @var 295@item chooser 296the object which received the signal. 297 298@item user-data 299user data set when the signal handler was connected. 300 301@end table 302 303@subsection The "GtkFileChooserDefault::quick-bookmark" signal 304@example 305 306 void user_function (GtkFileChooserDefault *chooser, 307 gint bookmark_index, 308 gpointer user_data); 309 310@end example 311 312This is used to make the file chooser switch to the bookmark specified in the 313@var{bookmark-index} parameter. For example, if you have three bookmarks, you 314can pass 0, 1, 2 to this signal to switch to each of them, respectively. By 315default this is bound to , , etc. until . Note that in the default binding, that 316is actually defined to switch to the bookmark at index 0, and so on 317successively; is defined to switch to the bookmark at index 10. 318 319@table @var 320@item chooser 321the object which received the signal. 322 323@item bookmark-indes 324index of the bookmark to switch to; the indices start at 0. 325 326@item user-data 327user data set when the signal handler was connected. 328 329@end table 330 331@section Usage 332@include defuns-gtkfilechooser.xml.texi 333 334@c %end of fragment 335