Commit 708a37f3 authored by David Boddie's avatar David Boddie 💬
Browse files

Add settings and permissions information

parent 0e466ccd
Pipeline #5404 passed with stage
in 11 minutes and 10 seconds
.. _gnome_settings:
Settings, User Data and Files
=============================
Applications access three kinds of information from the user's account: settings, user data and files. These hold three different kinds of information.
Settings
--------
Settings hold information about the way the user has configured an application, such as the font size, window size or theme. This information is typically about the application itself or metadata that describes data produced by the application.
GNOME applications access their settings using the GSettings_ class. This stores data in a suitable directory in the user's home directory. Applications distributed as flatpaks require permissions to be granted in order to access the user's settings. See the :ref:`flatpak_app_permissions_guide` guide for details.
.. _gnome_settings_user_data:
User Data
---------
Some applications prefer to store data that the user has created or imported in a special 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.
.. Include a snippet of this from the treasure example
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.
Files
-----
Traditional applications can load and save files from arbitrary directories as long as the user has permission to access them. For types of files that can be opened by many different applications, such as music and video files, it is common to find that directories have been set aside for these files in the user's home directory. The `XDG Base Directory Specification`_ describes how these directories are organized.
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_DOCUMENTS`` Documents, such as text or word processing files
``DIRECTORY_DOWNLOAD`` Files downloaded by applications
``DIRECTORY_MUSIC`` Music files
``DIRECTORY_PICTURES`` Pictures and photographs
``DIRECTORY_VIDEOS`` Movies and videos
=========================== ====================================================
The photographs and videos taken by the camera are stored in the directories represented by ``DIRECTORY_PICTURES`` and ``DIRECTORY_VIDEOS`` respectively.
.. Provide an example showing how to obtain the directory.
.. include:: /links.txt
......@@ -18,12 +18,14 @@ a typical GNOME development environment. The following sections cover use of
these tools in more detail.
.. toctree::
:maxdepth: 1
GNOME/Flatpak_setup
GNOME/GBuilder
GNOME/Gtk+
GNOME/Glade
GNOME/Application_Resources
GNOME/Settings
GNOME/Resources
.. include:: /links.txt
Sandbox Permissions
===================
.. _flatpak_app_permissions_guide:
When applications are distributed as flatpaks they need permission to access
certain features on the phone. This is done by requesting permissions in the
Flatpak manifest file. The table below shows which permissions correspond to
which features.
Application Permissions
=======================
.. |br| raw:: html
<br />
When an application is distributed as a flatpak it needs permission to access
certain features on the phone, such as using the network, or reading and
writing the user's files. This is done by requesting permissions in the Flatpak
manifest file.
The permissions required by an application are included in the ``finish-args``
entry of its manifest. The following example shows the first part of a manifest
for an application that uses the display and maintains user-specific settings:
.. literalinclude:: _files/example.json
:language: json
Some tasks can be performed without the need to request permissions. For
example, each application can store and retrieve user data in its own private
area. This mechanism for storing persistent data is described in the section
about :ref:`gnome_settings_user_data`.
Permissions for Common Features
-------------------------------
The table below shows the permissions that correspond to some common features
used by applications.
======================================= ================================================
Feature Flatpak Permissions
======================================= ================================================
Display a graphical user interface. ``--socket=wayland``
Access the Internet using sockets. ``--share=network``
Display a graphical user interface ``--socket=wayland``
Access the Internet using sockets ``--share=network``
Access settings (GNOME applications) ``--filesystem=~/.config/dconf:ro`` |br|
``--talk-name=ca.desrt.dconf`` |br|
``--env=DCONF_USER_CONFIG_DIR=.config/dconf``
Access Bluetooth devices ``--allow=bluetooth``
Read and write user's documents ``--xdg-documents``
Read and write user's downloads ``--xdg-download``
Read and write user's music ``--xdg-music``
Read and write user's pictures ``--xdg-pictures``
Read and write user's videos ``--xdg-videos``
======================================= ================================================
Asking for Permission
---------------------
The permissions required by an application are included in the ``finish-args``
entry of its manifest. The following example shows the first part of a manifest
for an application that uses the display and maintains user-specific settings:
.. literalinclude:: _files/example.json
:language: json
A more detailed description of permissions is given in the `Flatpak Sandbox
Permissions`_ section of the Flatpak documentation.
A more detailed description of permissions is given in the `Sandbox Permissions`_
section of the Flatpak documentation, which also contains a more extensive list.
.. include:: /links.txt
......@@ -12,30 +12,40 @@
.. _`Flatpak Building Introduction`: http://docs.flatpak.org/en/latest/building-introduction.html
.. _`Flatpak debugging documentation`: http://docs.flatpak.org/en/latest/debugging.html
.. _`Flatpak documentation`: http://docs.flatpak.org/en/latest/
.. _`Flatpak Sandbox Permissions`: http://docs.flatpak.org/en/latest/sandbox-permissions.html
.. _`Freedesktop quick reference`: http://docs.flatpak.org/en/latest/freedesktop-quick-reference.html
.. _`Gio.GApplication documentation`: https://developer.gnome.org/gio/stable/GApplication.html#g-application-id-is-valid
.. _`git-buildpackage`: http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html
.. _`GKeyFile`: https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html
.. _`Glade`: https://glade.gnome.org/
.. _`Glade Tutorials`: https://wiki.gnome.org/action/show/Apps/Glade/Tutorials
.. _`glib-compile-resources`: https://developer.gnome.org/gio/stable/glib-compile-resources.html
.. _`g_get_user_data_dir`: https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-get-user-data-dir
.. _`GMenu`: https://developer.gnome.org/gio/2.60/GMenu.html
.. _`GNOME API Reference`: https://developer.gnome.org/references
.. _`GNOME Builder`: https://wiki.gnome.org/Apps/Builder
.. _`GNOME Builder documentation`: https://builder.readthedocs.io/en/latest/
.. _`GNOME git client`: https://wiki.gnome.org/Apps/Gitg
.. _`GNOME`: https://www.gnome.org
.. _`GNOME Human Interface Guidelines`: https://developer.gnome.org/hig/stable/
.. _`The GNU Privacy Handbook`: https://gnupg.org/gph/en/manual.html
.. _`GResource`: https://developer.gnome.org/gio/stable/GResource.html
.. _`GSettings`: https://developer.gnome.org/gio/stable/GSettings.html
.. _`GSimpleAction`: https://developer.gnome.org/gio/2.60/GSimpleAction.html
.. _`GTK+ 3 documentation`: https://developer.gnome.org/gtk3/stable/
.. _`GtkApplicationWindow`: https://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html
.. _GtkButton : https://developer.gnome.org/gtk3/stable/GtkButton.html
.. _GtkHeaderBar : https://developer.gnome.org/gtk3/stable/GtkHeaderBar.html
.. _`GTK+ Inspector`: https://wiki.gnome.org/Projects/GTK+/Inspector
.. _GtkLabel ellipize property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--ellipsize
.. _GtkLabel ellipsize property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--ellipsize
.. _GtkLabel : https://developer.gnome.org/gtk3/stable/GtkLabel.html
.. _GtkLabel wrap-mode property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap-mode
.. _GtkLabel wrap property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap
.. _GtkLabel xalign property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--xalign
.. _GtkMenuButton: https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkMenuButton
.. _GtkSeparator : https://developer.gnome.org/gtk3/stable/GtkSeparator.html
.. _GtkScrolledWindow : https://developer.gnome.org/gtk3/stable/GtkScrolledWindow.html
.. _GtkSizeGroup : https://developer.gnome.org/gtk3/stable/GtkSizeGroup.html
.. _GtkToolButton : https://developer.gnome.org/gtk3/stable/GtkToolButton.html
.. _`GTK+ toolkit`: https://www.gtk.org
.. _`GTK+ website`: https://www.gtk.org/
.. _HdyHeaderGroup : https://honk.sigxcpu.org/projects/libhandy/doc/HdyHeaderGroup.html
......@@ -71,7 +81,9 @@
.. _`Qt Quick`: https://doc.qt.io/qt-5/qtquick-index.html
.. _`Qt Quick Controls 2`: https://doc.qt.io/qt-5/qtquickcontrols2-index.html
.. _`Running GTK+ Applications`: https://developer.gnome.org/gtk3/stable/gtk-running.html
.. _`Sandbox Permissions`: http://docs.flatpak.org/en/latest/sandbox-permissions-reference.html
.. _`Scalable Vector Graphics`: https://www.w3.org/TR/SVG/
.. _`XDG Base Directory Specification`: http://www.freedesktop.org/Standards/basedir-spec
.. _`FH34SRJ-6S-0.5SH(50) (Touch)`: https://www.hirose.com/product/download/?distributor=digikey&type=2d&lang=en&num=FH34SRJ-6S-0.5SH(50)
.. _`74LVC2G241DC,125`: https://assets.nexperia.com/documents/data-sheet/74LVC2G241.pdf
......
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