Xfce Foundation Classes
 « Main Page | Index

File Chooser

Table of Contents

  1. Selection Modes
  2. Adding a Preview Widget
  3. Adding Extra Widgets
  4. Creating a FileChooserDialog

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.

Selection Modes

FileChooser can be used in two modes, to select a single file at a time or to select multiple files. When the user is finished selecting files, your program can retrieve the selected names as either 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. For this reason, FileChooser methods that pass or return a filename use a std::string as the data type, not an Xfc::String. Please see the GLib documentation for more details about this variable.

In single-selection mode you can retrieve the name of the selected file from the local file system as a filename or a URI:

std::string get_filename() const;

String get_uri() const;

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:

bool get_filenames(std::vector<std::string>& filenames) const;

bool get_uris(std::vector<String>& uris) const;

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:

String from_filename(const std::string& opsysstring, G::Error *error = 0);

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:

std::string to_filename(G::Error *error = 0) const;

To set the selection mode of the FileChooser, use the following method:

void set_select_multiple(bool select_multiple);

If 'select_multiple' is true, multiple files can be selected.

You can configure FileChooser to select files or folders by calling this method:

void set_action(FileChooserAction action);

The 'action' argument can be one of the following values from the Gtk::FileChooserAction enum:
  • FILE_CHOOSER_ACTION_OPEN - indicates open mode; The file chooser will only let the user pick an existing file.
  • FILE_CHOOSER_ACTION_SAVE - indicates save mode; The file chooser will let the user pick an existing file,
  • FILE_CHOOSER_ACTION_SELECT_FOLDER - indicates an Open mode for selecting folders; The file chooser will let the user pick an existing folder.
  • FILE_CHOOSER_ACTION_CREATE_FOLDER - indicates a mode for creating a new folder; The file chooser will let the user name an existing or new folder.

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 or retrieve a preview widget, use the following methods respectively:

void set_preview_widget(Widget& preview_widget);

Gtk::Widget* get_preview_widget() const;

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:

const UpdatePreviewSignalProxy signal_update_preview();

Your callback slot should call this next method to see what needs previewing:

std::string get_preview_filename() const;

Once you have generated the preview for the corresponding file, you must indicate whether your callback slot was able to successfully generate a preview:

void set_preview_widget_active(bool active);

Here is an example of how to install and use a preview widget:

MyWindow::MyWindow()
{
    Gtk::Image *preview = new Gtk::Image;
    file_chooser->set_preview_widget(*preview);
    file_chooser->signal_update_preview().connect(sigc::bind(sigc::mem_fun(this, &MyWindow::on_update_preview), preview);
    ...
} 

void
MyWindow::on_update_preview(Gtk::Image *preview)
{
    std::string filename = file_chooser->get_preview_filename();
    Pointer<Gdk::Pixbuf> pixbuf = Gdk::Pixbuf::create(filename, 128, 128);
    preview->set(pixbuf);
    file_chooser->set_preview_widget_active(!preview.null());
}

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.

Use the following method to insert an additional widget in a file chooser:

void set_extra_widget(Widget& extra_widget);

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.

Creating a FileChooserDialog

FileChooserDialog is the base class for two convenience dialogs: FileChooserOpenDialog and FileChooserSaveAsDialog. These dialogs are simpler to create because they use the appropriate default values. FileChooserDialog is derived from Gtk::Dialog and Gtk::FileChooser so it is both a Dialog and a FileChooser.

To create a FileChooserDialog, you simply call one the following constructors:

FileChooserDialog(const String& title, FileChooserAction action, const char *backend = 0);
   
FileChooserDialog(const String& title, Gtk::Window *parent, FileChooserAction action, const char *backend = 0);

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:

FileChooserOpenDialog(Gtk::Window *parent = 0);
  
FileChooserOpenDialog(const String& title, Gtk::Window *parent = 0);

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:

FileChooserSaveAsDialog(Gtk::Window *parent = 0);
  
FileChooserSaveAsDialog(const String& title, Gtk::Window *parent = 0);

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.

Copyright © 2004-2005 The XFC Development Team Top
 XFC 4.4