File

File — access to files outside the sandbox

Functions

Types and Values

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