## GtkFileChooser GtkFileChooser — File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog |

## Functions

void | gtk_file_chooser_set_action ()
GtkFileChooserAction | gtk_file_chooser_get_action ()
void | gtk_file_chooser_set_select_multiple ()
gboolean | gtk_file_chooser_get_select_multiple ()
void | gtk_file_chooser_set_create_folders ()
gboolean | gtk_file_chooser_get_create_folders ()
void | gtk_file_chooser_set_current_name ()
gchar * | gtk_file_chooser_get_current_name ()
GFile * | gtk_file_chooser_get_file ()
gboolean | gtk_file_chooser_set_file ()
gboolean | gtk_file_chooser_select_file ()
void | gtk_file_chooser_unselect_file ()
void | gtk_file_chooser_select_all ()
void | gtk_file_chooser_unselect_all ()
GSList * | gtk_file_chooser_get_files ()
gboolean | gtk_file_chooser_set_current_folder ()
GFile * | gtk_file_chooser_get_current_folder ()
void | gtk_file_chooser_add_filter ()
void | gtk_file_chooser_remove_filter ()
GSList * | gtk_file_chooser_list_filters ()
void | gtk_file_chooser_set_filter ()
GtkFileFilter * | gtk_file_chooser_get_filter ()
gboolean | gtk_file_chooser_add_shortcut_folder ()
gboolean | gtk_file_chooser_remove_shortcut_folder ()
GSList * | gtk_file_chooser_list_shortcut_folders ()
void | gtk_file_chooser_add_choice ()
void | gtk_file_chooser_remove_choice ()
void | gtk_file_chooser_set_choice ()
const char * | gtk_file_chooser_get_choice ()

## Properties

GtkFileChooserAction | action | Read / Write
gboolean | create-folders | Read / Write
GtkFileFilter * | filter | Read / Write
gboolean | select-multiple | Read / Write

## Signals

void | current-folder-changed | Run Last
void | file-activated | Run Last
void | selection-changed | Run Last

## Types and Values

| GtkFileChooser
enum | GtkFileChooserAction
#define | GTK_FILE_CHOOSER_ERROR
enum | GtkFileChooserError

## Object Hierarchy

        GInterface
        ╰── GtkFileChooser

## Prerequisites

GtkFileChooser requires GObject.

## Known Implementations

GtkFileChooser is implemented by GtkFileChooserButton, GtkFileChooserDialog 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, GtkFileChooserDialog, and GtkFileChooserButton. 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 choser 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 choser 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 gchar *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 ()

    gchar *
    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` . This is equivalent to a sequence of `gtk_file_chooser_unselect_all()` followed by `gtk_file_chooser_select_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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    if (document_is_new)
      {
        // the user just created a new document
        gtk_file_chooser_set_current_folder (chooser, default_file_for_saving);
        gtk_file_chooser_set_current_name (chooser, "Untitled document");
      }
    else
      {
        // the user edited an existing document
        gtk_file_chooser_set_file (chooser, existing_file);
      }

#### 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_select_file ()

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

Selects the file referred to by `file` .

#### Parameters

chooser | a GtkFileChooser |
file | the file to select |
error | location to store error, or `NULL`. | [allow-none]

#### Returns

Not useful.

### gtk_file_chooser_unselect_file ()

    void
    gtk_file_chooser_unselect_file (GtkFileChooser *chooser,
                                    GFile *file);

Unselects the file referred to by `file` . If the file is not in the current directory, does not exist, or is otherwise not currently selected, does nothing.

#### Parameters

chooser | a GtkFileChooser |
file | a GFile |

### gtk_file_chooser_select_all ()

    void
    gtk_file_chooser_select_all (GtkFileChooser *chooser);

Selects all the files in the current folder of a file chooser.

#### Parameters

chooser | a GtkFileChooser |

### gtk_file_chooser_unselect_all ()

    void
    gtk_file_chooser_unselect_all (GtkFileChooser *chooser);

Unselects all the files in the current folder of a file chooser.

#### Parameters

chooser | a GtkFileChooser |

### gtk_file_chooser_get_files ()

    GSList *
    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 containing a GFile for each selected file and subfolder in the current folder. Free the returned list with `g_slist_free()`, and the files with `g_object_unref()`.

[element-type GFile][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_list_filters ()

    GSList *
    gtk_file_chooser_list_filters (GtkFileChooser *chooser);

Lists the current set of user-selectable filters; see `gtk_file_chooser_add_filter()`, `gtk_file_chooser_remove_filter()`.

#### Parameters

chooser | a GtkFileChooser |

#### Returns

a GSList containing the current set of user selectable filters. The contents of the list are owned by GTK+, but you must free the list itself with `g_slist_free()` when you are done with it.

[element-type GtkFileFilter][transfer container]

### 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_list_shortcut_folders ()

    GSList *
    gtk_file_chooser_list_shortcut_folders
                                   (GtkFileChooser *chooser);

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

#### Parameters

chooser | a GtkFileChooser |

#### Returns

A list of folder filenames, or `NULL` if there are no shortcut folders.

[nullable][element-type Gio.File][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 currenly 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 `“select-multiple”` property

      “select-multiple”          gboolean

Whether to allow multiple files to be selected.

Owner: GtkFileChooser

Flags: Read / Write

Default value: FALSE

## Signal Details

### The `“current-folder-changed”` signal

    void
    user_function (GtkFileChooser *chooser,
                   gpointer        user_data)

This signal is emitted when the current folder in a GtkFileChooser changes. This can happen due to the user performing some action that changes folders, such as selecting a bookmark or visiting a folder on the file list. It can also happen as a result of calling a function to explicitly change the current folder in a file chooser.

Normally you do not need to connect to this signal, unless you need to keep track of which folder a file chooser is showing.

See also: `gtk_file_chooser_set_current_folder()`, `gtk_file_chooser_get_current_folder()`,

#### Parameters

chooser | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“file-activated”` signal

    void
    user_function (GtkFileChooser *chooser,
                   gpointer        user_data)

This signal is emitted when the user "activates" a file in the file chooser. This can happen by double-clicking on a file in the file list, or by pressing `Enter`.

Normally you do not need to connect to this signal. It is used internally by GtkFileChooserDialog to know when to activate the default button in the dialog.

See also: `gtk_file_chooser_get_file()`, `gtk_file_chooser_get_files()`

#### Parameters

chooser | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“selection-changed”` signal

    void
    user_function (GtkFileChooser *chooser,
                   gpointer        user_data)

This signal is emitted when there is a change in the set of selected files in a GtkFileChooser. This can happen when the user modifies the selection with the mouse or the keyboard, or when explicitly calling functions to change the selection.

Normally you do not need to connect to this signal, as it is easier to wait for the file chooser to finish running, and then to get the list of selected files using the functions mentioned below.

#### Parameters

chooser | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

GtkFileChooserDialog, GtkFileChooserWidget, GtkFileChooserButton