FileChooserDialog


Object Hierarchy:

Object hierarchy for FileChooserDialog

Description:

[ CCode ( type_id = "gtk_file_chooser_dialog_get_type ()" ) ]
public class FileChooserDialog : Dialog, Accessible, Buildable, ConstraintTarget, FileChooser, Native, Root, ShortcutManager

FileChooserDialog is a dialog box suitable for use with “File Open” or “File Save” commands.

This widget works by putting a FileChooserWidget inside a Dialog. It exposes the FileChooser interface, so you can use all of the FileChooser functions on the file chooser dialog as well as those for Dialog.

Note that FileChooserDialog does not have any methods of its own. Instead, you should use the functions that work on a FileChooser.

If you want to integrate well with the platform you should use the FileChooserNative API, which will use a platform-specific dialog if available and fall back to GtkFileChooserDialog otherwise.

Typical usage

In the simplest of cases, you can the following code to use FileChooserDialog to select a file for opening:

static void
on_open_response (GtkDialog *dialog,
int response)
{
if (response == GTK_RESPONSE_ACCEPT)
{
GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);

g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser);

open_file (file);
}

gtk_window_destroy (GTK_WINDOW (dialog));
}

// ...
GtkWidget *dialog;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;

dialog = gtk_file_chooser_dialog_new ("Open File",
parent_window,
action,
_("_Cancel"),
GTK_RESPONSE_CANCEL,
_("_Open"),
GTK_RESPONSE_ACCEPT,
NULL);

gtk_widget_show (dialog);

g_signal_connect (dialog, "response",
G_CALLBACK (on_open_response),
NULL);

To use a dialog for saving, you can use this:

static void
on_save_response (GtkDialog *dialog,
int response)
{
if (response == GTK_RESPONSE_ACCEPT)
{
GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);

g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser);

save_to_file (file);
}

gtk_window_destroy (GTK_WINDOW (dialog));
}

// ...
GtkWidget *dialog;
GtkFileChooser *chooser;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;

dialog = gtk_file_chooser_dialog_new ("Save File",
parent_window,
action,
_("_Cancel"),
GTK_RESPONSE_CANCEL,
_("_Save"),
GTK_RESPONSE_ACCEPT,
NULL);
chooser = GTK_FILE_CHOOSER (dialog);

if (user_edited_a_new_document)
gtk_file_chooser_set_current_name (chooser, _("Untitled document"));
else
gtk_file_chooser_set_file (chooser, existing_filename);

gtk_widget_show (dialog);

g_signal_connect (dialog, "response",
G_CALLBACK (on_save_response),
NULL);

Setting up a file chooser dialog

There are various cases in which you may need to use a FileChooserDialog:

  • To select a file for opening. Use OPEN.
  • To save a file for the first time. Use SAVE, and suggest a name such as “Untitled” with set_current_name.
  • To save a file under a different name. Use SAVE, and set the existing file with set_file.
  • To choose a folder instead of a file. Use SELECT_FOLDER.

Note that old versions of the file chooser’s documentation suggested using set_current_folder in various situations, with the intention of letting the application suggest a reasonable default folder. This is no longer considered to be a good policy, as now the file chooser is able to make good suggestions on its own. In general, you should only cause the file chooser to show a specific folder when it is appropriate to use set_file, i.e. when you are doing a Save As command and you already have a file saved somewhere.

Response Codes

FileChooserDialog inherits from Dialog, so buttons that go in its action area have response codes such as ACCEPT and CANCEL. For example, you could call FileChooserDialog as follows:

GtkWidget *dialog;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;

dialog = gtk_file_chooser_dialog_new ("Open File",
parent_window,
action,
_("_Cancel"),
GTK_RESPONSE_CANCEL,
_("_Open"),
GTK_RESPONSE_ACCEPT,
NULL);

This will create buttons for “Cancel” and “Open” that use predefined response identifiers from ResponseType. For most dialog boxes you can use your own custom response codes rather than the ones in ResponseType, but FileChooserDialog assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes:

This is because FileChooserDialog must intercept responses and switch to folders if appropriate, rather than letting the dialog terminate — the implementation uses these known response codes to know which responses can be blocked if appropriate.

To summarize, make sure you use a predefined response code when you use FileChooserDialog to ensure proper operation.


Namespace: Gtk
Package: gtk4

Content:

Creation methods:

Inherited Members:

All known members inherited from class Gtk.Widget
All known members inherited from interface Gtk.Native
All known members inherited from interface Gtk.Root
All known members inherited from interface Gtk.ShortcutManager