File

File — access to files outside the sandbox

Functions

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,
                      gboolean modal,
                      gboolean multiple,
                      GVariant *filters,
                      GVariant *current_filter,
                      GVariant *choices,
                      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

 

modal

whether the dialog should be modal

 

multiple

whether multiple files can be selected or not

 

filters

a GVariant describing file filters.

[nullable]

current_filter

a GVariant describing the current file filter.

[nullable]

choices

a GVariant describing extra widgets.

[nullable]

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,
                      gboolean modal,
                      const char *current_name,
                      const char *current_folder,
                      const char *current_file,
                      GVariant *filters,
                      GVariant *current_filter,
                      GVariant *choices,
                      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

 

modal

whether the dialog should be modal

 

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]

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]