.. _org.freedesktop.impl.portal.FileChooser:

=======================================
 File Chooser
=======================================

-----------
Description
-----------

.. _org.freedesktop.impl.portal.FileChooser Description:

File chooser portal backend interface

The FileChooser portal allows sandboxed applications to ask
the user for access to files outside the sandbox. The portal
backend will present the user with a file chooser dialog.

Backends must normalize URIs of locations selected by the
user into "file://" URIs. URIs that cannot be normalized
should be discarded.



.. _org.freedesktop.impl.portal.FileChooser Methods:

-------
Methods
-------

.. _org.freedesktop.impl.portal.FileChooser.OpenFile:

org.freedesktop.impl.portal.FileChooser.OpenFile
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    OpenFile (
      IN handle o,
      IN app_id s,
      IN parent_window s,
      IN title s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



Presents a file chooser dialog to the user to open one or more files.

Supported keys in the ``options`` vardict include:

* ``accept_label`` (``s``)

  The label for the accept button. Mnemonic underlines are allowed.

* ``modal`` (``b``)

  Whether to make the dialog modal. Default is yes.

* ``multiple`` (``b``)

  Whether to allow selection of multiple files. Default is no.

* ``directory`` (``b``)

  Whether to select for folders instead of files. Default is to select files.

* ``filters`` (``a(sa(us))``)

  A list of serialized file filters.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

* ``current_filter`` (``(sa(us))``)

  Request that this filter be set by default at dialog creation.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

* ``choices`` (``a(ssa(ss)s)``)

  A list of serialized combo boxes.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

* ``current_folder`` (``ay``)

  A suggested folder to open the files from.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

The following results get returned via the ``results`` vardict:

* ``uris`` (``as``)

  An array of strings containing the uris of the selected files. All
  URIs must have the ``file://`` scheme.

* ``choices`` (``a(ss)``)

  An array of pairs of strings, corresponding to the passed-in choices.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

* ``current_filter`` (``(sa(us))``)

  The filter that was selected.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

* ``writable`` (``b``)

  Whether the file is opened with write access. Default is ``false``.



handle
  Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call

app_id
  App id of the application

parent_window
  Identifier for the application window, see :doc:`window-identifiers`

title
  Title for the file chooser dialog

options
  Vardict with optional further information

response
  Numeric response

results
  Vardict with the results of the call



.. _org.freedesktop.impl.portal.FileChooser.SaveFile:

org.freedesktop.impl.portal.FileChooser.SaveFile
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    SaveFile (
      IN handle o,
      IN app_id s,
      IN parent_window s,
      IN title s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



Presents a file chooser dialog to the user to save a file.

Supported keys in the ``options`` vardict include:

* ``accept_label`` (``s``)

  The label for the accept button. Mnemonic underlines are allowed.

* ``modal`` (``b``)

  Whether to make the dialog modal. Default is yes.

* ``multiple`` (``b``)

  Whether to allow selection of multiple files. Default is no.

* ``filters`` (``a(sa(us))``)

  A list of serialized file filters.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

* ``current_filter`` (``(sa(us))``)

  Request that this filter be set by default at dialog creation.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

* ``choices`` (``a(ssa(ss)s)``)

  A list of serialized combo boxes.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

* ``current_name`` (``s``)

  A suggested filename.

* ``current_folder`` (``ay``)

  A suggested folder to save the file in.

* ``current_file`` (``ay``)

  The current file (when saving an existing file).

The following results get returned via the ``results`` vardict:

* ``uris`` (``as``)

  An array of strings containing the uri of the selected file. All
  URIs must have the "file://" scheme.

* ``choices`` (``a(ss)``)

  An array of pairs of strings, corresponding to the passed-in choices.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

* ``current_filter`` (``(sa(us))``)

  The filter that was selected.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.



handle
  Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call

app_id
  App id of the application

parent_window
  Identifier for the application window, see :doc:`window-identifiers`

title
  Title for the file chooser dialog

options
  Vardict with optional further information

response
  Numeric response

results
  Vardict with the results of the call



.. _org.freedesktop.impl.portal.FileChooser.SaveFiles:

org.freedesktop.impl.portal.FileChooser.SaveFiles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    SaveFiles (
      IN handle o,
      IN app_id s,
      IN parent_window s,
      IN title s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



Asks for a folder as a location to save one or more files. The
names of the files will be used as-is and appended to the
selected folder's path in the list of returned files. If the
selected folder already contains a file with one of the given
names, the portal may prompt or take some other action to
construct a unique file name and return that instead.

Supported keys in the ``options`` vardict include:

* ``accept_label`` (``s``)

  Label for the accept button. Mnemonic underlines are allowed.

* ``modal`` (``b``)

  Whether the dialog should be modal. Default is yes.

* ``choices`` (``a(ssa(ss)s)``)

  List of serialized combo boxes.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.

* ``current_folder`` (``ay``)

  Suggested folder to save the files in. The byte array is
  expected to be null-terminated.

* ``files`` (``aay``)

  An array of file names to be saved. The array and byte
  arrays are expected to be null-terminated.

The following results get returned via the
:ref:`org.freedesktop.portal.Request::Response` signal:

* ``uris`` (``as``)

  An array of strings containing the uri corresponding to
  each file given by ``options``, in the same order. Note that
  the file names may have changed, for example if a file
  with the same name in the selected folder already exists.

  All URIs must have the "file://" scheme.

* ``choices`` (``a(ss)``)

  An array of pairs of strings, corresponding to the passed-in choices.
  See :ref:`org.freedesktop.portal.FileChooser.OpenFile` for details.



handle
  Object path for the :ref:`org.freedesktop.portal.Request` object representing this call

app_id
  

parent_window
  Identifier for the application window, see :doc:`window-identifiers`

title
  Title for the file chooser dialog

options
  Vardict with optional further information

response
  Numeric response

results
  Vardict with the results of the call


