FileDialog

Added in version 4.10.

class FileDialog(**properties: Any)

Superclasses: Object

A GtkFileDialog object collects the arguments that are needed to present a file chooser 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. These APIs follow the GIO async pattern, and the result can be obtained by calling the corresponding finish function, for example open_finish.

Constructors

class FileDialog

classmethod new() → FileDialog: Creates a new GtkFileDialog object.

Added in version 4.10.

Methods

class FileDialog

get_accept_label() → str | None: 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 name for the file that should be initially set.

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.

open(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

This function initiates a file selection operation by presenting a file chooser dialog to the user.

The callback will be called when the dialog is dismissed. It should call open_finish to obtain the result.

Added in version 4.10.

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_finish(result: AsyncResult) → File | None

Finishes the open call and returns the resulting file.

Added in version 4.10.

Parameters:: result – a GAsyncResult

open_multiple(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

This function initiates a multi-file selection operation by presenting a file chooser dialog to the user.

The file chooser will initially be opened in the directory initial_folder.

The callback will be called when the dialog is dismissed. It should call open_multiple_finish to obtain the result.

Added in version 4.10.

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_multiple_finish(result: AsyncResult) → ListModel | None

Finishes the open call and returns the resulting files in a GListModel.

Added in version 4.10.

Parameters:: result – a GAsyncResult

save(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

This function initiates a file save operation by presenting a file chooser dialog to the user.

The callback will be called when the dialog is dismissed. It should call save_finish to obtain the result.

Added in version 4.10.

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_finish(result: AsyncResult) → File | None

Finishes the save call and returns the resulting file.

Added in version 4.10.

Parameters:: result – a GAsyncResult

select_folder(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

This function initiates a directory selection operation by presenting a file chooser dialog to the user.

If you pass initial_folder, the file chooser 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 dismissed. It should call select_folder_finish to obtain the result.

Added in version 4.10.

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

select_folder_finish(result: AsyncResult) → File | None

Finishes the select_folder call and returns the resulting file.

Added in version 4.10.

Parameters:: result – a GAsyncResult

select_multiple_folders(parent: Window | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

This function initiates a multi-directory selection operation by presenting a file chooser dialog to the user.

The file chooser will initially be opened in the directory initial_folder.

The callback will be called when the dialog is dismissed. It should call select_multiple_folders_finish to obtain the result.

Added in version 4.10.

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

select_multiple_folders_finish(result: AsyncResult) → ListModel | None

Finishes the select_multiple_folders call and returns the resulting files in a GListModel.

Added in version 4.10.

Parameters:: result – a GAsyncResult

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 None, 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 – a GtkFileFilter

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 GListModel of GtkFileFilters

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 GFile

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 GFile

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

Sets the name for the file that should be initially set. For saving dialogs, this 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 should preselect it.

Added in version 4.10.

Parameters:: name – a UTF8 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, that is, the filter that is initially active in the file chooser dialog.

If the default filter is None, 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 None, 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 those two properties interact.

Added in version 4.10.

props.initial_file: File

The initial file, that is, the file that 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, that is, the directory that is initially opened in the file chooser dialog

Added in version 4.10.

props.initial_name: str: The initial name, that is, the filename 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.