1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
|
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<article id="index">
<articleinfo>
<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>
</articleinfo>
<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 green
2 CARD16 blue
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>
|