FileChooserDialog

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

An example GtkFileChooserDialog

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

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

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

Typical usage

In the simplest of cases, you can the following code to use gtk.file_chooser_dialog.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_window_present (GTK_WINDOW (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_window_present (GTK_WINDOW (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 gtk.file_chooser_dialog.FileChooserDialog:

To select a file for opening, use gtk.types.FileChooserAction.Open.
To save a file for the first time, use gtk.types.FileChooserAction.Save, and suggest a name such as “Untitled” with gtk.file_chooser.FileChooser.setCurrentName.
To save a file under a different name, use gtk.types.FileChooserAction.Save, and set the existing file with gtk.file_chooser.FileChooser.setFile.
To choose a folder instead of a filem use gtk.types.FileChooserAction.SelectFolder.

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

Response Codes

gtk.file_chooser_dialog.FileChooserDialog inherits from gtk.dialog.Dialog, so buttons that go in its action area have response codes such as gtk.types.ResponseType.Accept and gtk.types.ResponseType.Cancel. For example, you could call gtk.file_chooser_dialog.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 gtk.types.ResponseType. For most dialog boxes you can use your own custom response codes rather than the ones in gtk.types.ResponseType, but gtk.file_chooser_dialog.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 gtk.file_chooser_dialog.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 gtk.file_chooser_dialog.FileChooserDialog to ensure proper operation.

CSS nodes

gtk.file_chooser_dialog.FileChooserDialog has a single CSS node with the name window and style class .filechooser.

Typical usage
Setting up a file chooser dialog
Response Codes
CSS nodes
Mixed In Members

From mixin FileChooserT!()

Inherited Members

From Dialog
From FileChooser

Detailed Description

class FileChooserDialog : Dialog , FileChooser {}

Mixed In Members

From `mixin FileChooserT!()`

addChoice void addChoice(string id, string label, string[] options, string[] optionLabels): Adds a 'choice' to the file chooser.
addFilter void addFilter(gtk.file_filter.FileFilter filter): Adds filter to the list of filters that the user can select between.
addShortcutFolder bool addShortcutFolder(gio.file.File folder): Adds a folder to be displayed with the shortcut folders in a file chooser.
getAction gtk.types.FileChooserAction 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 gio.file.File getCurrentFolder(): Gets the current folder of chooser as gio.file.File.
getCurrentName string getCurrentName(): Gets the current name in the file selector, as entered by the user.
getFile gio.file.File getFile(): Gets the gio.file.File for the currently selected file in the file selector.
getFiles gio.list_model.ListModel getFiles(): Lists all the selected files and subfolders in the current folder of chooser as gio.file.File.
getFilter gtk.file_filter.FileFilter getFilter(): Gets the current filter.
getFilters gio.list_model.ListModel 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 gio.list_model.ListModel 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.FileChooser.addChoice.
removeFilter void removeFilter(gtk.file_filter.FileFilter filter): Removes filter from the list of filters that the user can select between.
removeShortcutFolder bool removeShortcutFolder(gio.file.File folder): Removes a folder from the shortcut folders in a file chooser.
setAction void setAction(gtk.types.FileChooserAction 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.FileChooser.addChoice.
setCreateFolders void setCreateFolders(bool createFolders): Sets whether file chooser will offer to create new folders.
setCurrentFolder bool setCurrentFolder(gio.file.File file): Sets the current folder for chooser from a gio.file.File.
setCurrentName void setCurrentName(string name): Sets the current name in the file selector, as if entered by the user.
setFile bool setFile(gio.file.File file): Sets file as the current filename for the file chooser.
setFilter void setFilter(gtk.file_filter.FileFilter filter): Sets the current filter.
setSelectMultiple void setSelectMultiple(bool selectMultiple): Sets whether multiple files can be selected in the file chooser.

Inherited Members

From Dialog

addActionWidget void addActionWidget(gtk.widget.Widget child, int responseId): Adds an activatable widget to the action area of a gtk.dialog.Dialog.
addButton gtk.widget.Widget addButton(string buttonText, int responseId): Adds a button with the given text.
getContentArea gtk.box.Box getContentArea(): Returns the content area of dialog.
getHeaderBar gtk.header_bar.HeaderBar getHeaderBar(): Returns the header bar of dialog.
getResponseForWidget int getResponseForWidget(gtk.widget.Widget widget): Gets the response id of a widget in the action area of a dialog.
getWidgetForResponse gtk.widget.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.
connectClose ulong connectClose(T callback, Flag!"After" after): Connect to Close signal.
connectResponse ulong connectResponse(T callback, Flag!"After" after): Connect to Response signal.

From FileChooser

addChoice void addChoice(string id, string label, string[] options, string[] optionLabels): Adds a 'choice' to the file chooser.
addFilter void addFilter(gtk.file_filter.FileFilter filter): Adds filter to the list of filters that the user can select between.
addShortcutFolder bool addShortcutFolder(gio.file.File folder): Adds a folder to be displayed with the shortcut folders in a file chooser.
getAction gtk.types.FileChooserAction 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 gio.file.File getCurrentFolder(): Gets the current folder of chooser as gio.file.File.
getCurrentName string getCurrentName(): Gets the current name in the file selector, as entered by the user.
getFile gio.file.File getFile(): Gets the gio.file.File for the currently selected file in the file selector.
getFiles gio.list_model.ListModel getFiles(): Lists all the selected files and subfolders in the current folder of chooser as gio.file.File.
getFilter gtk.file_filter.FileFilter getFilter(): Gets the current filter.
getFilters gio.list_model.ListModel 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 gio.list_model.ListModel 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.FileChooser.addChoice.
removeFilter void removeFilter(gtk.file_filter.FileFilter filter): Removes filter from the list of filters that the user can select between.
removeShortcutFolder bool removeShortcutFolder(gio.file.File folder): Removes a folder from the shortcut folders in a file chooser.
setAction void setAction(gtk.types.FileChooserAction 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.FileChooser.addChoice.
setCreateFolders void setCreateFolders(bool createFolders): Sets whether file chooser will offer to create new folders.
setCurrentFolder bool setCurrentFolder(gio.file.File file): Sets the current folder for chooser from a gio.file.File.
setCurrentName void setCurrentName(string name): Sets the current name in the file selector, as if entered by the user.
setFile bool setFile(gio.file.File file): Sets file as the current filename for the file chooser.
setFilter void setFilter(gtk.file_filter.FileFilter filter): Sets the current filter.
setSelectMultiple void setSelectMultiple(bool selectMultiple): Sets whether multiple files can be selected in the file chooser.

Detailed Description

Deprecated: Use gtk.file_dialog.FileDialog instead

gtk file_chooser_dialog classes

FileChooserDialog

FileChooserDialog

From mixin FileChooserT!()

From `mixin FileChooserT!()`