mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-08-01 15:03:39 +02:00
Merge the GSettings docs
This commit is contained in:
Matthias Clasen
@@ -26,6 +26,7 @@ IGNORE_HFILES= \
|
||||
fen-node.h \
|
||||
gasynchelper.h \
|
||||
gcontenttypeprivate.h \
|
||||
gdelayedsettingsbackend.h \
|
||||
gdummyfile.h \
|
||||
gfamdirectorymonitor.h \
|
||||
gfamfilemonitor.h \
|
||||
@@ -37,6 +38,7 @@ IGNORE_HFILES= \
|
||||
gio.h \
|
||||
gioalias.h \
|
||||
gioalias.h \
|
||||
gkeyfilesettingsbackend.h \
|
||||
gioenumtypes.h \
|
||||
giomodule-priv.h \
|
||||
glocaldirectorymonitor.h \
|
||||
@@ -49,8 +51,10 @@ IGNORE_HFILES= \
|
||||
glocalvfs.h \
|
||||
gnativevolumemonitor.h \
|
||||
gnetworkingprivate.h \
|
||||
gnullsettingsbackend.h \
|
||||
gpollfilemonitor.h \
|
||||
gsettingsbackendinternal.h \
|
||||
gsettingsschema.h \
|
||||
gthreadedresolver.h \
|
||||
gunionvolumemonitor.h \
|
||||
gunixdrive.h \
|
||||
@@ -114,7 +118,9 @@ content_files = \
|
||||
|
||||
expand_content_files = \
|
||||
overview.xml \
|
||||
migrating.xml
|
||||
migrating.xml \
|
||||
gschema-compile.xml \
|
||||
gsettings-schema-convert.xml
|
||||
|
||||
extra_files = \
|
||||
version.xml.in \
|
||||
@@ -124,3 +130,23 @@ include $(top_srcdir)/gtk-doc.make
|
||||
|
||||
EXTRA_DIST += \
|
||||
version.xml.in
|
||||
|
||||
if ENABLE_MAN
|
||||
|
||||
man_MANS = \
|
||||
gschema-compile.1 \
|
||||
gsettings-schema-convert.1
|
||||
|
||||
%.1 : xml/%.xml
|
||||
@XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
|
||||
|
||||
endif
|
||||
|
||||
BUILT_EXTRA_DIST = $(man_MANS)
|
||||
|
||||
dist-hook-local: $(BUILT_EXTRA_DIST)
|
||||
files='$(BUILT_EXTRA_DIST)'; \
|
||||
for f in $$files; do \
|
||||
if test -f $$f; then d=.; else d=$(srcdir); fi; \
|
||||
cp $$d/$$f $(distdir) || exit 1; done
|
||||
|
||||
|
||||
@@ -20,24 +20,24 @@
|
||||
<part>
|
||||
<title>API Reference</title>
|
||||
<chapter id="file_ops">
|
||||
<title>File Operations</title>
|
||||
<xi:include href="xml/gfile.xml"/>
|
||||
<title>File Operations</title>
|
||||
<xi:include href="xml/gfile.xml"/>
|
||||
<xi:include href="xml/gfileattribute.xml"/>
|
||||
<xi:include href="xml/gfileinfo.xml"/>
|
||||
<xi:include href="xml/gfileenumerator.xml"/>
|
||||
<xi:include href="xml/gioerror.xml"/>
|
||||
<xi:include href="xml/gmountoperation.xml"/>
|
||||
<xi:include href="xml/gfileinfo.xml"/>
|
||||
<xi:include href="xml/gfileenumerator.xml"/>
|
||||
<xi:include href="xml/gioerror.xml"/>
|
||||
<xi:include href="xml/gmountoperation.xml"/>
|
||||
</chapter>
|
||||
<chapter id="file_mon">
|
||||
<title>File System Monitoring</title>
|
||||
<title>File System Monitoring</title>
|
||||
<xi:include href="xml/gfilemonitor.xml"/>
|
||||
</chapter>
|
||||
<chapter id="async">
|
||||
<title>Asynchronous I/O</title>
|
||||
<xi:include href="xml/gcancellable.xml"/>
|
||||
<xi:include href="xml/gasyncresult.xml"/>
|
||||
<xi:include href="xml/gcancellable.xml"/>
|
||||
<xi:include href="xml/gasyncresult.xml"/>
|
||||
<xi:include href="xml/gioscheduler.xml"/>
|
||||
<xi:include href="xml/gsimpleasyncresult.xml"/>
|
||||
<xi:include href="xml/gsimpleasyncresult.xml"/>
|
||||
</chapter>
|
||||
<chapter id="conversion">
|
||||
<title>Data conversion</title>
|
||||
@@ -48,7 +48,7 @@
|
||||
</chapter>
|
||||
<chapter id="streaming">
|
||||
<title>Streaming I/O</title>
|
||||
<xi:include href="xml/gseekable.xml"/>
|
||||
<xi:include href="xml/gseekable.xml"/>
|
||||
<xi:include href="xml/ginputstream.xml"/>
|
||||
<xi:include href="xml/goutputstream.xml"/>
|
||||
<xi:include href="xml/giostream.xml"/>
|
||||
@@ -72,30 +72,30 @@
|
||||
<chapter id="types">
|
||||
<title>File types and applications</title>
|
||||
<xi:include href="xml/gcontenttype.xml"/>
|
||||
<xi:include href="xml/gappinfo.xml"/>
|
||||
<xi:include href="xml/gdesktopappinfo.xml"/>
|
||||
<xi:include href="xml/gappinfo.xml"/>
|
||||
<xi:include href="xml/gdesktopappinfo.xml"/>
|
||||
</chapter>
|
||||
<chapter id="volume_mon">
|
||||
<title>Volumes and Drives</title>
|
||||
<title>Volumes and Drives</title>
|
||||
<xi:include href="xml/gvolumemonitor.xml"/>
|
||||
<xi:include href="xml/gvolume.xml"/>
|
||||
<xi:include href="xml/gvolume.xml"/>
|
||||
<xi:include href="xml/gmount.xml"/>
|
||||
<xi:include href="xml/gdrive.xml"/>
|
||||
<xi:include href="xml/gunixmounts.xml"/>
|
||||
<xi:include href="xml/gdrive.xml"/>
|
||||
<xi:include href="xml/gunixmounts.xml"/>
|
||||
</chapter>
|
||||
<chapter id="icons">
|
||||
<title>Icons</title>
|
||||
<xi:include href="xml/gicon.xml"/>
|
||||
<xi:include href="xml/gfileicon.xml"/>
|
||||
<xi:include href="xml/gloadableicon.xml"/>
|
||||
<xi:include href="xml/gthemedicon.xml"/>
|
||||
<xi:include href="xml/gemblemedicon.xml"/>
|
||||
<xi:include href="xml/gemblem.xml"/>
|
||||
<title>Icons</title>
|
||||
<xi:include href="xml/gicon.xml"/>
|
||||
<xi:include href="xml/gfileicon.xml"/>
|
||||
<xi:include href="xml/gloadableicon.xml"/>
|
||||
<xi:include href="xml/gthemedicon.xml"/>
|
||||
<xi:include href="xml/gemblemedicon.xml"/>
|
||||
<xi:include href="xml/gemblem.xml"/>
|
||||
</chapter>
|
||||
<chapter id="failable_initialization">
|
||||
<title>Failable Initialization</title>
|
||||
<xi:include href="xml/ginitable.xml"/>
|
||||
<xi:include href="xml/gasyncinitable.xml"/>
|
||||
<title>Failable Initialization</title>
|
||||
<xi:include href="xml/ginitable.xml"/>
|
||||
<xi:include href="xml/gasyncinitable.xml"/>
|
||||
</chapter>
|
||||
<chapter id="networking">
|
||||
<title>Lowlevel platform-independent network support</title>
|
||||
@@ -125,14 +125,24 @@
|
||||
<xi:include href="xml/gthreadedsocketservice.xml"/>
|
||||
</chapter>
|
||||
<chapter id="utils">
|
||||
<title>Utilities</title>
|
||||
<title>Utilities</title>
|
||||
<xi:include href="xml/gfilenamecompleter.xml"/>
|
||||
</chapter>
|
||||
<chapter id="settings">
|
||||
<title>Settings</title>
|
||||
<xi:include href="xml/gsettings.xml"/>
|
||||
<xi:include href="xml/gsettingsbackend.xml"/>
|
||||
</chapter>
|
||||
<chapter id="extending">
|
||||
<title>Extending GIO</title>
|
||||
<title>Extending GIO</title>
|
||||
<xi:include href="xml/gvfs.xml"/>
|
||||
<xi:include href="xml/giomodule.xml"/>
|
||||
<xi:include href="xml/extensionpoints.xml"/>
|
||||
<xi:include href="xml/giomodule.xml"/>
|
||||
<xi:include href="xml/extensionpoints.xml"/>
|
||||
</chapter>
|
||||
<chapter id="tools">
|
||||
<title>GIO Tools</title>
|
||||
<xi:include href="xml/gschema-compile.xml"/>
|
||||
<xi:include href="xml/gsettings-schema-convert.xml"/>
|
||||
</chapter>
|
||||
</part>
|
||||
|
||||
@@ -167,8 +177,4 @@
|
||||
<title>Index of new symbols in 2.24</title>
|
||||
<xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
|
||||
</index>
|
||||
<index id="api-index-2-26" role="2.26">
|
||||
<title>Index of new symbols in 2.26</title>
|
||||
<xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
|
||||
</index>
|
||||
</book>
|
||||
|
||||
@@ -2075,3 +2075,85 @@ G_FILE_DESCRIPTOR_BASED_GET_IFACE
|
||||
G_IS_FILE_DESCRIPTOR_BASED
|
||||
G_TYPE_FILE_DESCRIPTOR_BASED
|
||||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
<FILE>gsettingsbackend</FILE>
|
||||
<TITLE>GSettingsBackend</TITLE>
|
||||
GSettingsBackend
|
||||
GSettingsBackendClass
|
||||
G_SETTINGS_BACKEND_EXTENSION_POINT_NAME
|
||||
g_settings_backend_changed
|
||||
g_settings_backend_path_changed
|
||||
g_settings_backend_keys_changed
|
||||
g_settings_backend_path_writable_changed
|
||||
g_settings_backend_writable_changed
|
||||
g_settings_backend_changed_tree
|
||||
|
||||
<SUBSECTION Standard>
|
||||
G_IS_SETTINGS_BACKEND
|
||||
G_IS_SETTINGS_BACKEND_CLASS
|
||||
G_SETTINGS_BACKEND
|
||||
G_SETTINGS_BACKEND_CLASS
|
||||
G_SETTINGS_BACKEND_GET_CLASS
|
||||
|
||||
<SUBSECTION Private>
|
||||
g_settings_backend_get_type
|
||||
GSettingsBackendPrivate
|
||||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
<FILE>gsettings</FILE>
|
||||
<TITLE>GSettings</TITLE>
|
||||
GSettings
|
||||
g_settings_new
|
||||
g_settings_new_with_path
|
||||
g_settings_new_with_context
|
||||
g_settings_new_with_context_and_path
|
||||
g_settings_supports_context
|
||||
g_settings_get_value
|
||||
g_settings_set_value
|
||||
g_settings_is_writable
|
||||
g_settings_delay
|
||||
g_settings_apply
|
||||
g_settings_revert
|
||||
g_settings_get_has_unapplied
|
||||
g_settings_get_child
|
||||
|
||||
<SUBSECTION Convenience>
|
||||
g_settings_get
|
||||
g_settings_set
|
||||
g_settings_get_boolean
|
||||
g_settings_set_boolean
|
||||
g_settings_get_int
|
||||
g_settings_set_int
|
||||
g_settings_get_double
|
||||
g_settings_set_double
|
||||
g_settings_get_string
|
||||
g_settings_set_string
|
||||
g_settings_get_strv
|
||||
g_settings_set_strv
|
||||
|
||||
<SUBSECTION Binding>
|
||||
GSettingsBindFlags
|
||||
g_settings_bind
|
||||
g_settings_bind_with_mapping
|
||||
g_settings_unbind
|
||||
GSettingsBindSetMapping
|
||||
GSettingsBindGetMapping
|
||||
|
||||
<SUBSECTION Standard>
|
||||
GSettingsClass
|
||||
G_IS_SETTINGS
|
||||
G_IS_SETTINGS_CLASS
|
||||
G_IS_SETTINGS_SCHEMA
|
||||
G_IS_SETTINGS_SCHEMA_CLASS
|
||||
G_SETTINGS
|
||||
G_SETTINGS_CLASS
|
||||
G_SETTINGS_GET_CLASS
|
||||
G_SETTINGS_SCHEMA
|
||||
G_SETTINGS_SCHEMA_CLASS
|
||||
G_SETTINGS_SCHEMA_GET_CLASS
|
||||
|
||||
<SUBSECTION Private>
|
||||
g_settings_get_type
|
||||
</SECTION>
|
||||
|
||||
@@ -72,6 +72,8 @@ g_password_save_get_type
|
||||
g_resolver_error_get_type
|
||||
g_resolver_get_type
|
||||
g_seekable_get_type
|
||||
g_settings_get_type
|
||||
g_settings_backend_get_type
|
||||
g_simple_async_result_get_type
|
||||
g_socket_address_enumerator_get_type
|
||||
g_socket_address_get_type
|
||||
|
||||
61
docs/reference/gio/gschema-compile.xml
Normal file
61
docs/reference/gio/gschema-compile.xml
Normal file
@@ -0,0 +1,61 @@
|
||||
<refentry id="gschema-compile" lang="en">
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>gschema-compile</refentrytitle>
|
||||
<manvolnum>1</manvolnum>
|
||||
<refmiscinfo class="manual">User Commands</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>gschema-compile</refname>
|
||||
<refpurpose>GSettings schema compiler</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<cmdsynopsis>
|
||||
<command>gschema-compile</command>
|
||||
<arg choice="opt" rep="repeat">option</arg>
|
||||
<arg choice="req">directory</arg>
|
||||
</cmdsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1><title>Description</title>
|
||||
<para><command>gschema-compile</command> compiles all the GSettings XML
|
||||
schema files in <replaceable>directory</replaceable> into a binary file
|
||||
with the name <filename>gschemas.compiled</filename> that can be used
|
||||
by #GSettings. The XML schema files must have the filename extension
|
||||
<filename>.gschema</filename>. For a detailed description of the XML
|
||||
file format, see the #GSettings documentation.
|
||||
</para>
|
||||
|
||||
<refsect2><title>Options</title>
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-h</option>, <option>--help</option></term>
|
||||
<listitem><para>
|
||||
Print help and exit
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>--targetdir=<replaceable>TARGETDIR</replaceable></option></term>
|
||||
<listitem><para>
|
||||
Store <filename>gschemas.compiled</filename> in <replaceable>TARGETDIR</replaceable> instead of <replaceable>directory</replaceable>.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>--allow-any-name</option></term>
|
||||
<listitem><para>
|
||||
Do not enforce restrictions on key names. Note that this option is purely
|
||||
to facility the transition from GConf, and will be removed at some time
|
||||
in the future.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
105
docs/reference/gio/gsettings-schema-convert.xml
Normal file
105
docs/reference/gio/gsettings-schema-convert.xml
Normal file
@@ -0,0 +1,105 @@
|
||||
<refentry id="gsettings-schema-convert" lang="en">
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>gsettings-schema-convert</refentrytitle>
|
||||
<manvolnum>1</manvolnum>
|
||||
<refmiscinfo class="manual">User Commands</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>gsettings-schema-convert</refname>
|
||||
<refpurpose>GConf to GSettings schema conversion</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<cmdsynopsis>
|
||||
<command>gsettings-schema-convert</command>
|
||||
<arg choice="opt" rep="repeat">option</arg>
|
||||
<arg choice="req">file</arg>
|
||||
</cmdsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1><title>Description</title>
|
||||
<para><command>gsettings-schema-convert</command> converts between GConf
|
||||
and GSettings schema file formats. Note that the conversion is not
|
||||
expected to be fully automated. You are expected to verify and edit
|
||||
the result of the conversion.
|
||||
</para>
|
||||
<para>
|
||||
Note that GSettings schemas need to be converted into binary form
|
||||
with <link linkend="gschema-compile">gschema-compile</link> before they
|
||||
can be used by applications.
|
||||
</para>
|
||||
|
||||
<refsect2><title>Options</title>
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-h</option>, <option>--help</option></term>
|
||||
<listitem><para>
|
||||
Print help and exit
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-o <replaceable>OUTPUT</replaceable></option>, <option>--output=<replaceable>OUTPUT</replaceable></option></term>
|
||||
<listitem><para>
|
||||
Store the generated output in the file <replaceable>OUTPUT</replaceable>. If no output file is specified, the generated output is written to stdout.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-f</option>, <option>--force</option></term>
|
||||
<listitem><para>
|
||||
Overwrite the output file if it already exists.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-g</option>, <option>--gconf</option></term>
|
||||
<listitem><para>
|
||||
The input file is a GConf schema.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-s</option>, <option>--simple</option></term>
|
||||
<listitem><para>
|
||||
The input file is a simple GSettings schema. If the input
|
||||
format is not explicitly specified, this is the default.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-x</option>, <option>--xml</option></term>
|
||||
<listitem><para>
|
||||
Produce a GSettings schema in XML format. If the output format
|
||||
is not explicitly specified, a GConf schema will be converted
|
||||
into a simple Gsettings schema, and a simple GSettings schema
|
||||
will be converted into XML.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-i <replaceable>ID</replaceable></option>, <option>--schema-id=<replaceable>ID</replaceable></option></term>
|
||||
<listitem><para>
|
||||
Use <replaceable>ID</replaceable> as the schema id in the generated
|
||||
GSettings schema.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
<refsect1><title>See also</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>gsettings-data-convert</refentrytitle>
|
||||
<manvolnum>1</manvolnum>
|
||||
</citerefentry> a related command to migrate user settings
|
||||
from GConf to GSettings.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
|
||||
@@ -120,7 +120,7 @@ start_monitoring_trash (void)
|
||||
reflect that state of the trash can.
|
||||
</para>
|
||||
<para>
|
||||
Moving a file to the trash is much simpler with GIO. Instead of
|
||||
Moving a file to the trash is much simpler with GIO. Instead of
|
||||
using gnome_vfs_find_directory() with %GNOME_VFS_DIRECTORY_KIND_TRASH
|
||||
to find out where to move the trashed file, just use the g_file_trash()
|
||||
function.
|
||||
@@ -151,12 +151,293 @@ start_monitoring_trash (void)
|
||||
gnome-vfs offered a way to monitor the association between mime types
|
||||
and default handlers for changes, with the #GnomeVFSMIMEMonitor object.
|
||||
GIO does not offer a replacement for this functionality at this time,
|
||||
since we have not found a compelling use case where
|
||||
since we have not found a compelling use case where
|
||||
#GnomeVFSMIMEMonitor was used. If you think you have such a use
|
||||
case, please report it at
|
||||
case, please report it at
|
||||
<ulink url="http://bugzilla.gnome.org">bugzilla.gnome.org</ulink>.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
<title>Migrating from GConf to GSettings</title>
|
||||
|
||||
<section>
|
||||
<title>Before you start</title>
|
||||
|
||||
<para>
|
||||
Converting individual applications and their settings from GConf to
|
||||
GSettings can be done at will. But desktop-wide settings like font or
|
||||
theme settings often have consumers in multiple modules. Therefore,
|
||||
some consideration has to go into making sure that all users of a setting
|
||||
are converted to GSettings at the same time or that the program
|
||||
responsible for configuring that setting continues to update the value in
|
||||
both places.
|
||||
</para>
|
||||
<para>
|
||||
It is always a good idea to have a look at how others have handled
|
||||
similar problems before. An examplaric conversion can be found e.g.
|
||||
in the <ulink url="http://git.gnome.org/browse/gnome-utils/log/?h=gsettings-tutorial">gsettings-tutorial</ulink> branch of gnome-utils.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Conceptual differences</title>
|
||||
|
||||
<para>
|
||||
Conceptually, GConf and GSettings are fairly similar. Both
|
||||
have a concept of pluggable backends. Both keep information
|
||||
about keys and their types in schemas. Both have a concept of
|
||||
mandatory values, which lets you implement lock-down.
|
||||
</para>
|
||||
<para>
|
||||
There are some differences in the approach to schemas. GConf
|
||||
installs the schemas into the database and has API to handle
|
||||
schema information (gconf_client_get_default_from_schema(),
|
||||
gconf_value_get_schema(), etc). GSettings on the other hand
|
||||
assumes that an application knows its own schemas, and does
|
||||
not provide API to handle schema information at runtime.
|
||||
GSettings is also more strict about requiring a schema whenever
|
||||
you want to read or write a key. To deal with more free-form
|
||||
information that would appear in schema-less entries in GConf,
|
||||
GSettings allows for schemas to be 'relocatable'.
|
||||
</para>
|
||||
<para>
|
||||
One difference in the way applications interact with their
|
||||
settings is that with GConf you interact with a tree of
|
||||
settings (ie the keys you pass to functions when reading
|
||||
or writing values are actually paths with the actual name
|
||||
of the key as the last element. With GSettings, you create
|
||||
a GSettings object which has an implicit prefix that determines
|
||||
where the settings get stored in the global tree of settings,
|
||||
but the keys you pass when reading or writing values are just
|
||||
the key names, not the full path.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>GConfClient API conversion</title>
|
||||
|
||||
<para>
|
||||
Most people use GConf via the high-level #GConfClient API.
|
||||
The corresponding API is the #GSettings object. While not
|
||||
every GConfClient function has a direct GSettings equivalent,
|
||||
many do:
|
||||
<table id="gconf-client-vs-gsettings">
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row><entry>GConfClient</entry><entry>GSettings</entry></row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row><entry>gconf_client_set()</entry><entry>g_settings_set()</entry></row>
|
||||
<row><entry>gconf_client_get()</entry><entry>g_settings_get()</entry></row>
|
||||
<row><entry>gconf_client_get_bool()</entry><entry>g_settings_get_boolean()</entry></row>
|
||||
<row><entry>gconf_client_set_bool()</entry><entry>g_settings_set_boolean()</entry></row>
|
||||
<row><entry>gconf_client_get_int()</entry><entry>g_settings_get_int()</entry></row>
|
||||
<row><entry>gconf_client_set_int()</entry><entry>g_settings_set_int()</entry></row>
|
||||
<row><entry>gconf_client_get_float()</entry><entry>g_settings_get_double()</entry></row>
|
||||
<row><entry>gconf_client_set_float()</entry><entry>g_settings_set_double()</entry></row>
|
||||
<row><entry>gconf_client_get_string()</entry><entry>g_settings_get_string()</entry></row>
|
||||
<row><entry>gconf_client_set_string()</entry><entry>g_settings_set_string()</entry></row>
|
||||
<row><entry>gconf_client_get_list()</entry><entry>for string lists, see g_settings_get_strv(), else see g_settings_get_value() and #GVariant API</entry></row>
|
||||
<row><entry>gconf_client_set_list()</entry><entry>for string lists, see g_settings_set_strv(), else see g_settings_set_value() and #GVariant API</entry></row>
|
||||
<row><entry>gconf_entry_get_is_writable()</entry><entry>g_settings_is_writable()</entry></row>
|
||||
<row><entry>gconf_client_notify_add()</entry><entry>not required, the #GSettings::changed signal is emitted automatically</entry></row>
|
||||
<row><entry>gconf_client_add_dir()</entry><entry>not required, each GSettings instance automatically watches all keys in its path</entry></row>
|
||||
<row><entry>#GConfChangeSet</entry><entry>g_settings_delay(), g_settings_apply()</entry></row>
|
||||
<row><entry>gconf_client_get_default_from_schema()</entry><entry>no equivalent, applications are expected to know their schema</entry></row>
|
||||
<row><entry>gconf_client_all_entries()</entry><entry>no equivalent, applications are expected to know their schema, and GSettings does not allow schema-less entries</entry></row>
|
||||
<row><entry>gconf_client_get_without_default()</entry><entry>no equivalent</entry></row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
<para>
|
||||
There is a pattern that is sometimes used for GConf, where a setting can have
|
||||
explicit 'value A', explicit 'value B' or 'use the system default'. With GConf,
|
||||
'use the system default' is sometimes implemented by unsetting the user value.
|
||||
</para>
|
||||
<para>
|
||||
This is not possible in GSettings, since it does not have API to determine if a value
|
||||
is the default and does not let you unset values. The recommended way (and much
|
||||
clearer) way in which this can be implemented in GSettings is to have a separate
|
||||
'use-system-default' boolean setting.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Change notification</title>
|
||||
|
||||
<para>
|
||||
GConf requires you to call gconf_client_add_dir() and
|
||||
gconf_client_notify_add() to get change notification. With
|
||||
GSettings, this is not necessary; signals get emitted automatically
|
||||
for every change.
|
||||
</para>
|
||||
<para>
|
||||
The #GSettings::changed signal is emitted for each changed key.
|
||||
There is also a #GSettings::change-event signal that you can handle
|
||||
if you need to see groups of keys that get changed at the same time.
|
||||
</para>
|
||||
<para>
|
||||
GSettings also notifies you about changes in writability of keys,
|
||||
with the #GSettings::writable-changed signal (and the
|
||||
#GSettings::writable-change-event signal).
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section><title>Change sets</title>
|
||||
<para>
|
||||
GConf has a a concept of a set of changes which can be applied or reverted
|
||||
at once: #GConfChangeSet (GConf doesn't actually apply changes atomically,
|
||||
which is one of its shortcomings).
|
||||
</para>
|
||||
<para>
|
||||
Instead of a separate object to represent a change set, GSettings has a
|
||||
'delayed-apply' mode, which can be turned on for a GSettings object by
|
||||
calling g_settings_delay(). In this mode, changes done to the GSettings
|
||||
object are not applied - they are still visible when calling g_settings_get()
|
||||
<emphasis>on the same object</emphasis>, but not to other GSettings instances
|
||||
or even other processes.
|
||||
</para>
|
||||
<para>
|
||||
To apply the pending changes all at once (GSettings <emphasis>does</emphasis>
|
||||
atomicity here), call g_settings_apply(). To revert the pending changes,
|
||||
call g_settings_revert() or just drop the reference to the #GSettings object.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Schema conversion</title>
|
||||
|
||||
<para>
|
||||
One possible pitfall in doing schema conversion is that the default
|
||||
values in GSettings schemas are parsed by the #GVariant parser.
|
||||
This means that strings need to include quotes in the XML. Also note
|
||||
that the types are now specified as #GVariant type strings.
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
<type>string</type>
|
||||
<default>rgb</default>
|
||||
]]>
|
||||
</programlisting>
|
||||
becomes
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
<key name="rgba-order" type="s">
|
||||
<default>'rgb'</default> <!-- note quotes -->
|
||||
</key>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Another possible complication is that GConf specifies full paths
|
||||
for each key, while a GSettings schema has a 'path' attribute that
|
||||
contains the prefix for all the keys in the schema, and individual
|
||||
keys just have a simple name. So
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
<key>/schemas/desktop/gnome/font_rendering/antialiasing</key>
|
||||
]]>
|
||||
</programlisting>
|
||||
becomes
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
<schema id="org.gnome.font" path="/desktop/gnome/font_rendering/">
|
||||
<key name="antialiasing" type="s">
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Default values can be localized in both GConf and GSettings schemas,
|
||||
but GSettings uses gettext for the localization, so
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
<key>/schemas/apps/my_app/font_size</key>
|
||||
<locale name="C">
|
||||
<default>18</default>
|
||||
</locale>
|
||||
<locale name="be">
|
||||
<default>24</default>
|
||||
</locale>
|
||||
</key>
|
||||
]]>
|
||||
</programlisting>
|
||||
becomes
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
<key name="font-size" type="i">
|
||||
<default l10n="messages" context="font_size">18</default>
|
||||
</key>
|
||||
]]>
|
||||
</programlisting>
|
||||
Note how we used the context attribute to add msgctxt - "18" is not a
|
||||
good string to look up in gettext by itself. Also note that the value
|
||||
24 is not present in the schema anymore. It has to be added to the gettext
|
||||
catalog for "be" instead.
|
||||
</para>
|
||||
<para>
|
||||
GSettings schemas have more stringent restrictions on key names
|
||||
than GConf. Key names in GSettings are restricted to at most 32
|
||||
characters, and must only consist of lowercase characters, numbers
|
||||
and dashes, with no consecutive dashes. The first character must
|
||||
not be a number or dash, and the last character cannot be '-'.
|
||||
The <link linkend="gschema-compile">gschema-compile</link> schema
|
||||
compiler has a <option>--allow-any-name</option> that lets you
|
||||
ignore these restrictions. Note that this option is only meant
|
||||
to ease the process of porting your application, allowing parts
|
||||
of your application to continue to access GConf and parts to use
|
||||
GSettings. By the time you have finished porting your application
|
||||
you must ensure that all key names are valid.
|
||||
</para>
|
||||
<para>
|
||||
GIO comes with a commandline tool
|
||||
<link linkend="gsettings-schema-convert">gsettings-schema-convert</link>
|
||||
that can help with the task of converting a GConf schema into
|
||||
an equivalent GSettings schema. The tool is not perfect and
|
||||
may need assistence in some cases.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section><title>Data conversion</title>
|
||||
<para>
|
||||
GConf comes with a utility called <command>gsettings-data-convert</command>,
|
||||
which is designed to help with the task of migrating user settings from
|
||||
GConf into GSetting. <command>gsettings-data-convert</command> can be run
|
||||
manually, but it is designed to be run automatically, every time a user
|
||||
logs in. It keeps track of the conversion that it has already done, and it
|
||||
is harmless to run it more than once.
|
||||
</para>
|
||||
<para>
|
||||
To make use of this utility, you must install a keyfile in the
|
||||
<filename>/usr/share/gsettings-data-convert</filename> which lists the GSettings
|
||||
and GConf paths to map to each other, for each schema that you want to migrate
|
||||
user data for.
|
||||
</para>
|
||||
<para>
|
||||
Here is an example:
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
[org.gnome.fonts]
|
||||
antialiasing = /desktop/gnome/font_rendering/antialiasing
|
||||
dpi = /desktop/gnome/font_rendering/dpi
|
||||
hinting = /desktop/gnome/font_rendering/hinting
|
||||
rgba-order = /desktop/gnome/font_rendering/rgba_order
|
||||
|
||||
[apps.myapp]
|
||||
some-odd-key1 = /apps/myapp/some_ODD-key1
|
||||
]]>
|
||||
</programlisting>
|
||||
The last key demonstrates that it may be necessary to modify the key name
|
||||
to comply with stricter GSettings key name rules. Of course, that means your
|
||||
application must make the corresponding adjustments.
|
||||
</para>
|
||||
<para>
|
||||
There are some limitations: <command>gsettings-data-convert</command> does not
|
||||
do any transformation of the values. And it does not handle complex GConf types
|
||||
other than lists of strings or integers.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
</part>
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<part>
|
||||
<title>GIO Overview</title>
|
||||
|
||||
<chapter>
|
||||
<chapter>
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
@@ -9,7 +9,7 @@
|
||||
at the right level in the library stack. The goal is to overcome the
|
||||
shortcomings of GnomeVFS and provide an API that is so good that
|
||||
developers prefer it over raw POSIX calls. Among other things
|
||||
that means using GObject. It also means not cloning the POSIX
|
||||
that means using GObject. It also means not cloning the POSIX
|
||||
API, but providing higher-level, document-centric interfaces.
|
||||
</para>
|
||||
|
||||
@@ -74,6 +74,13 @@
|
||||
<listitem><para>abstract type for file and application icons</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
There is a framework for storing and retrieving application settings:
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>GSettings</term>
|
||||
<listitem><para>stores and retrieves application settings</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
There is support for network programming, including name resolution, lowlevel socket
|
||||
APIs and highlevel client and server helper classes:
|
||||
<variablelist>
|
||||
@@ -99,9 +106,9 @@
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
Beyond these, GIO provides facilities for file monitoring,
|
||||
asynchronous I/O and filename completion. In addition to the
|
||||
interfaces, GIO provides implementations for the local case.
|
||||
Implementations for various network file systems are provided
|
||||
asynchronous I/O and filename completion. In addition to the
|
||||
interfaces, GIO provides implementations for the local case.
|
||||
Implementations for various network file systems are provided
|
||||
by the GVFS package as loadable modules.
|
||||
</para>
|
||||
|
||||
@@ -109,8 +116,8 @@
|
||||
Other design choices which consciously break with the GnomeVFS
|
||||
design are to move backends out-of-process, which minimizes the
|
||||
dependency bloat and makes the whole system more robust. The backends
|
||||
are not included in GIO, but in the separate GVFS package. The GVFS
|
||||
package also contains the GVFS daemon, which spawn further mount
|
||||
are not included in GIO, but in the separate GVFS package. The GVFS
|
||||
package also contains the GVFS daemon, which spawn further mount
|
||||
daemons for each individual connection.
|
||||
</para>
|
||||
|
||||
@@ -120,13 +127,13 @@
|
||||
</figure>
|
||||
|
||||
<para>
|
||||
The GIO model of I/O is stateful: if an application establishes e.g.
|
||||
a SFTP connection to a server, it becomes available to all applications
|
||||
in the session; the user does not have to enter his password over
|
||||
The GIO model of I/O is stateful: if an application establishes e.g.
|
||||
a SFTP connection to a server, it becomes available to all applications
|
||||
in the session; the user does not have to enter his password over
|
||||
and over again.
|
||||
</para>
|
||||
<para>
|
||||
One of the big advantages of putting the VFS in the GLib layer
|
||||
One of the big advantages of putting the VFS in the GLib layer
|
||||
is that GTK+ can directly use it, e.g. in the filechooser.
|
||||
</para>
|
||||
</chapter>
|
||||
@@ -138,16 +145,16 @@
|
||||
GIO comes with a <filename>gio-2.0.pc</filename> file that you
|
||||
should use together with <literal>pkg-config</literal> to obtain
|
||||
the necessary information about header files and libraries. See
|
||||
the <literal>pkg-config</literal> man page or the GLib documentation
|
||||
for more information on how to use <literal>pkg-config</literal>
|
||||
the <literal>pkg-config</literal> man page or the GLib documentation
|
||||
for more information on how to use <literal>pkg-config</literal>
|
||||
to compile your application.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you are using GIO on UNIX-like systems, you may want to use
|
||||
UNIX-specific GIO interfaces such as #GUnixInputStream,
|
||||
#GUnixOutputStream, #GUnixMount or #GDesktopAppInfo.
|
||||
To do so, use the <filename>gio-unix-2.0.pc</filename> file
|
||||
UNIX-specific GIO interfaces such as #GUnixInputStream,
|
||||
#GUnixOutputStream, #GUnixMount or #GDesktopAppInfo.
|
||||
To do so, use the <filename>gio-unix-2.0.pc</filename> file
|
||||
instead of <filename>gio-2.0.pc</filename>
|
||||
</para>
|
||||
</chapter>
|
||||
@@ -164,7 +171,7 @@
|
||||
<title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
|
||||
|
||||
<para>
|
||||
GIO uses these environment variables to locate MIME information.
|
||||
GIO uses these environment variables to locate MIME information.
|
||||
For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
|
||||
and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
|
||||
</para>
|
||||
@@ -188,19 +195,19 @@
|
||||
<title><envar>GIO_USE_VFS</envar></title>
|
||||
|
||||
<para>
|
||||
This environment variable can be set to the name of a #GVfs
|
||||
This environment variable can be set to the name of a #GVfs
|
||||
implementation to override the default for debugging purposes.
|
||||
The #GVfs implementation for local files that is included in GIO
|
||||
has the name "local", the implementation in the gvfs module has
|
||||
the name "gvfs".
|
||||
The #GVfs implementation for local files that is included in GIO
|
||||
has the name "local", the implementation in the gvfs module has
|
||||
the name "gvfs".
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
<formalpara>
|
||||
<title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
|
||||
|
||||
|
||||
<para>
|
||||
This variable can be set to the name of a #GVolumeMonitor
|
||||
This variable can be set to the name of a #GVolumeMonitor
|
||||
implementation to override the default for debugging purposes.
|
||||
The #GVolumeMonitor implementation for local files that is included
|
||||
in GIO has the name "unix", the hal-based implementation in the
|
||||
@@ -216,7 +223,7 @@
|
||||
implementation to override the default for debugging purposes.
|
||||
GIO does not include a #GDesktopAppInfoLookup implementation,
|
||||
the GConf-based implementation in the gvfs module has the name
|
||||
"gconf".
|
||||
"gconf".
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
@@ -225,7 +232,7 @@
|
||||
|
||||
<para>
|
||||
When this environment variable is set and GIO has been built
|
||||
with inotify support, a dump of diagnostic inotify information
|
||||
with inotify support, a dump of diagnostic inotify information
|
||||
will be written every 20 seconds to a file named
|
||||
<filename>/tmp/gvfsdid.<replaceable>pid</replaceable></filename>.
|
||||
</para>
|
||||
@@ -235,12 +242,43 @@
|
||||
<title><envar>GIO_EXTRA_MODULES</envar></title>
|
||||
|
||||
<para>
|
||||
When this environment variable is set to a path, or a set of
|
||||
paths separated by a colon, GIO will attempt to load
|
||||
modules from within the path.
|
||||
When this environment variable is set to a path, or a set of
|
||||
paths separated by a colon, GIO will attempt to load
|
||||
modules from within the path.
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
<formalpara>
|
||||
<title><envar>GSETTINGS_BACKEND</envar></title>
|
||||
|
||||
<para>
|
||||
This variable can be set to the name of a #GSettingsBackend
|
||||
implementation to override the default for debugging purposes.
|
||||
The keyfile-based implementation that is included in GIO has
|
||||
the name "keyfile", the one in dconf has the name "dconf-settings".
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
<formalpara>
|
||||
<title><envar>GSETTINGS_SCHEMA_DIR</envar></title>
|
||||
|
||||
<para>
|
||||
This variable can be set to the name of a directory that is
|
||||
considered in addition to the <filename>glib-2.0/schemas</filename>
|
||||
subdirectories of the XDG system data dirs when looking
|
||||
for compiled schemas for #GSettings.
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
<formalpara>
|
||||
<title><envar>GSETTINGS_KEYFILE_BACKEND_STORE</envar></title>
|
||||
|
||||
<para>
|
||||
This variable can be set to the path where the keyfile #GSettings
|
||||
backend stores its data. By default, the keyfile is stored in
|
||||
<filename>$HOME/.config/gsettings/store</filename>.
|
||||
</para>
|
||||
</formalpara>
|
||||
</chapter>
|
||||
|
||||
<chapter id="extending-gio">
|
||||
@@ -249,7 +287,7 @@
|
||||
<para>
|
||||
A lot of the functionality that is accessible through GIO
|
||||
is implemented in loadable modules, and modules provide a convenient
|
||||
way to extend GIO. In addition to the #GIOModule API which supports
|
||||
way to extend GIO. In addition to the #GIOModule API which supports
|
||||
writing such modules, GIO has a mechanism to define extension points,
|
||||
and register implementations thereof, see #GIOExtensionPoint.
|
||||
</para>
|
||||
@@ -297,8 +335,8 @@
|
||||
is_supported() vfunc in #GVolumeMonitorClass.
|
||||
</para>
|
||||
<para>
|
||||
GIO implements this extension point for local mounts,
|
||||
gvfs contains a hal-based implementation.
|
||||
GIO implements this extension point for local mounts,
|
||||
gvfs contains a hal-based implementation.
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
@@ -306,9 +344,9 @@
|
||||
<title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
|
||||
|
||||
<para>
|
||||
Allows to override the file monitor implementation for
|
||||
local files. Implementations of this extension point must
|
||||
be derived from #GLocalFileMonitor. GIO uses the implementation
|
||||
Allows to override the file monitor implementation for
|
||||
local files. Implementations of this extension point must
|
||||
be derived from #GLocalFileMonitor. GIO uses the implementation
|
||||
with the highest priority that is supported, as determined by the
|
||||
is_supported() vfunc in #GLocalFileMonitorClass.
|
||||
</para>
|
||||
@@ -322,8 +360,8 @@
|
||||
<title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title>
|
||||
|
||||
<para>
|
||||
Allows to override the directory monitor implementation for
|
||||
local files. Implementations of this extension point must be
|
||||
Allows to override the directory monitor implementation for
|
||||
local files. Implementations of this extension point must be
|
||||
derived from #GLocalDirectoryMonitor. GIO uses the implementation
|
||||
with the highest priority that is supported, as determined by the
|
||||
is_supported() vfunc in #GLocalDirectoryMonitorClass.
|
||||
@@ -339,14 +377,26 @@
|
||||
|
||||
<para>
|
||||
Unix-only. Allows to provide a way to associate default handlers
|
||||
with URI schemes. Implementations of this extension point must
|
||||
implement the #GDesktopAppInfoLookup interface. GIO uses the
|
||||
with URI schemes. Implementations of this extension point must
|
||||
implement the #GDesktopAppInfoLookup interface. GIO uses the
|
||||
implementation with the highest priority.
|
||||
</para>
|
||||
<para>
|
||||
gvfs contains a GConf-based implementation that uses the
|
||||
gvfs contains a GConf-based implementation that uses the
|
||||
same GConf keys as gnome-vfs.
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
<formalpara>
|
||||
<title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
|
||||
|
||||
<para>
|
||||
Allows to provide an alternative storage for #GSettings.
|
||||
Implementations of this extension point must derive from the
|
||||
#GSettingsBackend type. GIO contains a keyfile-based
|
||||
implementation of this extension point, another one is provided
|
||||
by dconf.
|
||||
</para>
|
||||
</formalpara>
|
||||
</chapter>
|
||||
</part>
|
||||
|
||||
Reference in New Issue
Block a user