Migrating from GtkFileSelection to GtkFileChooserFedericoMena-Quinterofederico@ximian.com
#GtkFileChooser, starting with GTK+ 2.4, is the new set of APIs
for file selection widgets and dialogs. Previous versions of GTK+
used #GtkFileSelection, which has numerous problems.
#GtkFileChooser is an abstract interface that can be implemented
by widgets that perform file selection tasks. Two widgets in GTK+
implement this interface: #GtkFileChooserDialog and
#GtkFileChooserWidget. Most applications simply need to use
#GtkFileChooserDialog, which is a dialog box that allows the user
to select existing files for opening them, or to pick new
filenames for saving documents. #GtkFileChooserWidget is for
special applications that need to embed a file selection widget
inside a larger window. In the context of GTK+,
#GtkFileChooserDialog is simply a #GtkDialog box with a
#GtkFileChooserWidget inside.
Creating a GtkFileChooserDialog
To create a #GtkFileChooserDialog, you simply call
gtk_file_chooser_dialog_new(). This function is similar to
gtk_dialog_new() in that it takes parameters for the title
of the dialog box and its transient parent, as well as its
buttons. In addition, it takes in an argument that determines
whether the file chooser dialog will be used for opening
existing files or for saving to a possibly new file.
Please see for
how to create a simple file chooser dialog and extract the
selected filename from it.
Selection Modes
#GtkFileChooser can be used in two modes, to select a single
file at a time or to select a set of more than one file. To set
this, use gtk_file_chooser_set_select_multiple(). In
single-selection mode, you can use
gtk_file_chooser_get_filename() to get a file name from the
local file system or gtk_file_chooser_get_uri() to get a
full-formed URI. In multiple-selection mode, you can use
gtk_file_chooser_get_filenames() to get a #GSList of filename
strings, or gtk_file_chooser_get_uris() to get a list of URI
strings.
Also, you can configure #GtkFileChooser to select files or
folders. Consider a backup program that needs to let the user
select a folder that will be backed up along with its
subfolders. To configure whether #GtkFileChooser is used to
select files or folders, use gtk_file_chooser_set_folder_mode().
Installing a Preview widget
Many applications need to have a preview facility within their
file chooser dialogs. Previous to GTK+ 2.4, one needed to
access the #GtkFileSelection widget hierarchy directly to hook
in a preview widget. With #GtkFileChooser, there is a dedicated
API to do this.
Please see the section on
creating preview widgets for more information.
Installing Extra Widgets
Some applications need to install extra widgets in a file
chooser. For example, an application may want to provide a
toggle button to give the user the option of opening a file
read-only.
Please see the section on
creating extra widgets for more information.
New features
New features in #GtkFileChooser include the following:
Ability to select URIs rather than just local files. You
must use a #GtkFileSystem implementation that supports this,
for example GtkFileSystemGnomeVFS.
Present a list of application-specific shortcut folders.
For example, a paint program may want to add a shortcut for
its /usr/share/paint_program/Clipart
folder.
Define custom filters so that not all the files in a folder
are listed. For example, you could filter out backup files,
or show only image files.
To see how to use these features, please consult the
#GtkFileChooser reference documentation.