GtkFileChooser

GtkFileChooser — File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog

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

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 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 “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