File: libportal Reference Manual

## File File — access to files outside the sandbox |

## Functions

void | xdp_portal_open_file ()
GVariant * | xdp_portal_open_file_finish ()
void | xdp_portal_save_file ()
GVariant * | xdp_portal_save_file_finish ()
void | xdp_portal_save_files ()
GVariant * | xdp_portal_save_files_finish ()

## Types and Values

enum | XdpOpenFileFlags
enum | XdpSaveFileFlags

## Description

These functions let applications ask the user for access to files outside the sandbox, by presenting a file chooser dialog.

The selected files will be made accessible to the application via the document portal, and the returned URI will point into the document portal fuse filesystem in /run/user/$UID/doc/.

The underlying portal is org.freedesktop.portal.FileChooser.

## Functions

### xdp_portal_open_file ()

    void
    xdp_portal_open_file (XdpPortal *portal,
                          XdpParent *parent,
                          const char *title,
                          GVariant *filters,
                          GVariant *current_filter,
                          GVariant *choices,
                          XdpOpenFileFlags flags,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer data);

Asks the user to open one or more files.

The format for the `filters` argument is a(sa(us)). Each item in the array specifies a single filter to offer to the user. The first string is a user-visible name for the filter. The a(us) specifies a list of filter strings, which can be either a glob pattern (indicated by 0) or a mimetype (indicated by 1).

Example: [('Images', [(0, '*.ico'), (1, 'image/png')]), ('Text', [(0, '*.txt')])]

The format for the `choices` argument is a(ssa(ss)s). For each element, the first string is an ID that will be returned with the response, te second string is a user-visible label. The a(ss) is the list of choices, each being a is an ID and a user-visible label. The final string is the initial selection, or "", to let the portal decide which choice will be initially selected. None of the strings, except for the initial selection, should be empty.

As a special case, passing an empty array for the list of choices indicates a boolean choice that is typically displayed as a check button, using "true" and "false" as the choices.

Example: [('encoding', 'Encoding', [('utf8', 'Unicode (UTF-8)'), ('latin15', 'Western')], 'latin15'), ('reencode', 'Reencode', [], 'false')]

When the request is done, `callback` will be called. You can then call `xdp_portal_open_file_finish()` to get the results.

#### Parameters

portal | a XdpPortal |
parent | parent window information. | [nullable]
title | title for the file chooser dialog |
filters | a GVariant describing file filters. | [nullable]
current_filter | a GVariant describing the current file filter. | [nullable]
choices | a GVariant describing extra widgets. | [nullable]
flags | options for this call |
cancellable | optional GCancellable. | [nullable]
callback | a callback to call when the request is done. | [scope async]
data | data to pass to `callback` . | [closure]

### xdp_portal_open_file_finish ()

    GVariant *
    xdp_portal_open_file_finish (XdpPortal *portal,
                                 GAsyncResult *result,
                                 GError **error);

Finishes the open-file request, and returns the result in the form of a GVariant dictionary containing the following fields:

- uris `as`: an array of strings containing the uris of selected files

- choices `a(ss)`: an array of pairs of strings, the first string being the ID of a combobox that was passed into this call, the second string being the selected option.

#### Parameters

portal | a XdpPortal |
result | a GAsyncResult |
error | return location for an error |

#### Returns

a GVariant dictionary with the results.

[transfer full]

### xdp_portal_save_file ()

    void
    xdp_portal_save_file (XdpPortal *portal,
                          XdpParent *parent,
                          const char *title,
                          const char *current_name,
                          const char *current_folder,
                          const char *current_file,
                          GVariant *filters,
                          GVariant *current_filter,
                          GVariant *choices,
                          XdpSaveFileFlags flags,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer data);

Asks the user for a location to save a file.

The format for the `filters` argument is the same as for `xdp_portal_open_file()`.

The format for the `choices` argument is the same as for `xdp_portal_open_file()`.

When the request is done, `callback` will be called. You can then call `xdp_portal_save_file_finish()` to get the results.

#### Parameters

portal | a XdpPortal |
parent | parent window information. | [nullable]
title | title for the file chooser dialog |
current_name | suggested filename. | [nullable]
current_folder | suggested folder to save the file in. | [nullable]
current_file | the current file (when saving an existing file). | [nullable]
filters | a GVariant describing file filters. | [nullable]
current_filter | a GVariant describing the current file filter. | [nullable]
choices | a GVariant describing extra widgets. | [nullable]
flags | options for this call |
cancellable | optional GCancellable. | [nullable]
callback | a callback to call when the request is done. | [scope async]
data | data to pass to `callback` . | [closure]

### xdp_portal_save_file_finish ()

    GVariant *
    xdp_portal_save_file_finish (XdpPortal *portal,
                                 GAsyncResult *result,
                                 GError **error);

Finishes the save-file request, and returns the result in the form of a GVariant dictionary containing the following fields:

- uris `(as)`: an array of strings containing the uri of the selected file

- choices `a(ss)`: an array of pairs of strings, the first string being the ID of a combobox that was passed into this call, the second string being the selected option.

#### Parameters

portal | a XdpPortal |
result | a GAsyncResult |
error | return location for an error |

#### Returns

a GVariant dictionary with the results.

[transfer full]

### xdp_portal_save_files ()

    void
    xdp_portal_save_files (XdpPortal *portal,
                           XdpParent *parent,
                           const char *title,
                           const char *current_name,
                           const char *current_folder,
                           GVariant *files,
                           GVariant *choices,
                           XdpSaveFileFlags flags,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer data);

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.

The format for the `choices` argument is the same as for `xdp_portal_open_file()`.

When the request is done, `callback` will be called. You can then call `xdp_portal_save_file_finish()` to get the results.

#### Parameters

portal | a XdpPortal |
parent | parent window information. | [nullable]
title | title for the file chooser dialog |
current_name | suggested filename. | [nullable]
current_folder | suggested folder to save the file in. | [nullable]
files | An array of file names to be saved |
choices | a GVariant describing extra widgets. | [nullable]
flags | options for this call |
cancellable | optional GCancellable. | [nullable]
callback | a callback to call when the request is done. | [scope async]
data | data to pass to `callback` . | [closure]

### xdp_portal_save_files_finish ()

    GVariant *
    xdp_portal_save_files_finish (XdpPortal *portal,
                                  GAsyncResult *result,
                                  GError **error);

Finishes the save-files request, and returns the result in the form of a GVariant dictionary containing the following fields:

- uris `(as)`: an array of strings containing the uri corresponding to each file passed to the save-files request, 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.

- choices `a(ss)`: an array of pairs of strings, the first string being the ID of a combobox that was passed into this call, the second string being the selected option.

#### Parameters

portal | a XdpPortal |
result | a GAsyncResult |
error | return location for an error |

#### Returns

a GVariant dictionary with the results.

[transfer full]

## Types and Values

### enum XdpOpenFileFlags

Options for opening files.

#### Members

XDP_OPEN_FILE_FLAG_NONE | No options |
XDP_OPEN_FILE_FLAG_MULTIPLE | Allow selecting multiple files |

### enum XdpSaveFileFlags

#### Members

XDP_SAVE_FILE_FLAG_NONE |  |