Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# File Chooser

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

## Methods

### 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 org.freedesktop.portal.FileChooser.OpenFile for details.

- `current_filter` (`(sa(us))`)

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

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

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

- `current_folder` (`ay`)

  A suggested folder to open the files from. See 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 org.freedesktop.portal.FileChooser.OpenFile for details.

- `current_filter` (`(sa(us))`)

  The filter that was selected. See 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 Request object representing this call

app_id

  App id of the application

parent_window

  Identifier for the application window, see 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

    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 org.freedesktop.portal.FileChooser.OpenFile for details.

- `current_filter` (`(sa(us))`)

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

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

  A list of serialized combo boxes. See 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 org.freedesktop.portal.FileChooser.OpenFile for details.

- `current_filter` (`(sa(us))`)

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

handle

  Object path for the Request object representing this call

app_id

  App id of the application

parent_window

  Identifier for the application window, see 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

    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 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 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 org.freedesktop.portal.FileChooser.OpenFile for details.

handle

  Object path for the Request object representing this call

app_id

parent_window

  Identifier for the application window, see 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