GioSettings

GSettings 类提供了一个便利的 API，用于存储和检索应用程序设置。

读写可以认为是非阻塞的。使用GSettings读取设置通常非常快：大约与GHashTable查找同一数量级（但较慢）。写入设置在返回您的应用程序方面也非常快，但可能对其他线程和其他进程非常昂贵。许多设置后端（包括dconf）都有懒初始化，这意味着在用户通常不修改任何设置的常见情况下，可以避免大量工作。对于dconf，在这种情况下甚至不需要启动D-Bus服务。因此，您应该仅在实际用户显式动作的情况下修改GSettings密钥。特别应小心确保不在启动时进行修改——例如，设置首选项小部件的初始值。内置的g_settings_bind()功能注意不在通过修改小部件而产生通知信号的响应中写入设置。

创建一个GSettings实例时，您必须指定一个描述设置中的密钥及其类型和默认值的架构，以及其他一些信息。

通常，架构有一个固定的路径，用于确定设置在概念全球树中的存储位置。然而，架构也可以是“可移动的”，即没有固定的路径。这在例如，架构描述了“账户”，您希望能够存储任意数量的账户时很有用。

路径必须以正斜杠字符（/）开始和结束，并且不能包含连续的两个斜杠字符。路径应根据与属于程序的设置所属的域相关联的域名来选择。路径示例包括 /org/gtk/settings/file-chooser/ 和 /ca/desrt/dconf-editor/。路径不应以 /apps/、/desktop/ 或 /system/ 开头，因为它们在 GConf 中往往如此。

与其他配置系统（如 GConf）不同，GSettings 不限制键的基本类型（如字符串和数字）。GSettings 使用 GVariant 存储值，并允许任何 GVariantType 键。键名仅限于小写字母、数字和 -。此外，名称必须以小写字母开头，不得以 - 结尾，并且不得包含连续的破折号。

与 GConf 类似，GSettings 架构中的默认值可以本地化，但本地化值存储在 gettext 目录中，并通过指定在<schemalist>或<schema>元素中指定和<default>元素中指定在l10n属性中指定的域和类别来查找。翻译的字符串包括 <default> 元素中包括任何周围引号的所有文本。

l10n 属性必须设置为 messages 或 time，并设置地区分类以进行翻译。“ messages”类别应默认使用；对于可翻译的日期或时间格式，请使用“ time”。可以在 <default> 元素上面的 XML 注释中添加翻译注释——建议将这些注释添加以帮助翻译者了解默认值的含义和影响。可以在 <default> 元素上设置可选的翻译context属性，以消除使用相同字符串的多个默认值之间的歧义。

例如

 <!-- Translators: A list of words which are not allowed to be typed, in
      GVariant serialization syntax.
      See: https://developer.gnome.org/glib/stable/gvariant-text.html -->
 <default l10n='messages' context='Banned words'>['bad', 'words']</default>

默认值的翻译必须保持作为序列化的GVariant的语法有效性（例如，保留任何周围的引号），或者将发生运行时错误。

GSettings 使用由 glib-compile-schemas 工具创建的紧凑二进制格式的 schema。输入是一个 XML 格式的 schema 描述。

gschema XML 格式的 DTD 可以在这里找到：gschema.dtd

glib-compile-schemas 工具期望 schema 文件扩展名为 .gschema.xml。

在运行时，schema 通过其 ID（如 <schema> 元素的 id 属性中指定）来识别。schema ID 的约定是使用点名称，类似于 D-Bus 总线名称的风格，例如 org.gnome.SessionManager。特别是，如果设置是为拥有 D-Bus 总线名称的特定服务，那么 D-Bus 总线名称和 schema ID 应该相匹配。对于处理不与特定应用名称相关联的设置的 schema，ID 不应使用 StudlyCaps，例如 org.gnome.font-rendering。

除了 GVariant 类型，键还可以有枚举类型。这些可以通过 <choice>、<enum> 或 <flags> 元素来描述，如下面的第二个示例所示。此类键的底层类型是字符串，但您可以使用 g_settings_get_enum()、g_settings_set_enum()、g_settings_get_flags()、g_settings_set_flags() 访问枚举和标志键的相应数值。

默认值的示例

<schemalist>
  <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">

    <key name="greeting" type="s">
      <default l10n="messages">"Hello, earthlings"</default>
      <summary>A greeting</summary>
      <description>
        Greeting of the invading martians
      </description>
    </key>

    <key name="box" type="(ii)">
      <default>(20,30)</default>
    </key>

    <key name="empty-string" type="s">
      <default>""</default>
      <summary>Empty strings have to be provided in GVariant form</summary>
    </key>

  </schema>
</schemalist>

范围、选择和枚举类型的示例

<schemalist>

  <enum id="org.gtk.Test.myenum">
    <value nick="first" value="1"/>
    <value nick="second" value="2"/>
  </enum>

  <flags id="org.gtk.Test.myflags">
    <value nick="flag1" value="1"/>
    <value nick="flag2" value="2"/>
    <value nick="flag3" value="4"/>
  </flags>

  <schema id="org.gtk.Test">

    <key name="key-with-range" type="i">
      <range min="1" max="100"/>
      <default>10</default>
    </key>

    <key name="key-with-choices" type="s">
      <choices>
        <choice value='Elisabeth'/>
        <choice value='Annabeth'/>
        <choice value='Joe'/>
      </choices>
      <aliases>
        <alias value='Anna' target='Annabeth'/>
        <alias value='Beth' target='Elisabeth'/>
      </aliases>
      <default>'Joe'</default>
    </key>

    <key name='enumerated-key' enum='org.gtk.Test.myenum'>
      <default>'first'</default>
    </key>

    <key name='flags-key' flags='org.gtk.Test.myflags'>
      <default>["flag1","flag2"]</default>
    </key>
  </schema>
</schemalist>

供应商覆盖

默认值定义在应用程序安装的 schema 中。有时，供应商或发行商需要调整这些默认值。由于修补 schema 的 XML 源不便且容易出错，glib-compile-schemas 读取所谓的“供应商覆盖”文件。这些是位于 XML schema 源同一目录中的密钥文件，可以覆盖默认值。schema ID 作为密钥文件中的组名，值期望以序列化 GVariant 形式提供，如下面的示例所示

[org.gtk.Example]
key1='string'
key2=1.5

glib-compile-schemas 期望 schema 文件扩展名为 .gschema.override。

绑定

GSettings 的一个非常方便的功能允许您使用 g_settings_bind() 直接将 GObject 属性绑定到设置。一旦一个 GObject 属性被绑定到一个设置，任何一方的更改都会自动传播到另一方。GSettings 处理诸如 GObject 和 GVariant 类型之间的映射以及防止无限循环等细节。

这使得非常适合将优先级对话框连接到底层设置中。为了让这更加方便，GSettings 会寻找一个名为 sensitivity 的布尔属性，并将其自动绑定到绑定设置的写性上。如果这种“魔法”妨碍了操作，可以使用 G_SETTINGS_BIND_NO_SENSITIVITY 标志来抑制。

可重定位模式

可重定位模式是指在它的 <schema> 元素上没有指定 path 属性的模式。通过使用 g_settings_new_with_path()，可以为可重定位模式创建一个 GSettings 对象，并将路径分配给实例。传递给 g_settings_new_with_path() 的路径通常由一个常前缀加上某种类型的实例标识符动态构建；但它们必须是有效的 GSettings 路径。路径也可以是常量，并与来自依赖库的全球安装的模式一起使用。

例如，可以使用可重定位模式存储应用程序中不同窗口的几何信息。如果模式 ID 为 org.foo.MyApp.Window，则可以为路径 /org/foo/MyApp/main/、/org/foo/MyApp/document-1/、/org/foo/MyApp/document-2/ 等等创建实例。如果有任何路径是众所周知的，则可以将它们指定为父模式中的 <child> 元素，例如：

<schema id="org.foo.MyApp" path="/org/foo/MyApp/">
  <child name="main" schema="org.foo.MyApp.Window"/>
</schema>

构建系统集成

Meson

GSettings 是 Meson 的 GNOME 模块 的原生支持。

您可以像安装其他数据文件一样安装模式

install_data(
  'org.foo.MyApp.gschema.xml',
  install_dir: get_option('datadir') / 'glib-2.0/schemas',
)

您可以使用 gnome.post_install() 函数在安装时编译模式

gnome = import('gnome')
gnome.post_install(
  glib_compile_schemas: true,
)

如果要在 GSettings 模式中使用在 C 头文件中定义的枚举类型，既可以使用模式 XML 中的 <enum> 元素手动定义它，也可以从 C 头文件自动提取。这种方法是首选的，因为它确保两种表示始终同步。为了做到这一点，您需要使用 gnome.mkenums() 函数和以下模板：

schemas_enums = gnome.mkenums('org.foo.MyApp.enums.xml',
  comments: '<!-- @comment@ -->',
  fhead: '<schemalist>',
  vhead: '  <@type@ id="org.foo.MyApp.@EnumName@">',
  vprod: '    <value nick="@valuenick@" value="@valuenum@"/>',
  vtail: '  </@type@>',
  ftail: '</schemalist>',
  sources: enum_sources,
  install_header: true,
  install_dir: get_option('datadir') / 'glib-2.0/schemas',
)

建议您将验证模式作为您应用程序测试套件的一部分进行

test('validate-schema',
  find_program('glib-compile-schemas'),
  args: ['--strict', '--dry-run', meson.current_source_dir()],
)

如果您的应用程序允许运行未安装的程序，您还应该使用 gnome.compile_schemas() 函数在当前构建目录中编译模式

gnome.compile_schemas()

自动工具

GSettings 包含自动工具集成以简化模式的编译和安装。要将 GSettings 支持添加到应用程序中，请向您的 configure.ac 添加以下内容：

GLIB_GSETTINGS

在适当的 Makefile.am 中，使用以下片段编译和安装命名模式：

gsettings_SCHEMAS = org.foo.MyApp.gschema.xml
EXTRA_DIST = $(gsettings_SCHEMAS)

@GSETTINGS_RULES@

如果要在 GSettings 模式中使用在 C 头文件中定义的枚举类型，既可以使用模式 XML 中的 <enum> 元素手动定义它，也可以从 C 头文件自动提取。这种方法是首选的，因为它确保两种表示始终同步。为了做到这一点，请将以下内容添加到相关的 Makefile.am：

gsettings_ENUM_NAMESPACE = org.foo.MyApp
gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h

gsettings_ENUM_NAMESPACE 指定了枚举文件的架构命名空间，这些文件在 gsettings_ENUM_FILES 中指定。这将会生成一个包含提取枚举的 org.foo.MyApp.enums.xml 文件，该文件将在架构编译、安装和卸载规则中自动包含。它不应提交到版本控制或包含在 EXTRA_DIST 中。

本地化

为标记架构 XML 文件进行翻译，无需对构建系统进行任何更改。假设它设置了 gettext-domain 属性，如果使用的是 gettext 0.19 或更高版本（翻译的首选方法），则可以通过将其添加到 POTFILES.in 中来标记架构为翻译。

data/org.foo.MyApp.gschema.xml

或者，如果使用的是 intltool 0.50.1

[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml

GSettings 将使用 gettext 查找 <summary> 和 <description> 元素以及任何设置了 l10n 属性的 <default> 元素的翻译。

翻译不得通过构建系统包含在 .gschema.xml 文件中，例如通过使用规则从模板生成 XML 文件。