FileChooserDialog

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

An example GtkFileChooserDialog

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

Note that GtkFileChooserDialog does not have any methods of its own. Instead, you should use the functions that work on a [iface@Gtk.FileChooser].

If you want to integrate well with the platform you should use the [class@Gtk.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 GtkFileChooserDialog 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 GtkFileChooserDialog:

- To select a file for opening, use %GTK_FILE_CHOOSER_ACTION_OPEN.

- To save a file for the first time, use %GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as “Untitled” with [method@Gtk.FileChooser.set_current_name].

- To save a file under a different name, use %GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing file with [method@Gtk.FileChooser.set_file].

- To choose a folder instead of a filem use %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.

In general, you should only cause the file chooser to show a specific folder when it is appropriate to use [method@Gtk,FileChooser.set_file], i.e. when you are doing a “Save As” command and you already have a file saved somewhere.

Response Codes

GtkFileChooserDialog inherits from [class@Gtk.Dialog], so buttons that go in its action area have response codes such as %GTK_RESPONSE_ACCEPT and %GTK_RESPONSE_CANCEL. For example, you could call [ctor@Gtk.FileChooserDialog.new] 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 [enum@Gtk.ResponseType]. For most dialog boxes you can use your own custom response codes rather than the ones in [enum@Gtk.ResponseType], but GtkFileChooserDialog assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes:

- %GTK_RESPONSE_ACCEPT - %GTK_RESPONSE_OK - %GTK_RESPONSE_YES - %GTK_RESPONSE_APPLY

This is because GtkFileChooserDialog 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 GtkFileChooserDialog to ensure proper operation.

class FileChooserDialog : Dialog , FileChooserIF {

protected

GtkFileChooserDialog* gtkFileChooserDialog;

GtkFileChooserDialog* getFileChooserDialogStruct(bool transferOwnership);

void* getStruct();

this(GtkFileChooserDialog* gtkFileChooserDialog, bool ownedRef);

mixin FileChooserT!(GtkFileChooserDialog) ;

this(string title, Window parent, FileChooserAction action, string[] buttonsText, ResponseType[] responses);

static GType getType();

}

Constructors

this this(GtkFileChooserDialog* gtkFileChooserDialog, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(string title, Window parent, FileChooserAction action, string[] buttonsText, ResponseType[] responses): Creates a new FileChooserDialog. This function is analogous to gtk_dialog_new_with_buttons().

Members

Functions

getFileChooserDialogStruct GtkFileChooserDialog* getFileChooserDialogStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*

Mixins

__anonymous mixin FileChooserT!(GtkFileChooserDialog): Undocumented in source.

Static functions

getType GType getType()

Variables

gtkFileChooserDialog GtkFileChooserDialog* gtkFileChooserDialog;: the main Gtk struct

Inherited Members

From Dialog

gtkDialog GtkDialog* gtkDialog;: the main Gtk struct
getDialogStruct GtkDialog* getDialogStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
addButtons void addButtons(string[] buttonsText, ResponseType[] responses)
getType GType getType()
addActionWidget void addActionWidget(Widget child, int responseId): Adds an activatable widget to the action area of a GtkDialog.
addButton Widget addButton(string buttonText, int responseId): Adds a button with the given text.
getContentArea Box getContentArea(): Returns the content area of @dialog.
getHeaderBar HeaderBar getHeaderBar(): Returns the header bar of @dialog.
getResponseForWidget int getResponseForWidget(Widget widget): Gets the response id of a widget in the action area of a dialog.
getWidgetForResponse Widget getWidgetForResponse(int responseId): Gets the widget button that uses the given response ID in the action area of a dialog.
response void response(int responseId): Emits the ::response signal with the given response ID.
setDefaultResponse void setDefaultResponse(int responseId): Sets the default widget for the dialog based on the response ID.
setResponseSensitive void setResponseSensitive(int responseId, bool setting): A convenient way to sensitize/desensitize dialog buttons.
addOnClose gulong addOnClose(void delegate(Dialog) dlg, ConnectFlags connectFlags): Emitted when the user uses a keybinding to close the dialog.
addOnResponse gulong addOnResponse(void delegate(int, Dialog) dlg, ConnectFlags connectFlags): Emitted when an action widget is clicked.

From FileChooserIF

getFileChooserStruct GtkFileChooser* getFileChooserStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
getType GType getType()
addChoice void addChoice(string id, string label, string[] options, string[] optionLabels): Adds a 'choice' to the file chooser.
addFilter void addFilter(FileFilter filter): Adds @filter to the list of filters that the user can select between.
addShortcutFolder bool addShortcutFolder(FileIF folder): Adds a folder to be displayed with the shortcut folders in a file chooser.
getAction GtkFileChooserAction getAction(): Gets the type of operation that the file chooser is performing.
getChoice string getChoice(string id): Gets the currently selected option in the 'choice' with the given ID.
getCreateFolders bool getCreateFolders(): Gets whether file chooser will offer to create new folders.
getCurrentFolder FileIF getCurrentFolder(): Gets the current folder of @chooser as #GFile.
getCurrentName string getCurrentName(): Gets the current name in the file selector, as entered by the user.
getFile FileIF getFile(): Gets the GFile for the currently selected file in the file selector.
getFiles ListModelIF getFiles(): Lists all the selected files and subfolders in the current folder of @chooser as #GFile.
getFilter FileFilter getFilter(): Gets the current filter.
getFilters ListModelIF getFilters(): Gets the current set of user-selectable filters, as a list model.
getSelectMultiple bool getSelectMultiple(): Gets whether multiple files can be selected in the file chooser.
getShortcutFolders ListModelIF getShortcutFolders(): Queries the list of shortcut folders in the file chooser.
removeChoice void removeChoice(string id): Removes a 'choice' that has been added with gtk_file_chooser_add_choice().
removeFilter void removeFilter(FileFilter filter): Removes @filter from the list of filters that the user can select between.
removeShortcutFolder bool removeShortcutFolder(FileIF folder): Removes a folder from the shortcut folders in a file chooser.
setAction void setAction(GtkFileChooserAction action): Sets the type of operation that the chooser is performing.
setChoice void setChoice(string id, string option): Selects an option in a 'choice' that has been added with gtk_file_chooser_add_choice().
setCreateFolders void setCreateFolders(bool createFolders): Sets whether file chooser will offer to create new folders.
setCurrentFolder bool setCurrentFolder(FileIF file): Sets the current folder for @chooser from a #GFile.
setCurrentName void setCurrentName(string name): Sets the current name in the file selector, as if entered by the user.
setFile bool setFile(FileIF file): Sets @file as the current filename for the file chooser.
setFilter void setFilter(FileFilter filter): Sets the current filter.
setSelectMultiple void setSelectMultiple(bool selectMultiple): Sets whether multiple files can be selected in the file chooser.