|« Main Page | Index|
Table of Contents
Starting with GTK+ 2.4, GtkFileChooser is the new set of APIs for file selection widgets and dialogs. Previous versions of GTK+ used GtkFileSelection, which had numerous problems. GtkFileChooser overcomes these problems and provides the programmer with a powerful file selection interface that has several new features. With GtkFileChooser you can select URIs rather than just local files but you must use a GtkFileSystem implementation that supports this, for example the gnome-vfs back end. GtkFileChooser lets you present a list of application-specific shortcut folders to the user. For example, a paint program may want to add a shortcut for its clipart folder. GtkFileChooser also lets you 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.
GtkFileChooser is an abstract interface that can be implemented by widgets that perform file selection tasks. The two widgets in GTK+ that implement this interface are GtkFileChooserDialog and GtkFileChooserWidget. Most applications only 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. In XFC, Gtk::FileChooser, Gtk::FileChooserDialog and Gtk::FileChooserWidget are the corresponding C++ classes these GTK+ objects.
In single-selection mode you can retrieve the name of the selected file from the local file system as a filename or a URI:
The first method returns the name as a filename and the second as a fully formed URI.
In multiple-selection mode you can call the following methods to fill a vector with a list of the selected filenames or URIs:
The first method fills a vector with the filenames of all the selected files and subfolders in the current folder of the file chooser. The second method fills a vector with the URIs of all the selected files and subfolders. Both methods return true if any files were selected. Note that you may not be able to directly set a filename as the text of a Gtk::Label widget unless you convert it first to UTF-8, which all GTK+ widgets expect.
To convert the selected filename to UTF-8 so it can be passed to a widget, call the static Xfc::String method:
This method converts 'opsysstring' from the encoding used for filenames into a UTF-8 string. Possible errors are those defined in GConvertError.
To convert a UTF-8 string to the encoding used for filenames, call the Xfc::String method:
To set the selection mode of the FileChooser, use the following method:
If 'select_multiple' is true, multiple files can be selected.
You can configure FileChooser to select files or folders by calling this method:
The 'action' argument can be one of the following values from the Gtk::FileChooserAction enum:
To install or retrieve a preview widget, use the following methods respectively:
The 'preview_widget' argument is a reference to the widget that will display the preview. After installing the preview widget, connect to the FileChooser 'update-preview' signal to get notified when you need to update the contents of the preview. To make the connection use the signal's proxy signal function:
Your callback slot should call this next method to see what needs previewing:
Once you have generated the preview for the corresponding file, you must indicate whether your callback slot was able to successfully generate a preview:
Here is an example of how to install and use a preview widget:
Use the following method to insert an additional widget in a file chooser:
The 'extra_widget' argument is the extra widget to insert. If you want to insert more than one extra widget in the file chooser, you can use a container such as a Gtk::VBox or a Gtk::Table and pack your widgets in it. Then, set the container as the extra widget.
To create a FileChooserDialog, you simply call one the following constructors:
The first constructor creates a file chooser dialog with no parent. The second constructor creates a file chooser dialog with the specified parent. The 'title' argument is the name for the dialog and 'action' is the dialog open or save mode. The 'backend' argument is the name of the specific filesystem back end to use, or null for the default, which is usual case.
To create a FileChooserOpenDialog, you can call the following constructors:
The first constructor creates a 'File/Open' file chooser dialog with the title "Open...". The second constructor creates a file chooser dialog using the specified title. The 'parent' argument is the Gtk::Window that is the transient parent for the dialog, or null if there is no parent.
To create a FileChooserSaveAsDialog, you can call the following constructors:
The first constructor creates a 'File/Save as' file chooser dialog with the title "Save as...". The second constructor creates a file chooser dialog using the specified title. The 'parent' argument is the Gtk::Window that is the transient parent for the dialog, or null if there is no parent.
To add buttons to a file chooser dialog, call one of the Gtk::Dialog add_button() methods. To display a modal dialog just call Gtk::Dialog::run(). Alternatively, you could display the dialog as an ordinary window. There is a good test program in the <tests/filechooser> subdirectory that shows you how to create a FileChooserDialog that uses the various options.