Top |
GtkFileChooserGtkFileChooser — File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog |
Functions
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 |
Types and Values
GtkFileChooser | |
enum | GtkFileChooserAction |
#define | GTK_FILE_CHOOSER_ERROR |
enum | GtkFileChooserError |
Known Implementations
GtkFileChooser is implemented by GtkFileChooserDialog, GtkFileChooserNative and GtkFileChooserWidget.
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
.
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()
.
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
.
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()
.
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
.
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()
.
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.
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.
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.
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
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); } } |
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.
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.
gtk_file_chooser_get_current_folder ()
GFile *
gtk_file_chooser_get_current_folder (GtkFileChooser *chooser
);
Gets the current folder of chooser
as GFile.
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.
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.
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.
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.
gtk_file_chooser_get_filter ()
GtkFileFilter *
gtk_file_chooser_get_filter (GtkFileChooser *chooser
);
Gets the current filter; see gtk_file_chooser_set_filter()
.
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.
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.
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.
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 |
||
id |
id for the added choice |
|
label |
user-visible label for the added choice |
|
options |
ids for the options of the choice, or |
[nullable][array zero-terminated=1] |
option_labels |
user-visible labels for the options, must be the same length as |
[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()
.
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".
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.
Types and Values
enum GtkFileChooserAction
Describes whether a GtkFileChooser is being used to open existing files or to save to a possibly new file.
Members
Indicates open mode. The file chooser will only let the user pick an existing file. |
||
Indicates save mode. The file chooser will let the user pick an existing file, or type in a new filename. |
||
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.
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