#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.
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.
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.
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.
#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:
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.