:right-sidebar: True

FileDialog
===================================================================

.. currentmodule:: gi.repository.Gtk


.. versionadded:: 4.10




.. class:: FileDialog(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.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 :obj:`~gi.repository.Gtk.FileDialog.open`,
:obj:`~gi.repository.Gtk.FileDialog.save`, etc. These APIs follow the
GIO async pattern, and the result can be obtained by calling
the corresponding finish function, for example
:obj:`~gi.repository.Gtk.FileDialog.open_finish`.



Constructors
------------

.. rst-class:: interim-class

.. class:: FileDialog
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.FileDialog

      Creates a new ``GtkFileDialog`` object.



      .. versionadded:: 4.10












Methods
-------

.. rst-class:: interim-class

.. class:: FileDialog
   :no-index:


   .. method:: get_accept_label() -> str | None

      


      .. versionadded:: 4.10








   .. method:: get_default_filter() -> ~gi.repository.Gtk.FileFilter | None

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



      .. versionadded:: 4.10








   .. method:: get_filters() -> ~gi.repository.Gio.ListModel | None

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



      .. versionadded:: 4.10








   .. method:: get_initial_file() -> ~gi.repository.Gio.File | None

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



      .. versionadded:: 4.10








   .. method:: get_initial_folder() -> ~gi.repository.Gio.File | None

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



      .. versionadded:: 4.10








   .. method:: get_initial_name() -> str | None

      Gets the name for the file that should be initially set.



      .. versionadded:: 4.10








   .. method:: get_modal() -> bool

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



      .. versionadded:: 4.10








   .. method:: get_title() -> str

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



      .. versionadded:: 4.10








   .. method:: open(parent: ~gi.repository.Gtk.Window | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.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 :obj:`~gi.repository.Gtk.FileDialog.open_finish`
      to obtain the result.



      .. versionadded:: 4.10





      :param parent: the parent ``GtkWindow``


      :param cancellable: a ``GCancellable`` to cancel the operation


      :param callback: a callback to call when the operation is complete


      :param user_data: data to pass to ``callback``





   .. method:: open_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.File | None

      Finishes the :obj:`~gi.repository.Gtk.FileDialog.open` call and
      returns the resulting file.



      .. versionadded:: 4.10





      :param result: a ``GAsyncResult``





   .. method:: open_multiple(parent: ~gi.repository.Gtk.Window | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.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
      :obj:`~gi.repository.Gtk.FileDialog.props.initial_folder`.

      The ``callback`` will be called when the dialog is dismissed.
      It should call :obj:`~gi.repository.Gtk.FileDialog.open_multiple_finish`
      to obtain the result.



      .. versionadded:: 4.10





      :param parent: the parent ``GtkWindow``


      :param cancellable: a ``GCancellable`` to cancel the operation


      :param callback: a callback to call when the operation is complete


      :param user_data: data to pass to ``callback``





   .. method:: open_multiple_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.ListModel | None

      Finishes the :obj:`~gi.repository.Gtk.FileDialog.open` call and
      returns the resulting files in a ``GListModel``.



      .. versionadded:: 4.10





      :param result: a ``GAsyncResult``





   .. method:: save(parent: ~gi.repository.Gtk.Window | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.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 :obj:`~gi.repository.Gtk.FileDialog.save_finish`
      to obtain the result.



      .. versionadded:: 4.10





      :param parent: the parent ``GtkWindow``


      :param cancellable: a ``GCancellable`` to cancel the operation


      :param callback: a callback to call when the operation is complete


      :param user_data: data to pass to ``callback``





   .. method:: save_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.File | None

      Finishes the :obj:`~gi.repository.Gtk.FileDialog.save` call and
      returns the resulting file.



      .. versionadded:: 4.10





      :param result: a ``GAsyncResult``





   .. method:: select_folder(parent: ~gi.repository.Gtk.Window | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.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 :obj:`~gi.repository.Gtk.FileDialog.props.initial_folder`.

      The ``callback`` will be called when the dialog is dismissed.
      It should call :obj:`~gi.repository.Gtk.FileDialog.select_folder_finish`
      to obtain the result.



      .. versionadded:: 4.10





      :param parent: the parent ``GtkWindow``


      :param cancellable: a ``GCancellable`` to cancel the operation


      :param callback: a callback to call when the operation is complete


      :param user_data: data to pass to ``callback``





   .. method:: select_folder_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.File | None

      Finishes the :obj:`~gi.repository.Gtk.FileDialog.select_folder` call and
      returns the resulting file.



      .. versionadded:: 4.10





      :param result: a ``GAsyncResult``





   .. method:: select_multiple_folders(parent: ~gi.repository.Gtk.Window | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.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
      :obj:`~gi.repository.Gtk.FileDialog.props.initial_folder`.

      The ``callback`` will be called when the dialog is dismissed.
      It should call :obj:`~gi.repository.Gtk.FileDialog.select_multiple_folders_finish`
      to obtain the result.



      .. versionadded:: 4.10





      :param parent: the parent ``GtkWindow``


      :param cancellable: a ``GCancellable`` to cancel the operation


      :param callback: a callback to call when the operation is complete


      :param user_data: data to pass to ``callback``





   .. method:: select_multiple_folders_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.ListModel | None

      Finishes the :obj:`~gi.repository.Gtk.FileDialog.select_multiple_folders`
      call and returns the resulting files in a ``GListModel``.



      .. versionadded:: 4.10





      :param result: a ``GAsyncResult``





   .. method:: 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.



      .. versionadded:: 4.10





      :param accept_label: the new accept label





   .. method:: set_default_filter(filter: ~gi.repository.Gtk.FileFilter | None = None) -> None

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

      If set to :const:`None`, the first item in :obj:`~gi.repository.Gtk.FileDialog.props.filters`
      will be used as the default filter. If that list is empty, the dialog
      will be unfiltered.



      .. versionadded:: 4.10





      :param filter: a ``GtkFileFilter``





   .. method:: set_filters(filters: ~gi.repository.Gio.ListModel | None = None) -> None

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



      .. versionadded:: 4.10





      :param filters: a ``GListModel`` of ``GtkFileFilters``





   .. method:: set_initial_file(file: ~gi.repository.Gio.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
      :func:`~gi.repository.Gtk.FileDialog.set_initial_folder` and
      :func:`~gi.repository.Gtk.FileDialog.set_initial_name` with the directory and
      name of ``file`` respectively.



      .. versionadded:: 4.10





      :param file: a ``GFile``





   .. method:: set_initial_folder(folder: ~gi.repository.Gio.File | None = None) -> None

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



      .. versionadded:: 4.10





      :param folder: a ``GFile``





   .. method:: 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
      :obj:`~gi.repository.Gtk.FileDialog.props.initial_folder`, the dialog should preselect it.



      .. versionadded:: 4.10





      :param name: a UTF8 string





   .. method:: set_modal(modal: bool) -> None

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



      .. versionadded:: 4.10





      :param modal: the new value





   .. method:: set_title(title: str) -> None

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



      .. versionadded:: 4.10





      :param title: the new title









Properties
----------

.. rst-class:: interim-class

.. class:: FileDialog
   :no-index:
   

   .. attribute:: props.accept_label
      :type: str

      Label for the file chooser's accept button.



      .. versionadded:: 4.10





   .. attribute:: props.default_filter
      :type: ~gi.repository.Gtk.FileFilter

      The default filter, that is, the filter that is initially
      active in the file chooser dialog.

      If the default filter is :const:`None`, the first filter of :obj:`~gi.repository.Gtk.FileDialog.props.filters`
      is used as the default filter. If that property contains no filter, the dialog will
      be unfiltered.

      If :obj:`~gi.repository.Gtk.FileDialog.props.filters` is not :const:`None`, the default filter should be part
      of the list. If it is not, the dialog may choose to not make it available.



      .. versionadded:: 4.10





   .. attribute:: props.filters
      :type: ~gi.repository.Gio.ListModel

      The list of filters.

      See :obj:`~gi.repository.Gtk.FileDialog.props.default_filter` about how those two properties interact.



      .. versionadded:: 4.10





   .. attribute:: props.initial_file
      :type: ~gi.repository.Gio.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 :obj:`~gi.repository.Gtk.FileDialog.props.initial_folder` and
      :obj:`~gi.repository.Gtk.FileDialog.props.initial_name`.



      .. versionadded:: 4.10





   .. attribute:: props.initial_folder
      :type: ~gi.repository.Gio.File

      The initial folder, that is, the directory that is initially
      opened in the file chooser dialog



      .. versionadded:: 4.10





   .. attribute:: props.initial_name
      :type: str

      The initial name, that is, the filename that is initially
      selected in the file chooser dialog.



      .. versionadded:: 4.10





   .. attribute:: props.modal
      :type: bool

      Whether the file chooser dialog is modal.



      .. versionadded:: 4.10





   .. attribute:: props.title
      :type: str

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



      .. versionadded:: 4.10