FileChooser


Object Hierarchy:

Object hierarchy for FileChooser

Description:

public interface FileChooser : Object

FileChooser is an interface that can be implemented by file selection widgets.

In GTK+, the main objects that implement this interface are FileChooserWidget , FileChooserDialog, and FileChooserButton. You do not need to write an object that implements the FileChooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface.

FileChooser 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 FileChooser, 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 get_filename to open or fopen, you may not be able to directly set it as the text of a Label widget unless you convert it first to UTF-8, which all GTK+ widgets expect. You should use to_utf8 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 set_preview_widget. Then, connect to the update_preview signal to get notified when you need to update the contents of the preview.

Your callback should use get_preview_filename to see what needs previewing. Once you have generated the preview for the corresponding file, you must call set_preview_widget_active with a boolean flag that indicates whether your callback could successfully generate a preview.

Example: Using a Preview Widget

{
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 set_extra_widget 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 Box or a Grid and include your widgets in it. Then, set the container as the whole extra widget.


Namespace: Gtk
Package: gtk+-3.0

Content:

Properties:

Methods:

Signals:

Inherited Members: