Gtk.FileDialog¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`get_accept_label` ()
	`get_default_filter` ()
	`get_filters` ()
	`get_initial_file` ()
	`get_initial_folder` ()
	`get_initial_name` ()
	`get_modal` ()
	`get_title` ()
	`open` (parent, cancellable, callback, *user_data)
	`open_finish` (result)
	`open_multiple` (parent, cancellable, callback, *user_data)
	`open_multiple_finish` (result)
	`open_multiple_text_files` (parent, cancellable, callback, *user_data)
	`open_multiple_text_files_finish` (result)
	`open_text_file` (parent, cancellable, callback, *user_data)
	`open_text_file_finish` (result)
	`save` (parent, cancellable, callback, *user_data)
	`save_finish` (result)
	`save_text_file` (parent, cancellable, callback, *user_data)
	`save_text_file_finish` (result)
	`select_folder` (parent, cancellable, callback, *user_data)
	`select_folder_finish` (result)
	`select_multiple_folders` (parent, cancellable, callback, *user_data)
	`select_multiple_folders_finish` (result)
	`set_accept_label` (accept_label)
	`set_default_filter` (filter)
	`set_filters` (filters)
	`set_initial_file` (file)
	`set_initial_folder` (folder)
	`set_initial_name` (name)
	`set_modal` (modal)
	`set_title` (title)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags
`accept-label`	`str`	r/w/en
`default-filter`	`Gtk.FileFilter`	r/w/en
`filters`	`Gio.ListModel`	r/w/en
`initial-file`	`Gio.File`	r/w/en
`initial-folder`	`Gio.File`	r/w/en
`initial-name`	`str`	r/w/en
`modal`	`bool`	r/w/en
`title`	`str`	r/w/en

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Gtk.FileDialog(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Gtk.FileDialogClass

Asynchronous API to present a file chooser dialog.

GtkFileDialog collects the arguments that are needed to present the dialog to the user, such as a title for the dialog and whether it should be modal.

The dialog is shown with [method`Gtk`.FileDialog.open], [method`Gtk`.FileDialog.save], etc.

New in version 4.10.

classmethod new()[source]¶

Returns:: the new GtkFileDialog
Return type:: Gtk.FileDialog

Creates a new GtkFileDialog object.

New in version 4.10.

get_accept_label()[source]¶

Returns:: the label shown on the file chooser’s accept button
Return type:: str or None

Retrieves the text used by the dialog on its accept button.

New in version 4.10.

get_default_filter()[source]¶

Returns:: the default filter
Return type:: Gtk.FileFilter or None

Gets the filter that will be selected by default in the file chooser dialog.

New in version 4.10.

get_filters()[source]¶

Returns:: the filters, as a list model of [class`Gtk`.FileFilter]
Return type:: Gio.ListModel or None

Gets the filters that will be offered to the user in the file chooser dialog.

New in version 4.10.

get_initial_file()[source]¶

Returns:: the file
Return type:: Gio.File or None

Gets the file that will be initially selected in the file chooser dialog.

New in version 4.10.

get_initial_folder()[source]¶

Returns:: the folder
Return type:: Gio.File or None

Gets the folder that will be set as the initial folder in the file chooser dialog.

New in version 4.10.

get_initial_name()[source]¶

Returns:: the name
Return type:: str or None

Gets the filename that will be initially selected.

New in version 4.10.

get_modal()[source]¶

Returns:: true if the file chooser dialog is modal
Return type:: bool

Returns whether the file chooser dialog blocks interaction with the parent window while it is presented.

New in version 4.10.

get_title()[source]¶

Returns:: the title
Return type:: str

Returns the title that will be shown on the file chooser dialog.

New in version 4.10.

open(parent, cancellable, callback, *user_data)[source]¶

Parameters:

parent (Gtk.Window or None) – the parent window
cancellable (Gio.Cancellable or None) – a cancellable to cancel the operation
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation is complete
user_data (object or None) – data to pass to callback

Presents a file chooser dialog to the user.

The file chooser dialog will be set up to select a single file.

The callback will be called when the dialog is dismissed.

New in version 4.10.

open_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – the result
Raises:: GLib.Error
Returns:: the file that was selected
Return type:: Gio.File or None

Finishes the [method`Gtk`.FileDialog.open] call.

New in version 4.10.

open_multiple(parent, cancellable, callback, *user_data)[source]¶

Parameters:

parent (Gtk.Window or None) – the parent window
cancellable (Gio.Cancellable or None) – a cancellable to cancel the operation
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation is complete
user_data (object or None) – data to pass to callback

Presents a file chooser dialog to the user.

The file chooser dialog will be set up to select multiple files.

The file chooser dialog will initially be opened in the directory [property`Gtk`.FileDialog:initial-folder].

The callback will be called when the dialog is dismissed.

New in version 4.10.

open_multiple_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – the result
Raises:: GLib.Error
Returns:: the files that were selected, as a list model of [iface`Gio`.File]
Return type:: Gio.ListModel or None

Finishes the [method`Gtk`.FileDialog.open] call.

New in version 4.10.

open_multiple_text_files(parent, cancellable, callback, *user_data)[source]¶

Parameters:

parent (Gtk.Window or None) – the parent window
cancellable (Gio.Cancellable or None) – a cancellable to cancel the operation
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation is complete
user_data (object or None) – data to pass to callback

Presents a file chooser dialog to the user.

The file chooser dialog will be set up to select multiple files.

The file chooser dialog will initially be opened in the directory [property`Gtk`.FileDialog:initial-folder].

In contrast to [method`Gtk`.FileDialog.open], this function lets the user select the text encoding for the files, if possible.

The callback will be called when the dialog is dismissed.

New in version 4.18.

open_multiple_text_files_finish(result)[source]¶

Parameters:

result (Gio.AsyncResult) – the result

Raises:

GLib.Error

Returns:

the files that were selected, as a list model of [iface`Gio`.File]

encoding:: return location for the text encoding to use

Return type:

(Gio.ListModel or None, encoding: str)

Finishes the [method`Gtk`.FileDialog.open] call.

New in version 4.18.

open_text_file(parent, cancellable, callback, *user_data)[source]¶

Parameters:

parent (Gtk.Window or None) – the parent GtkWindow
cancellable (Gio.Cancellable or None) – a GCancellable to cancel the operation
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation is complete
user_data (object or None) – data to pass to callback

Initiates a file selection operation by presenting a file chooser dialog to the user.

In contrast to [method`Gtk`.FileDialog.open], this function lets the user select the text encoding for the file, if possible.

The callback will be called when the dialog is dismissed.

New in version 4.18.

open_text_file_finish(result)[source]¶

Parameters:

result (Gio.AsyncResult) – a GAsyncResult

Raises:

GLib.Error

Returns:

the file that was selected

encoding:: return location for the text encoding to use

Return type:

(Gio.File or None, encoding: str)

Finishes the [method`Gtk`.FileDialog.open_text_file] call and returns the resulting file and text encoding.

If the user has explicitly selected a text encoding to use for the file, then encoding will be set to a codeset name that is suitable for passing to iconv_open(). Otherwise, it will be NULL.

New in version 4.18.

save(parent, cancellable, callback, *user_data)[source]¶

Parameters:

parent (Gtk.Window or None) – the parent window
cancellable (Gio.Cancellable or None) – a cancellable to cancel the operation
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation is complete
user_data (object or None) – data to pass to callback

Presents a file chooser dialog to the user.

The file chooser dialog will be save mode.

The callback will be called when the dialog is dismissed.

New in version 4.10.

save_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – the result
Raises:: GLib.Error
Returns:: the file that was selected
Return type:: Gio.File or None

Finishes the [method`Gtk`.FileDialog.save] call.

New in version 4.10.

save_text_file(parent, cancellable, callback, *user_data)[source]¶

Parameters:

parent (Gtk.Window or None) – the parent GtkWindow
cancellable (Gio.Cancellable or None) – a GCancellable to cancel the operation
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation is complete
user_data (object or None) – data to pass to callback

Initiates a file save operation by presenting a file chooser dialog to the user.

In contrast to [method`Gtk`.FileDialog.save], this function lets the user select the text encoding and line endings for the text file, if possible.

The callback will be called when the dialog is dismissed.

New in version 4.18.

save_text_file_finish(result)[source]¶

Parameters:

result (Gio.AsyncResult) – a GAsyncResult

Raises:

GLib.Error

Returns:

the file that was selected. Otherwise, NULL is returned and error is set

encoding:: return location for the text encoding to use
line_ending:: return location for the line endings to use

Return type:

(Gio.File or None, encoding: str, line_ending: str)

Finishes the [method`Gtk`.FileDialog.save_text_file] call and returns the resulting file, text encoding and line endings.

If the user has explicitly selected a text encoding to use for the file, then encoding will be set to a codeset name that is suitable for passing to iconv_open(). Otherwise, it will be NULL.

The line_ending will be set to one of “\n”, “\r\n”, “\r” or “”, where the latter means to preserve existing line endings.

New in version 4.18.

select_folder(parent, cancellable, callback, *user_data)[source]¶

Parameters:

parent (Gtk.Window or None) – the parent window
cancellable (Gio.Cancellable or None) – a cancellable to cancel the operation
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation is complete
user_data (object or None) – data to pass to callback

Presents a file chooser dialog to the user.

The file chooser dialog will be set up to select a single folder.

If you pass initial_folder, the file chooser dialog will initially be opened in the parent directory of that folder, otherwise, it will be in the directory [property`Gtk`.FileDialog:initial-folder].

The callback will be called when the dialog is dismissed.

New in version 4.10.

select_folder_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – the result
Raises:: GLib.Error
Returns:: the folder that was selected
Return type:: Gio.File or None

Finishes the [method`Gtk`.FileDialog.select_folder] call.

New in version 4.10.

select_multiple_folders(parent, cancellable, callback, *user_data)[source]¶

Parameters:

parent (Gtk.Window or None) – the parent window
cancellable (Gio.Cancellable or None) – a cancellable to cancel the operation
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation is complete
user_data (object or None) – data to pass to callback

Presents a file chooser dialog to the user.

The file chooser dialog will be set up to allow selecting multiple folders.

The file chooser dialog will initially be opened in the directory [property`Gtk`.FileDialog:initial-folder].

The callback will be called when the dialog is dismissed.

New in version 4.10.

select_multiple_folders_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – the result
Raises:: GLib.Error
Returns:: the folders that were selected, as a list model of [iface`Gio`.File]
Return type:: Gio.ListModel or None

Finishes the [method`Gtk`.FileDialog.select_multiple_folders] call.

New in version 4.10.

set_accept_label(accept_label)[source]¶

Parameters:: accept_label (str or None) – the new accept label

Sets the label shown on the file chooser’s accept button.

Leaving the accept label unset or setting it as NULL will fall back to a default label, depending on what API is used to launch the file dialog.

New in version 4.10.

set_default_filter(filter)[source]¶

Parameters:: filter (Gtk.FileFilter or None) – the file filter

Sets the filter that will be selected by default in the file chooser dialog.

If set to NULL, the first item in [property`Gtk`.FileDialog:filters] will be used as the default filter. If that list is empty, the dialog will be unfiltered.

New in version 4.10.

set_filters(filters)[source]¶

Parameters:: filters (Gio.ListModel or None) – a list model of [class`Gtk`.FileFilter]

Sets the filters that will be offered to the user in the file chooser dialog.

New in version 4.10.

set_initial_file(file)[source]¶

Parameters:: file (Gio.File or None) – a file

Sets the file that will be initially selected in the file chooser dialog.

This function is a shortcut for calling both [method`Gtk`.FileDialog.set_initial_folder] and [method`Gtk`.FileDialog.set_initial_name] with the directory and name of file, respectively.

New in version 4.10.

set_initial_folder(folder)[source]¶

Parameters:: folder (Gio.File or None) – a file

Sets the folder that will be set as the initial folder in the file chooser dialog.

New in version 4.10.

set_initial_name(name)[source]¶

Parameters:: name (str or None) – a string

Sets the filename that will be initially selected.

For save dialogs, name will usually be pre-entered into the name field.

If a file with this name already exists in the directory set via [property`Gtk`.FileDialog:initial-folder], the dialog will preselect it.

New in version 4.10.

set_modal(modal)[source]¶

Parameters:: modal (bool) – the new value

Sets whether the file chooser dialog blocks interaction with the parent window while it is presented.

New in version 4.10.

set_title(title)[source]¶

Parameters:: title (str) – the new title

Sets the title that will be shown on the file chooser dialog.

New in version 4.10.

Property Details¶

Gtk.FileDialog.props.accept_label¶

Name:: accept-label
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Label for the file chooser’s accept button.

New in version 4.10.

Gtk.FileDialog.props.default_filter¶

Name:: default-filter
Type:: Gtk.FileFilter
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The default filter.

This filter is initially active in the file chooser dialog.

If the default filter is NULL, the first filter of [property`Gtk`.FileDialog:filters] is used as the default filter. If that property contains no filter, the dialog will be unfiltered.

If [property`Gtk`.FileDialog:filters] is not NULL, the default filter should be part of the list. If it is not, the dialog may choose to not make it available.

New in version 4.10.

Gtk.FileDialog.props.filters¶

Name:: filters
Type:: Gio.ListModel
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The list of filters.

See [property`Gtk`.FileDialog:default-filter] about how these two properties interact.

New in version 4.10.

Gtk.FileDialog.props.initial_file¶

Name:: initial-file
Type:: Gio.File
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The initial file.

This file is initially selected in the file chooser dialog

This is a utility property that sets both [property`Gtk`.FileDialog:initial-folder] and [property`Gtk`.FileDialog:initial-name].

New in version 4.10.

Gtk.FileDialog.props.initial_folder¶

Name:: initial-folder
Type:: Gio.File
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The initial folder.

This is the directory that is initially opened in the file chooser dialog.

New in version 4.10.

Gtk.FileDialog.props.initial_name¶

Name:: initial-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The initial name.

This is the name of the file that is initially selected in the file chooser dialog.

New in version 4.10.

Gtk.FileDialog.props.modal¶

Name:: modal
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the file chooser dialog is modal.

New in version 4.10.

Gtk.FileDialog.props.title¶

Name:: title
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

A title that may be shown on the file chooser dialog.

New in version 4.10.