GtkFileChooser

GtkFileChooser — File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog

Properties

GtkFileChooserAction action Read / Write
gboolean create-folders Read / Write
GtkFileFilter * filter Read / Write
GListModel * filters Read
gboolean select-multiple Read / Write
GListModel * shortcut-folders Read

Object Hierarchy

    GInterface
    ╰── GtkFileChooser

Prerequisites

GtkFileChooser requires GObject.

Known Implementations

GtkFileChooser is implemented by GtkFileChooserDialog, GtkFileChooserNative and GtkFileChooserWidget.

Includes

#include <gtk/gtk.h>

Description

GtkFileChooser is an interface that can be implemented by file selection widgets. In GTK, the main objects that implement this interface are GtkFileChooserWidget and GtkFileChooserDialog. You do not need to write an object that implements the GtkFileChooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface.

GtkFileChooser allows for shortcuts to various places in the filesystem. In the default implementation these are displayed in the left pane. It may be a bit confusing at first that these shortcuts come from various sources and in various flavours, so lets explain the terminology here:

  • Bookmarks: are created by the user, by dragging folders from the right pane to the left pane, or by using the “Add”. Bookmarks can be renamed and deleted by the user.

  • Shortcuts: can be provided by the application. For example, a Paint program may want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the user.

  • Volumes: are provided by the underlying filesystem abstraction. They are the “roots” of the filesystem.

File Names and Encodings

When the user is finished selecting files in a GtkFileChooser, your program can get the selected filenames as GFiles.

Adding options

You can add extra widgets to a file chooser to provide options that are not present in the default design, by using gtk_file_chooser_add_choice(). Each choice has an identifier and a user visible label; additionally, each choice can have multiple options. If a choice has no option, it will be rendered as a check button with the given label; if a choice has options, it will be rendered as a combo box.

Functions

gtk_file_chooser_set_action ()

void
gtk_file_chooser_set_action (GtkFileChooser *chooser,
                             GtkFileChooserAction action);

Sets the type of operation that the chooser is performing; the user interface is adapted to suit the selected action. For example, an option to create a new folder might be shown if the action is GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is GTK_FILE_CHOOSER_ACTION_OPEN.

Parameters

chooser

a GtkFileChooser

action

the action that the file selector is performing

gtk_file_chooser_get_action ()

GtkFileChooserAction
gtk_file_chooser_get_action (GtkFileChooser *chooser);

Gets the type of operation that the file chooser is performing; see gtk_file_chooser_set_action().

Parameters

chooser

a GtkFileChooser

Returns

the action that the file selector is performing

gtk_file_chooser_set_select_multiple ()

void
gtk_file_chooser_set_select_multiple (GtkFileChooser *chooser,
                                      gboolean select_multiple);

Sets whether multiple files can be selected in the file selector. This is only relevant if the action is set to be GTK_FILE_CHOOSER_ACTION_OPEN or GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.

Parameters

chooser

a GtkFileChooser

select_multiple

TRUE if multiple files can be selected.

gtk_file_chooser_get_select_multiple ()

gboolean
gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser);

Gets whether multiple files can be selected in the file selector. See gtk_file_chooser_set_select_multiple().

Parameters

chooser

a GtkFileChooser

Returns

TRUE if multiple files can be selected.

gtk_file_chooser_set_create_folders ()

void
gtk_file_chooser_set_create_folders (GtkFileChooser *chooser,
                                     gboolean create_folders);

Sets whether file chooser will offer to create new folders. This is only relevant if the action is not set to be GTK_FILE_CHOOSER_ACTION_OPEN.

Parameters

chooser

a GtkFileChooser

create_folders

TRUE if the Create Folder button should be displayed

gtk_file_chooser_get_create_folders ()

gboolean
gtk_file_chooser_get_create_folders (GtkFileChooser *chooser);

Gets whether file chooser will offer to create new folders. See gtk_file_chooser_set_create_folders().

Parameters

chooser

a GtkFileChooser

Returns

TRUE if the Create Folder button should be displayed.

gtk_file_chooser_set_current_name ()

void
gtk_file_chooser_set_current_name (GtkFileChooser *chooser,
                                   const char *name);

Sets the current name in the file selector, as if entered by the user. Note that the name passed in here is a UTF-8 string rather than a filename. This function is meant for such uses as a suggested name in a “Save As...” dialog. You can pass “Untitled.doc” or a similarly suitable suggestion for the name .

If you want to preselect a particular existing file, you should use gtk_file_chooser_set_file() instead.

Please see the documentation for those functions for an example of using gtk_file_chooser_set_current_name() as well.

Parameters

chooser

a GtkFileChooser

name

the filename to use, as a UTF-8 string.

[type filename]

gtk_file_chooser_get_current_name ()

char *
gtk_file_chooser_get_current_name (GtkFileChooser *chooser);

Gets the current name in the file selector, as entered by the user in the text entry for “Name”.

This is meant to be used in save dialogs, to get the currently typed filename when the file itself does not exist yet.

Parameters

chooser

a GtkFileChooser

Returns

The raw text from the file chooser’s “Name” entry. Free this with g_free(). Note that this string is not a full pathname or URI; it is whatever the contents of the entry are. Note also that this string is in UTF-8 encoding, which is not necessarily the system’s encoding for filenames.

gtk_file_chooser_get_file ()

GFile *
gtk_file_chooser_get_file (GtkFileChooser *chooser);

Gets the GFile for the currently selected file in the file selector. If multiple files are selected, one of the files will be returned at random.

If the file chooser is in folder mode, this function returns the selected folder.

Parameters

chooser

a GtkFileChooser

Returns

a selected GFile. You own the returned file; use g_object_unref() to release it.

[transfer full]

gtk_file_chooser_set_file ()

gboolean
gtk_file_chooser_set_file (GtkFileChooser *chooser,
                           GFile *file,
                           GError **error);

Sets file as the current filename for the file chooser, by changing to the file’s parent folder and actually selecting the file in list. If the chooser is in GTK_FILE_CHOOSER_ACTION_SAVE mode, the file’s base name will also appear in the dialog’s file name entry.

If the file name isn’t in the current folder of chooser , then the current folder of chooser will be changed to the folder containing filename .

Note that the file must exist, or nothing will be done except for the directory change.

If you are implementing a save dialog, you should use this function if you already have a file name to which the user may save; for example, when the user opens an existing file and then does Save As... If you don’t have a file name already — for example, if the user just created a new file and is saving it for the first time, do not call this function. Instead, use something similar to this:

static void
prepare_file_chooser (GtkFileChooser *chooser,
                      GFile          *existing_file)
{
  gboolean document_is_new = (existing_file == NULL);

  if (document_is_new)
    {
      GFile *default_file_for_saving = g_file_new_for_path ("./out.txt");
      // the user just created a new document
      gtk_file_chooser_set_current_folder (chooser, default_file_for_saving, NULL);
      gtk_file_chooser_set_current_name (chooser, "Untitled document");
      g_object_unref (default_file_for_saving);
    }
  else
    {
      // the user edited an existing document
      gtk_file_chooser_set_file (chooser, existing_file, NULL);
    }
}

Parameters

chooser

a GtkFileChooser

file

the GFile to set as current

error

location to store the error, or NULL to ignore errors.

[allow-none]

Returns

Not useful.

gtk_file_chooser_get_files ()

GListModel *
gtk_file_chooser_get_files (GtkFileChooser *chooser);

Lists all the selected files and subfolders in the current folder of chooser as GFile.

Parameters

chooser

a GtkFileChooser

Returns

a list model containing a GFile for each selected file and subfolder in the current folder. Free the returned list with g_object_unref().

[transfer full]

gtk_file_chooser_set_current_folder ()

gboolean
gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
                                     GFile *file,
                                     GError **error);

Sets the current folder for chooser from a GFile.

Parameters

chooser

a GtkFileChooser

file

the GFile for the new folder

error

location to store error, or NULL.

Returns

TRUE if the folder could be changed successfully, FALSE otherwise.

gtk_file_chooser_get_current_folder ()

GFile *
gtk_file_chooser_get_current_folder (GtkFileChooser *chooser);

Gets the current folder of chooser as GFile.

Parameters

chooser

a GtkFileChooser

Returns

the GFile for the current folder.

[transfer full]

gtk_file_chooser_add_filter ()

void
gtk_file_chooser_add_filter (GtkFileChooser *chooser,
                             GtkFileFilter *filter);

Adds filter to the list of filters that the user can select between. When a filter is selected, only files that are passed by that filter are displayed.

Note that the chooser takes ownership of the filter if it is floating, so you have to ref and sink it if you want to keep a reference.

Parameters

chooser

a GtkFileChooser

filter

a GtkFileFilter.

[transfer none]

gtk_file_chooser_remove_filter ()

void
gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
                                GtkFileFilter *filter);

Removes filter from the list of filters that the user can select between.

Parameters

chooser

a GtkFileChooser

filter

a GtkFileFilter

gtk_file_chooser_get_filters ()

GListModel *
gtk_file_chooser_get_filters (GtkFileChooser *chooser);

Gets the current set of user-selectable filters, as a list model; see gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter().

You should not modify the returned list model. Future changes to chooser may or may not affect the returned model.

Parameters

chooser

a GtkFileChooser

Returns

a GListModel containing the current set of user-selectable filters.

[transfer full]

gtk_file_chooser_set_filter ()

void
gtk_file_chooser_set_filter (GtkFileChooser *chooser,
                             GtkFileFilter *filter);

Sets the current filter; only the files that pass the filter will be displayed. If the user-selectable list of filters is non-empty, then the filter should be one of the filters in that list. Setting the current filter when the list of filters is empty is useful if you want to restrict the displayed set of files without letting the user change it.

Parameters

chooser

a GtkFileChooser

filter

a GtkFileFilter

gtk_file_chooser_get_filter ()

GtkFileFilter *
gtk_file_chooser_get_filter (GtkFileChooser *chooser);

Gets the current filter; see gtk_file_chooser_set_filter().

Parameters

chooser

a GtkFileChooser

Returns

the current filter, or NULL.

[nullable][transfer none]

gtk_file_chooser_add_shortcut_folder ()

gboolean
gtk_file_chooser_add_shortcut_folder (GtkFileChooser *chooser,
                                      GFile *folder,
                                      GError **error);

Adds a folder to be displayed with the shortcut folders in a file chooser.

Parameters

chooser

a GtkFileChooser

folder

a GFile for the folder to add

error

location to store error, or NULL

Returns

TRUE if the folder could be added successfully, FALSE otherwise.

gtk_file_chooser_remove_shortcut_folder ()

gboolean
gtk_file_chooser_remove_shortcut_folder
                               (GtkFileChooser *chooser,
                                GFile *folder,
                                GError **error);

Removes a folder from the shortcut folders in a file chooser.

Parameters

chooser

a GtkFileChooser

folder

a GFile for the folder to remove

error

location to store error, or NULL

Returns

TRUE if the folder could be removed successfully, FALSE otherwise.

gtk_file_chooser_get_shortcut_folders ()

GListModel *
gtk_file_chooser_get_shortcut_folders (GtkFileChooser *chooser);

Queries the list of shortcut folders in the file chooser, as set by gtk_file_chooser_add_shortcut_folder().

You should not modify the returned list model. Future changes to chooser may or may not affect the returned model.

Parameters

chooser

a GtkFileChooser

Returns

A list model of GFiles.

[transfer full]

gtk_file_chooser_add_choice ()

void
gtk_file_chooser_add_choice (GtkFileChooser *chooser,
                             const char *id,
                             const char *label,
                             const char **options,
                             const char **option_labels);

Adds a 'choice' to the file chooser. This is typically implemented as a combobox or, for boolean choices, as a checkbutton. You can select a value using gtk_file_chooser_set_choice() before the dialog is shown, and you can obtain the user-selected value in the ::response signal handler using gtk_file_chooser_get_choice().

Parameters

chooser

a GtkFileChooser

id

id for the added choice

label

user-visible label for the added choice

options

ids for the options of the choice, or NULL for a boolean choice.

[nullable][array zero-terminated=1]

option_labels

user-visible labels for the options, must be the same length as options .

[nullable][array zero-terminated=1]

gtk_file_chooser_remove_choice ()

void
gtk_file_chooser_remove_choice (GtkFileChooser *chooser,
                                const char *id);

Removes a 'choice' that has been added with gtk_file_chooser_add_choice().

Parameters

chooser

a GtkFileChooser

id

the ID of the choice to remove

gtk_file_chooser_set_choice ()

void
gtk_file_chooser_set_choice (GtkFileChooser *chooser,
                             const char *id,
                             const char *option);

Selects an option in a 'choice' that has been added with gtk_file_chooser_add_choice(). For a boolean choice, the possible options are "true" and "false".

Parameters

chooser

a GtkFileChooser

id

the ID of the choice to set

option

the ID of the option to select

gtk_file_chooser_get_choice ()

const char *
gtk_file_chooser_get_choice (GtkFileChooser *chooser,
                             const char *id);

Gets the currently selected option in the 'choice' with the given ID.

Parameters

chooser

a GtkFileChooser

id

the ID of the choice to get

Returns

the ID of the currently selected option

Types and Values

GtkFileChooser

typedef struct _GtkFileChooser GtkFileChooser;

enum GtkFileChooserAction

Describes whether a GtkFileChooser is being used to open existing files or to save to a possibly new file.

Members

GTK_FILE_CHOOSER_ACTION_OPEN

Indicates open mode. The file chooser will only let the user pick an existing file.

GTK_FILE_CHOOSER_ACTION_SAVE

Indicates save mode. The file chooser will let the user pick an existing file, or type in a new filename.

GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER

Indicates an Open mode for selecting folders. The file chooser will let the user pick an existing folder.

GTK_FILE_CHOOSER_ERROR

#define GTK_FILE_CHOOSER_ERROR (gtk_file_chooser_error_quark ())

Used to get the GError quark for GtkFileChooser errors.

enum GtkFileChooserError

These identify the various errors that can occur while calling GtkFileChooser functions.

Members

GTK_FILE_CHOOSER_ERROR_NONEXISTENT

Indicates that a file does not exist.

GTK_FILE_CHOOSER_ERROR_BAD_FILENAME

Indicates a malformed filename.

GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS

Indicates a duplicate path (e.g. when adding a bookmark).

GTK_FILE_CHOOSER_ERROR_INCOMPLETE_HOSTNAME

Indicates an incomplete hostname (e.g. "http://foo" without a slash after that).

Property Details

The “action” property

  “action”                   GtkFileChooserAction

The type of operation that the file selector is performing.

Owner: GtkFileChooser

Flags: Read / Write

Default value: GTK_FILE_CHOOSER_ACTION_OPEN

The “create-folders” property

  “create-folders”           gboolean

Whether a file chooser not in GTK_FILE_CHOOSER_ACTION_OPEN mode will offer the user to create new folders.

Owner: GtkFileChooser

Flags: Read / Write

Default value: TRUE

The “filter” property

  “filter”                   GtkFileFilter *

The current filter for selecting which files are displayed.

Owner: GtkFileChooser

Flags: Read / Write

The “filters” property

  “filters”                  GListModel *

A GListModel containing the filters that have been added with gtk_file_chooser_add_filter().

The returned object should not be modified. It may or may not be updated for later changes.

Owner: GtkFileChooser

Flags: Read

The “select-multiple” property

  “select-multiple”          gboolean

Whether to allow multiple files to be selected.

Owner: GtkFileChooser

Flags: Read / Write

Default value: FALSE

The “shortcut-folders” property

  “shortcut-folders”         GListModel *

A GListModel containing the shortcut folders that have been added with gtk_file_chooser_add_shortcut_folder().

The returned object should not be modified. It may or may not be updated for later changes.

Owner: GtkFileChooser

Flags: Read

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk4/4.0/GtkFileChooser.html