1<?xml version="1.0" encoding="UTF-8" ?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
3
4<appendix id='Resource_Configuration_Management'>
5<title>Resource Configuration Management</title>
6<para>
7Setting and changing resources in X applications can be difficult for
8both the application programmer and the end user.  <emphasis role='strong'>Resource
9Configuration Management (RCM)</emphasis> addresses this problem by changing
10the <function>X Intrinsics</function> to immediately modify a resource for a
11specified widget and each child widget in the hierarchy.
12In this context, immediate means: no sourcing of a resource
13file is required; the application does not need to be restarted for the
14new resource values to take effect; and the change
15occurs immediately.
16</para>
17
18<para>
19The main difference between <function>RCM</function> and the <function>Editres</function>
20protocol is that the <function>RCM</function>
21customizing hooks reside in the <function>Intrinsics</function> and thus are linked with
22other toolkits such as Motif and the Athena widgets.  However, the
23<function>EditRes</function> protocol requires the application to link with the
24<function>EditRes</function>
25routines in the Xmu library and Xmu is not used by all applications that
26use Motif.  Also, the <function>EditRes</function> protocol uses ClientMessage,
27whereas the
28<function>RCM</function> <function>Intrinsics</function> hooks use <function>PropertyNotify</function> events.
29</para>
30
31<para>
32X Properties and the <function>PropertyNotify</function> events are used
33to implement <function>RCM</function> and
34allow on-the-fly resource customization.  When the X Toolkit is
35initialized, two atoms are interned with the strings
36<emphasis remap='I'>Custom Init</emphasis> and
37<emphasis remap='I'>Custom Data</emphasis>.  Both
38<function>_XtCreatePopupShell</function>
39and
40<function>_XtAppCreateShell</function>
41register a <function>PropertyNotify</function> event handler to handle these properties.
42</para>
43
44<para>
45A customization tool uses the <emphasis remap='I'>Custom Init</emphasis> property to <emphasis remap='I'>ping</emphasis> an
46application to get the application's toplevel window.  When the
47application's property notify event handler is invoked, the handler
48deletes the property.  No data is transferred in this property.
49</para>
50
51<para>
52A customization tool uses the <emphasis remap='I'>Custom Data</emphasis> property to tell an
53application that it should change a resource's value.  The data in
54the property contains the length of the resource name (the number
55of bytes in the resource name), the resource name and the new
56value for the resource.  This property's type is <function>XA_STRING</function> and
57the format of the string is:
58</para>
59<orderedlist>
60  <listitem>
61    <para>
62The length of the resource name (the number of bytes in
63the resource name)
64    </para>
65  </listitem>
66  <listitem>
67    <para>
68One space character
69    </para>
70  </listitem>
71  <listitem>
72    <para>
73The resource name
74    </para>
75  </listitem>
76  <listitem>
77    <para>
78One space character
79    </para>
80  </listitem>
81  <listitem>
82    <para>
83The resource value
84    </para>
85  </listitem>
86</orderedlist>
87<para>
88When setting the application's resource, the event handler calls
89functions to walk the application's widget tree, determining which
90widgets are affected by the resource string, and then applying the value
91with
92<xref linkend='XtSetValues' xrefstyle='select: title'/>.
93As the widget tree is recursively descended, at
94each level in the widget tree a resource part is tested for a match.
95When the entire resource string has been matched, the value is applied
96to the widget or widgets.
97</para>
98
99<para>
100Before a value is set on a widget, it is first determined if the last
101part of the resource is a valid resource for that widget.  It must also
102add the resource to the application's resource database and then query
103it using specific resource strings that is builds from the widget
104information.
105</para>
106</appendix>
107