Commit 0c3b9dc3 authored by David Boddie's avatar David Boddie 💬
Browse files

Add more information about settings, data and files

parent 708a37f3
Pipeline #5433 passed with stage
in 9 minutes and 30 seconds
......@@ -17,7 +17,7 @@ GNOME applications access their settings using the GSettings_ class. This stores
User Data
---------
Some applications prefer to store data that the user has created or imported in a special directory set aside for the application.
Some applications prefer to store data that the user has created or imported in a special data directory set aside for the application.
Simple data can be accessed using keyfiles that record pieces of information as key-value pairs. Access to a suitable data directory is obtained using the `GLib.get_user_data_dir() <g_get_user_data_dir_>`_ function. The GKeyFile_ class is used to read and write keyfiles stored in a subdirectory of the data directory.
......@@ -25,6 +25,8 @@ Simple data can be accessed using keyfiles that record pieces of information as
More complex and larger data is also included in the user data directories by applications where it does not necessarily make sense for the user to decide where their data should be stored. These applications function like appliances, hiding the details of data storage, or using different ways to refer to user data than applications using the traditional *Open*, *Load* and *Save* actions.
Applications distributed as flatpaks do not need to request permissions in order to access user data stored in a data directory that has been set aside for that purpose.
Files
-----
......@@ -33,7 +35,7 @@ Traditional applications can load and save files from arbitrary directories as l
Some applications rely on finding data files in these standard locations, though they may also allow the user to select files from elsewhere, like traditional applications. These obtain the directory to access via the ``GLib.get_user_special_dir`` function, passing one of the ``Glib.UserDirectory`` values given in the table below.
=========================== ====================================================
**Value** **Contents**
**Directory** **Contents**
=========================== ====================================================
``DIRECTORY_DOCUMENTS`` Documents, such as text or word processing files
``DIRECTORY_DOWNLOAD`` Files downloaded by applications
......@@ -44,6 +46,22 @@ Some applications rely on finding data files in these standard locations, though
The photographs and videos taken by the camera are stored in the directories represented by ``DIRECTORY_PICTURES`` and ``DIRECTORY_VIDEOS`` respectively.
A more complete list of directories that can be accessed is provided in the `XDG Base Directory Specification`_ document.
.. Provide an example showing how to obtain the directory.
An application distributed as a flatpak needs to declare permissions in the ``finish-args`` entry of its manifest to be able to access these directories. The following table shows which permission corresponds to each directory, as described by the table above.
=================================== =======================
**Directory** **Flatpak Permission**
=================================== =======================
``DIRECTORY_DOCUMENTS`` ``--xdg-documents``
``DIRECTORY_DOWNLOAD`` ``--xdg-download``
``DIRECTORY_MUSIC`` ``--xdg-music``
``DIRECTORY_PICTURES`` ``--xdg-pictures``
``DIRECTORY_VIDEOS`` ``--xdg-videos``
=================================== =======================
See the :ref:`flatpak_app_permissions_guide` for a more complete description of permissions, and consult the `Sandbox Permissions`_ section of the Flatpak documentation for a more extensive list of permissions.
.. include:: /links.txt
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment