FileDialog#

Added in version 4.10.

class FileDialog(**properties: Any)#

Superclasses: Object

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 open, save, etc.

Constructors#

class FileDialog
classmethod new() → FileDialog#

Creates a new GtkFileDialog object.

Added in version 4.10.

Methods#

class FileDialog
get_accept_label() → str | None#

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

Added in version 4.10.

get_default_filter() → FileFilter | None#

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

Added in version 4.10.

get_filters() → ListModel | None#

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

Added in version 4.10.

get_initial_file() → File | None#

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

Added in version 4.10.

get_initial_folder() → File | None#

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

Added in version 4.10.

get_initial_name() → str | None#

Gets the filename that will be initially selected.

Added in version 4.10.

get_modal() → bool#

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

Added in version 4.10.

get_title() → str#

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

Added in version 4.10.

async open(self, parent: Window | None = None) → File#

This is the awaitable version of open().

Added in version 4.10.

Parameters:

parent – the parent window

open(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

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 closed.

Added in version 4.10.

Parameters:

  • parent – the parent window

  • cancellable – a cancellable to cancel the operation

  • callback – a callback to call when the operation is complete

  • user_data – data to pass to callback

open_finish(result: AsyncResult) → File#

Finishes the open call.

Note that this function returns a DISMISSED error if the user cancels the dialog.

Added in version 4.10.

Parameters:

result – the result

async open_multiple(self, parent: Window | None = None) → ListModel#

This is the awaitable version of open_multiple().

Added in version 4.10.

Parameters:

parent – the parent window

open_multiple(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

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 initial_folder.

The callback will be called when the dialog is closed.

Added in version 4.10.

Parameters:

  • parent – the parent window

  • cancellable – a cancellable to cancel the operation

  • callback – a callback to call when the operation is complete

  • user_data – data to pass to callback

open_multiple_finish(result: AsyncResult) → ListModel#

Finishes the open call.

Note that this function returns a DISMISSED error if the user cancels the dialog.

Added in version 4.10.

Parameters:

result – the result

async open_multiple_text_files(self, parent: Window | None = None) → tuple[ListModel, str]#

This is the awaitable version of open_multiple_text_files().

Added in version 4.18.

Parameters:

parent – the parent window

open_multiple_text_files(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

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 initial_folder.

In contrast to open, this function lets the user select the text encoding for the files, if possible.

The callback will be called when the dialog is closed.

Added in version 4.18.

Parameters:

  • parent – the parent window

  • cancellable – a cancellable to cancel the operation

  • callback – a callback to call when the operation is complete

  • user_data – data to pass to callback

open_multiple_text_files_finish(result: AsyncResult) → tuple[ListModel, str]#

Finishes the open call.

Note that this function returns a DISMISSED error if the user cancels the dialog.

Added in version 4.18.

Parameters:

result – the result

async open_text_file(self, parent: Window | None = None) → tuple[File, str]#

This is the awaitable version of open_text_file().

Added in version 4.18.

Parameters:

parent – the parent GtkWindow

open_text_file(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

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

In contrast to open, this function lets the user select the text encoding for the file, if possible.

The callback will be called when the dialog is closed.

Added in version 4.18.

Parameters:

  • parent – the parent GtkWindow

  • cancellable – a GCancellable to cancel the operation

  • callback – a callback to call when the operation is complete

  • user_data – data to pass to callback

open_text_file_finish(result: AsyncResult) → tuple[File, str]#

Finishes the 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.

Note that this function returns a DISMISSED error if the user cancels the dialog.

Added in version 4.18.

Parameters:

result – a GAsyncResult

async save(self, parent: Window | None = None) → File#

This is the awaitable version of save().

Added in version 4.10.

Parameters:

parent – the parent window

save(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

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 closed.

Added in version 4.10.

Parameters:

  • parent – the parent window

  • cancellable – a cancellable to cancel the operation

  • callback – a callback to call when the operation is complete

  • user_data – data to pass to callback

save_finish(result: AsyncResult) → File#

Finishes the save call.

Note that this function returns a DISMISSED error if the user cancels the dialog.

Added in version 4.10.

Parameters:

result – the result

async save_text_file(self, parent: Window | None = None) → tuple[File, str, str]#

This is the awaitable version of save_text_file().

Added in version 4.18.

Parameters:

parent – the parent GtkWindow

save_text_file(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

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

In contrast to 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 closed.

Added in version 4.18.

Parameters:

  • parent – the parent GtkWindow

  • cancellable – a GCancellable to cancel the operation

  • callback – a callback to call when the operation is complete

  • user_data – data to pass to callback

save_text_file_finish(result: AsyncResult) → tuple[File, str, str]#

Finishes the 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”, “rn”, “r” or “”, where the latter means to preserve existing line endings.

Note that this function returns a DISMISSED error if the user cancels the dialog.

Added in version 4.18.

Parameters:

result – a GAsyncResult

async select_folder(self, parent: Window | None = None) → File#

This is the awaitable version of select_folder().

Added in version 4.10.

Parameters:

parent – the parent window

select_folder(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

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 initial_folder.

The callback will be called when the dialog is closed.

Added in version 4.10.

Parameters:

  • parent – the parent window

  • cancellable – a cancellable to cancel the operation

  • callback – a callback to call when the operation is complete

  • user_data – data to pass to callback

select_folder_finish(result: AsyncResult) → File#

Finishes the select_folder call.

Note that this function returns a DISMISSED error if the user cancels the dialog.

Added in version 4.10.

Parameters:

result – the result

async select_multiple_folders(self, parent: Window | None = None) → ListModel#

This is the awaitable version of select_multiple_folders().

Added in version 4.10.

Parameters:

parent – the parent window

select_multiple_folders(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

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 initial_folder.

The callback will be called when the dialog is closed.

Added in version 4.10.

Parameters:

  • parent – the parent window

  • cancellable – a cancellable to cancel the operation

  • callback – a callback to call when the operation is complete

  • user_data – data to pass to callback

select_multiple_folders_finish(result: AsyncResult) → ListModel#

Finishes the select_multiple_folders call.

Note that this function returns a DISMISSED error if the user cancels the dialog.

Added in version 4.10.

Parameters:

result – the result

set_accept_label(accept_label: str | None = None) → None#

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.

Added in version 4.10.

Parameters:

accept_label – the new accept label

set_default_filter(filter: FileFilter | None = None) → None#

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

If set to NULL, the first item in filters will be used as the default filter. If that list is empty, the dialog will be unfiltered.

Added in version 4.10.

Parameters:

filter – the file filter

set_filters(filters: ListModel | None = None) → None#

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

Added in version 4.10.

Parameters:

filters – a list model of FileFilter

set_initial_file(file: File | None = None) → None#

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

This function is a shortcut for calling both set_initial_folder and set_initial_name with the directory and name of file, respectively.

Added in version 4.10.

Parameters:

file – a file

set_initial_folder(folder: File | None = None) → None#

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

Added in version 4.10.

Parameters:

folder – a file

set_initial_name(name: str | None = None) → None#

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 initial_folder, the dialog will preselect it.

Added in version 4.10.

Parameters:

name – a string

set_modal(modal: bool) → None#

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

Added in version 4.10.

Parameters:

modal – the new value

set_title(title: str) → None#

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

Added in version 4.10.

Parameters:

title – the new title

Properties#

class FileDialog
props.accept_label: str#

Label for the file chooser’s accept button.

Added in version 4.10.

props.default_filter: FileFilter#

The default filter.

This filter is initially active in the file chooser dialog.

If the default filter is NULL, the first filter of filters is used as the default filter. If that property contains no filter, the dialog will be unfiltered.

If 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.

Added in version 4.10.

props.filters: ListModel#

The list of filters.

See default_filter about how these two properties interact.

Added in version 4.10.

props.initial_file: File#

The initial file.

This file is initially selected in the file chooser dialog

This is a utility property that sets both initial_folder and initial_name.

Added in version 4.10.

props.initial_folder: File#

The initial folder.

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

Added in version 4.10.

props.initial_name: str#

The initial name.

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

Added in version 4.10.

props.modal: bool#

Whether the file chooser dialog is modal.

Added in version 4.10.

props.title: str#

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

Added in version 4.10.