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