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