GSettings Settings Handler

From wiki.gpii
Jump to: navigation, search

Description

The GSettings Settings Handler is one of several Settings Handlers available to the Cloud4All/GPII implementers when making their solution (application) compatible with the GPII. The GSettings Settings Handler is able to read and write values in the Linux' GSettings system, used amongst other in Gnome.

The focus of this page will be the specifics of the GSettings Settings Handlers, for more general information about how and where Settings Handlers are used, we refer to the Settings Handler Documentation.

Using the GSettings Settings Handler

Like all settings handlers, this one is used in the solution entries of the Solution Registry, describing how a particular solution configures the settings handler and what application settings are supported. As described in the general settings handler documentation, there are four key-value pairs in each settings handler declaration, namely: type, options, capabilities and capabilitiesTransformations. For the GSettings Settings Handler, they should contain the following format:

  • "type": This denotes the settings handler to be used and should always have the value "gpii.gsettings.set" when using the GSettings settings handler.
  • "options": In the options block, only one key is supported by the GSettings Settings Handler. This is "schema", which refers to the gsettings schema in which the relevant settings are located. The declaration of a schema is mandatory. If a solution modifies values in several different schemas, one gsettings settings handler block should be created for each schema.
  • "capabilities": This array tells what ontology terms the solution matches. This block is not specific to the GSettings settings handler, and we refer to the Settings Handler Documentation for more information.
  • "capabilityTransformations": As always, this blocks describes how common terms (from the Common Terms Registry) translates into settings understandable by the application. The indexes (keys) of this hash should match the gsettings keys to be set, and the values should be the Common Term that matches the gsettings key. Often the settings of an application might not entirely match that of a Common Term (eg. one might specify font size in pixels and the other one in points), for this type of transformations the Transformer is used - more information can be found here.

Below you can find an example of how the GSettings Settings Handler is used. For more information about Settings Handlers and the individual blocks described above, see this page. The capabilityTransformation block is simple in it's most basic form, but get rather complicated due the transformations. Information on what transformations are available and their syntax can be found on the Transformer page

Examples

Below is an example of usage. Note that the below is an example snippet from a longer solution declaration found in the Solution Registry.

As always, for GSettings Settings Handlers the type signature is "gpii.gsettings.set". The schema to be modified in the example is "org.gnome.desktop.a11y.magnifier" which contains the values related to the built in magnifier of Gnome Shell. The capabilities block declares that this solution covers the needs and preferences described by the nested ontology term "display.screenEnhancement.screenMagnification". The "applications.org\\.gnome\\.desktop\\.a11y\\.magnifier.name" is temporary due to a bug in the system.

The capabilitiesTransformations describes three settings, namely mag-factor, show-cross-hairs and mouse-tracking. The first two get their values directly from the "display.screenEnhancement.magnification" and "display.screenEnhancement.showCrosshairs" as declared in the users Needs and Preferences Set. The mouse-tracking is assigned the result of a more complicated transformation based on the value the user has set for "display.screenEnhancement.tracking". If this user setting has the value "mouse", the "mouse-tracking" gsettings key will have the value "centered" assigned. For more information about the available transformations, see the documentation on the Transformer.

<syntaxhighlight lang="javascript">

      "settingsHandlers": [
           {
               "type": "gpii.gsettings.set",
               "options": {
                   "schema": "org.gnome.desktop.a11y.magnifier"
               },
               "capabilities": [
                   "display.screenEnhancement.screenMagnification.applications.org\\.gnome\\.desktop\\.a11y\\.magnifier.name" 
               ],
               "capabilitiesTransformations": {
                   "mag-factor": "display.screenEnhancement.magnification",
                   "show-cross-hairs": "display.screenEnhancement.showCrosshairs",
                   "mouse-tracking": {
                       "expander": {
                           "type": "fluid.model.transform.valueMapper",
                           "inputPath": "display.screenEnhancement.tracking",
                           "options": {
                               "mouse": {
                                   "outputValue": "centered"
                               }
                           }
                       }
                   }
               }
           }
       ],

</syntaxhighlight>