summaryrefslogtreecommitdiffstats
path: root/xsettings
diff options
context:
space:
mode:
Diffstat (limited to 'xsettings')
-rw-r--r--xsettings/ChangeLog5
-rw-r--r--xsettings/xsettings.xml371
2 files changed, 376 insertions, 0 deletions
diff --git a/xsettings/ChangeLog b/xsettings/ChangeLog
index 141a909..2bcc683 100644
--- a/xsettings/ChangeLog
+++ b/xsettings/ChangeLog
@@ -1,3 +1,8 @@
+Wed Oct 9 15:32:20 2002 Owen Taylor <otaylor@redhat.com>
+
+ * xsettings.xml: Add the spec (prior to converting
+ to DocBook XML)
+
Tue Oct 8 19:19:37 2002 Owen Taylor <otaylor@redhat.com>
* xsettings-common.c (xsettings_setting_free): Fre
diff --git a/xsettings/xsettings.xml b/xsettings/xsettings.xml
new file mode 100644
index 0000000..81e901b
--- /dev/null
+++ b/xsettings/xsettings.xml
@@ -0,0 +1,371 @@
+<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+]>
+<article id="index">
+ <artheader>
+ <title>XSETTINGS - cross toolkit configuration proposal</title>
+ <releaseinfo>Version 0.5</releaseinfo>
+ <date>19 March 2001</date>
+ <authorgroup>
+ <author>
+ <firstname>Owen</firstname>
+ <surname>Taylor</surname>
+ <affiliation>
+ <address>
+ <email>otaylor@redhat.com</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+ </artheader>
+
+ <sect1 id="goals">
+ <title>Goals</title>
+ <para>
+ The intent of this specification is to specify a mechanism to
+ allow the configuration of settings such as double click timeout,
+ drag-and-drop threshold, and default foreground and background colors
+ for all applications running within a desktop. The mechanism should:
+ </para>
+ <simplelist>
+ <member>allow for instant updates to be propagated across all
+ applications at runtime</member>
+ <member>perform well, even for remote applications.</member>
+ </simplelist>
+ <para>
+ It is not intended:
+ </para>
+ <simplelist>
+ <member>for the storage of application-specific data</member>
+ <member>to be able to store large amounts of data</member>
+ <member>to store complex data types (other than as
+ strings)</member>
+ </simplelist>
+ </sect1>
+ <sect1 id="existing">
+ <title>Existing Systems</title>
+ <para>
+ The existing systems in this area are the Xrm database, and various
+ other configuration database systems, mostly specific to particular
+ desktops. (The kde configuration system, gnome-config, GConf,
+ libproplist, etc.)
+ </para>
+ <para>
+ The Xrm database is tempting to use for this purpose since it is
+ very well established and has a universally deployed existing
+ implementation. However, it has various defects, that make it
+ not suitable for this purpose.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The Xrm database merges information from various sources - the
+ ~/.Xdefaults file on the root window, and a property on the root
+ window. This means that to programatically configure the Xrm
+ database in response to a GUI config tool is difficult and
+ unreliable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Xrm database was not designed for on-the-fly changing of
+ settings.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Xrm database stores all information in a single text
+ property on the root window. This makes it difficult to
+ determine what settings have changed; it is necessary to parse
+ the property and do string comparisons.
+ </para>
+ <para>
+ Additionally, most systems have a large amount of application
+ specific information in the Xrm database, which further slows
+ down notification of changes.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Other configuration databases are more designed for this
+ task. However, they are sophisticated systems that are not easily
+ reimplementable. Also, picking one would mean difficulties
+ integrating with other desktops that use different systems.
+ </para>
+ <para>
+ It is our contention that a system designed specifically for
+ configuration of a small number of settings being changed at
+ runtime can, compared to a more general existing system:
+ </para>
+ <simplelist>
+ <member>Be easier to bridge onto each systems native configuration
+ mechanism.</member>
+ <member>Be easier to implement in whatever language/library combination
+ people want to use.</member>
+ <member>Be more efficient.</member>
+ </simplelist>
+ </sect1>
+ <sect1 id="client-behavior">
+ <title>Client behavior</title>
+ <para>
+ On startup, each client that should identify the settings window by
+ calling XGetSelectionOwner() for the _XSETTINGS_S[N] selection and select
+ for notification on the settings window by calling XSelectInput()
+ with a mask of StructureNotifyMask|PropertyChangeMask.
+ </para>
+ <para>
+ To prevent race conditions a client MUST grab the
+ server while performing these operations using XGrabServer().
+ </para>
+ <para>
+ If there is no owner of the _XSETTINGS_S[N] selection, the client can
+ determine when an owner is established by listening for client
+ messages sent to root window of the screen with type MANAGER. (See
+ section 2.8, Manager Selections of the ICCCM.) The format of this
+ message is:
+ </para>
+ <programlisting>
+ event-mask: StructureNotify
+ event: ClientMessage
+ type: MANAGER
+ format: 32
+ data[0]: timestamp
+ data[1]: _XSETTINGS_S[N] (atom)
+ data[2]: New owner of the selection
+ data[3]: 0 (reserved)
+ </programlisting>
+ <para>
+ The client can then proceed to read contents of the _XSETTINGS_SETTINGS
+ property from the settings window and interpret according to
+ the information in the "_XSETTINGS_SETTINGS Format" section of this
+ document.
+ </para>
+ <para>
+ Clients must trap X errors when reading the _XSETTING_SETTINGS property
+ because it is possible that the selection window may be destroyed
+ at any time.
+ </para>
+ <para>
+ When the client is notified that the settings window has been
+ destroyed or discovers that the selection window has been destroyed,
+ it should reset all settings to their default values and then proceed
+ as on initial startup. [ See rational section ]
+ </para>
+ <para>
+ When a client receives a PropertyChangeNotify event for the window
+ it should reread the _XSETTING_SETTINGS property. It can use
+ the 'serial' field to tell what fields have been changed. The
+ client must parse the entire property and read in all new values
+ before taking action on changed settings such as notifying listeners
+ for those settings to avoid using a mix of old and new data.
+ </para>
+ </sect1>
+ <sect1 id="format">
+ <title>_XSETTINGS_SETTINGS Format</title>
+ <para>
+ The _XSETTINGS_SETTINGS property is of form 8 and type _XSETTINGS_SETTINGS.
+The contents are a
+ </para>
+ <programlisting>
+ 1 CARD8 byte-order
+ 3 unused
+ 4 CARD32 SERIAL
+ 4 CARD32 N_SETTINGS
+ </programlisting>
+ <para>
+Followed by N_SETTINGS settings records, which have a header:
+ </para>
+ <programlisting>
+ 1 SETTING_TYPE type
+ 1 unused
+ 2 n name-len
+ n STRING8 name
+ P unused, p=pad(n)
+ 4 CARD32 last-change-serial
+ </programlisting>
+ <para>
+Where SETTING_TYPE is
+ </para>
+ <programlisting>
+ 0 XSettingsTypeInteger
+ 1 XSettingsTypeString
+ 2 XSettingsTypeColor
+ </programlisting>
+ <para>
+followed by the body. If TYPE = XSettingsTypeString the body is:
+ </para>
+ <programlisting>
+ 4 n value-len
+ n STRING8 value
+ P unused, p=pad(n)
+ </programlisting>
+
+ <para>
+If TYPE == XSettingsTypeInteger, then the body is:
+ </para>
+ <programlisting>
+ 4 INT32 value
+ </programlisting>
+
+ <para>
+ If TYPE == XSettingsTypeColor, then the body is:
+ </para>
+ <programlisting>
+ 2 CARD16 red
+ 2 CARD16 blue
+ 2 CARD16 green
+ 2 CARD16 alpha
+ </programlisting>
+ <para>
+If the setting does not need the alpha field, it should
+be set to 65535.
+ </para>
+ <para>
+ Setting names must be confined to the ascii characters:
+ </para>
+ <programlisting>
+ 'A'-'Z' 'a'-'z' '0'-'9' '_' and '/'
+ </programlisting>
+ <para>
+ With the additional restrictions that '/' cannot appear in
+ the leading or trailing position, that two occurences of
+ '/' cannot be consecutive, and that the first character
+ of the name, and and the first character after a slash
+ cannot be one of '0'-'9'. Names may not be empty.
+ </para>
+ <para>
+ So,
+ </para>
+ <programlisting>
+ "GTK/colors/background0"
+ "_background"
+ "_111"
+ </programlisting>
+ <para>
+ are legitimate names, while
+ </para>
+ <programlisting>
+ "/"
+ "_background/"
+ "GTK//colors"
+ ""
+ </programlisting>
+ <para>
+ Are not legitimate names.
+ </para>
+ <para>
+ The names, types, contents, and default values of standard settings
+ will be separately agreed upon.
+ </para>
+
+ <para>
+ Names beginning with 'Net/' and case variants of that string are
+ reserved and must not be used without prior agreement.
+ </para>
+ <para>
+ The 'serial' field and and the 'last-change-serial' field of the each
+ settings record can be used to tell which settings have changed since
+ the last time a client retrieved the _XSETTINGS_SETTINGS property. Each
+ time the client retrieves the contents of the _XSETTINGS_SETTINGS
+ property it should store the contents of the 'serial' field. When
+ it next retrieves the property, any settings whose 'last-change-serial'
+ is greater than the stored value.
+ </para>
+
+ <para>
+ (Careful clients will make provisions for wrap-around of the serial
+ field. This is, however, not expected to happen in practice.)
+ </para>
+ </sect1>
+ <sect1 id="manager-behavior">
+ <title>Settings Manager behavior</title>
+ <para>
+ The _XSETTING_S[N] selection is managed as a manager selection
+ according to section 2.8 of the ICCCM and the handling of the
+ selections window, the _XSETTING_S[N] window and MANAGER client
+ messages must conform to that specification.
+ </para>
+ <para>
+ The settings manager changes the contents of the _XSETTINGS_SETTINGS
+ property of the root window whenever the source it derives them
+ from changes, taking care to increment the 'serial' field at each
+ increment and set the 'last-change-serial' fields appropriately.
+ </para>
+ </sect1>
+ <appendix id="rational">
+ <title>Rational and Discussion</title>
+ <para>
+ The reasons why an existing configuration mechanism, and in particular,
+ the Xrm database, was not used is discussed above. Various other
+ design decisions are discussed below:
+ </para>
+ <formalpara>
+ <title>Why aren't the contents of the property stored in XML?</title>
+ <para>
+ The data format is designed to be space efficient and to be easily
+ and efficiently parsed with minimal code. These are not things
+ XML does well. Flexibility of structure, things that XML
+ does well are not needed here. If needed, XML can be used for
+ the contents of individual settings.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Why is the settings property screen specific?</title>
+ <para>
+ While most settings are expected to be shared across all screens
+ of a display, some settings, such as font sizes will be screen
+ specific, and it is considered easier to let the settings manager
+ propagate shared resources across screens then to have both
+ screen-specific and screen-independent resources.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Why does there need to be a "settings manager" process
+ running?</title>
+ <para>
+ Having a process always present as the owner of the _XSETTING
+ selection ensures that there are no race conditions and is
+ simpler than trying to create a locking mechanism that can
+ work without a persistant process. It is also expected that to
+ properly handle notification of changes to the stored
+ properties most desktops will want a process running to watch
+ for changes in any case. In cases of tight resource usage, the
+ settings manager can be combined with some other function,
+ such as the window manager or session manager.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Why use a single property for all settings?</title>
+ <para>
+ Using a single property has several advantages. First, retrieving
+ all settings takes only a single round-trip to the server instead
+ of a round-trip for each settings. Second, it means that when
+ multiple settings can be changed at once, only a single notification
+ is received by clients, and clients will see interrelated properties
+ changed in an atomic fashion.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Why is the _XSETTINGS_SETTINGS property stored in the endianess
+ of the manager instead of a neutral endianness?</title>
+ <para>
+ This conforms to the way many other X mechanisms work. The main reason
+ for doing it this way is to save conversions for the common case when
+ the client and manager are on machines of the same endianness.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>When the settings manager exits, why should clients reset the
+ values to the default settings instead of keeping the current
+ settings?</title>
+ <para>
+ Resetting the settings to the default values is preferred to
+ maintaining the current values because it makes sure that all programs
+ on the desktop have consistent values for settings whether they were
+ started before or after the settings manager exited. It is not
+ expected that changes in the current settings manager will occur
+ very often.
+ </para>
+ </formalpara>
+ </appendix>
+</article>
+