Skip to content

Gtk.FileDialog

class — extends GObject.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 FileDialog.open, FileDialog.save, etc.

Constructors

new

@classmethod
def new(cls) -> FileDialog

Creates a new GtkFileDialog object.

Methods

get_accept_label

def get_accept_label(self) -> str | None

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

get_default_filter

def get_default_filter(self) -> FileFilter | None

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

get_filters

def get_filters(self) -> Gio.ListModel | None

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

get_initial_file

def get_initial_file(self) -> Gio.File | None

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

get_initial_folder

def get_initial_folder(self) -> Gio.File | None

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

get_initial_name

def get_initial_name(self) -> str | None

Gets the filename that will be initially selected.

get_modal

def get_modal(self) -> bool

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

get_title

def get_title(self) -> str

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

open

def open(self, parent: Window | None = ..., cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | 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.

Parameters:

  • parent — the parent window
  • cancellable — a cancellable to cancel the operation
  • callback — a callback to call when the operation is complete

open_finish

def open_finish(self, result: Gio.AsyncResult) -> Gio.File

Finishes the FileDialog.open call.

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

Parameters:

  • result — the result

open_multiple

def open_multiple(self, parent: Window | None = ..., cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | 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 FileDialog.initial-folder.

The callback will be called when the dialog is closed.

Parameters:

  • parent — the parent window
  • cancellable — a cancellable to cancel the operation
  • callback — a callback to call when the operation is complete

open_multiple_finish

def open_multiple_finish(self, result: Gio.AsyncResult) -> Gio.ListModel

Finishes the FileDialog.open call.

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

Parameters:

  • result — the result

open_multiple_text_files

def open_multiple_text_files(self, parent: Window | None = ..., cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | 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 FileDialog.initial-folder.

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

Parameters:

  • parent — the parent window
  • cancellable — a cancellable to cancel the operation
  • callback — a callback to call when the operation is complete

open_multiple_text_files_finish

def open_multiple_text_files_finish(self, result: Gio.AsyncResult) -> tuple[Gio.ListModel, str]

Finishes the FileDialog.open call.

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

Parameters:

  • result — the result

open_text_file

def open_text_file(self, parent: Window | None = ..., cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | None = ...) -> None

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

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

Parameters:

  • parent — the parent GtkWindow
  • cancellable — a GCancellable to cancel the operation
  • callback — a callback to call when the operation is complete

open_text_file_finish

def open_text_file_finish(self, result: Gio.AsyncResult) -> tuple[Gio.File, str]

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

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

Parameters:

  • result — a GAsyncResult

save

def save(self, parent: Window | None = ..., cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | 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.

Parameters:

  • parent — the parent window
  • cancellable — a cancellable to cancel the operation
  • callback — a callback to call when the operation is complete

save_finish

def save_finish(self, result: Gio.AsyncResult) -> Gio.File

Finishes the FileDialog.save call.

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

Parameters:

  • result — the result

save_text_file

def save_text_file(self, parent: Window | None = ..., cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | None = ...) -> None

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

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

Parameters:

  • parent — the parent GtkWindow
  • cancellable — a GCancellable to cancel the operation
  • callback — a callback to call when the operation is complete

save_text_file_finish

def save_text_file_finish(self, result: Gio.AsyncResult) -> tuple[Gio.File, str, str]

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

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

Parameters:

  • result — a GAsyncResult

select_folder

def select_folder(self, parent: Window | None = ..., cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | 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 FileDialog.initial-folder.

The callback will be called when the dialog is closed.

Parameters:

  • parent — the parent window
  • cancellable — a cancellable to cancel the operation
  • callback — a callback to call when the operation is complete

select_folder_finish

def select_folder_finish(self, result: Gio.AsyncResult) -> Gio.File

Finishes the FileDialog.select_folder call.

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

Parameters:

  • result — the result

select_multiple_folders

def select_multiple_folders(self, parent: Window | None = ..., cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | 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 FileDialog.initial-folder.

The callback will be called when the dialog is closed.

Parameters:

  • parent — the parent window
  • cancellable — a cancellable to cancel the operation
  • callback — a callback to call when the operation is complete

select_multiple_folders_finish

def select_multiple_folders_finish(self, result: Gio.AsyncResult) -> Gio.ListModel

Finishes the FileDialog.select_multiple_folders call.

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

Parameters:

  • result — the result

set_accept_label

def set_accept_label(self, accept_label: str | 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.

Parameters:

  • accept_label — the new accept label

set_default_filter

def set_default_filter(self, filter: FileFilter | None = ...) -> None

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

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

Parameters:

  • filter — the file filter

set_filters

def set_filters(self, filters: Gio.ListModel | None = ...) -> None

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

Parameters:

set_initial_file

def set_initial_file(self, file: Gio.File | None = ...) -> None

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

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

Parameters:

  • file — a file

set_initial_folder

def set_initial_folder(self, folder: Gio.File | None = ...) -> None

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

Parameters:

  • folder — a file

set_initial_name

def set_initial_name(self, name: str | 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 FileDialog.initial-folder, the dialog will preselect it.

Parameters:

  • name — a string

set_modal

def set_modal(self, modal: bool) -> None

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

Parameters:

  • modal — the new value

set_title

def set_title(self, title: str) -> None

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

Parameters:

  • title — the new title

Properties

accept_label

accept_label: str  # read/write

Label for the file chooser's accept button.

default_filter

default_filter: FileFilter  # read/write

The default filter.

This filter is initially active in the file chooser dialog.

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

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

filters

filters: Gio.ListModel  # read/write

The list of filters.

See FileDialog.default-filter about how these two properties interact.

initial_file

initial_file: Gio.File  # read/write

The initial file.

This file is initially selected in the file chooser dialog

This is a utility property that sets both FileDialog.initial-folder and FileDialog.initial-name.

initial_folder

initial_folder: Gio.File  # read/write

The initial folder.

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

initial_name

initial_name: str  # read/write

The initial name.

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

modal

modal: bool  # read/write

Whether the file chooser dialog is modal.

title

title: str  # read/write

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