#GtkFileChooser is an interface that can be implemented by file selection widgets. In GTK+, the main objects that implement this interface are #GtkFileChooserWidget, #GtkFileChooserDialog, and #GtkFileChooserButton. You do not need to write an object that implements the #GtkFileChooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface.

#GtkFileChooser allows for shortcuts to various places in the filesystem. In the default implementation these are displayed in the left pane. It may be a bit confusing at first that these shortcuts come from various sources and in various flavours, so lets explain the terminology here:

• Bookmarks: are created by the user, by dragging folders from the

right pane to the left pane, or by using the “Add”. Bookmarks can be renamed and deleted by the user.

• Shortcuts: can be provided by the application. For example, a Paint

program may want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the user.

• Volumes: are provided by the underlying filesystem abstraction. They are

the “roots” of the filesystem.

File Names and Encodings

When the user is finished selecting files in a #GtkFileChooser, your program can get the selected names either as filenames or as URIs. For URIs, the normal escaping rules are applied if the URI contains non-ASCII characters. However, filenames are always returned in the character set specified by the G_FILENAME_ENCODING environment variable. Please see the GLib documentation for more details about this variable.

This means that while you can pass the result of [gtk.file_chooser.FileChooser.getFilename] to [glib.global.open] or [glib.global.fopen], you may not be able to directly set it as the text of a #GtkLabel widget unless you convert it first to UTF-8, which all GTK+ widgets expect. You should use [glib.global.filenameToUtf8] to convert filenames into strings that can be passed to GTK+ widgets.

Adding a Preview Widget

You can add a custom preview widget to a file chooser and then get notification about when the preview needs to be updated. To install a preview widget, use [gtk.file_chooser.FileChooser.setPreviewWidget]. Then, connect to the #GtkFileChooser::update-preview signal to get notified when you need to update the contents of the preview.

Your callback should use [gtk.file_chooser.FileChooser.getPreviewFilename] to see what needs previewing. Once you have generated the preview for the corresponding file, you must call [gtk.file_chooser.FileChooser.setPreviewWidgetActive] with a boolean flag that indicates whether your callback could successfully generate a preview.

Example: Using a Preview Widget ## {#gtkfilechooser-preview}

{
 GtkImage *preview;

 ...

 preview = gtk_image_new ();

 gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
 g_signal_connect (my_file_chooser, "update-preview",
		    G_CALLBACK (update_preview_cb), preview);
}

static void
update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
{
 GtkWidget *preview;
 char *filename;
 GdkPixbuf *pixbuf;
 gboolean have_preview;

 preview = GTK_WIDGET (data);
 filename = gtk_file_chooser_get_preview_filename (file_chooser);

 pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
 have_preview = (pixbuf != NULL);
 g_free (filename);

 gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
 if (pixbuf)
   g_object_unref (pixbuf);

 gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
}

Adding Extra Widgets

You can add extra widgets to a file chooser to provide options that are not present in the default design. For example, you can add a toggle button to give the user the option to open a file in read-only mode. You can use [gtk.file_chooser.FileChooser.setExtraWidget] to insert additional widgets in a file chooser.

An example for adding extra widgets:

GtkWidget *toggle;

 ...

 toggle = gtk_check_button_new_with_label ("Open file read-only");
 gtk_widget_show (toggle);
 gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
}

If you want to set more than one extra widget in the file chooser, you can a container such as a #GtkBox or a #GtkGrid and include your widgets in it. Then, set the container as the whole extra widget.