1<chapter id='Creating_New_Widgets_Subclassing'>
2<title>Creating New Widgets (Subclassing)</title>
3<para>
4Although the task of creating a new widget may at first appear a little
5daunting, there is a basic simple pattern that all widgets follow.  The
6Athena Widget library contains a special widget called the
7<emphasis remap='I'>Template</emphasis> widget that is intended to assist
8the novice widget programmer in writing a custom widget.
9</para>
10<para>
11Reasons for wishing to write a custom widget include:
12</para>
13<itemizedlist>
14  <listitem>
15    <para>
16Providing a graphical interface not currently supported by any existing
17widget set.
18    </para>
19  </listitem>
20  <listitem>
21    <para>
22Convenient access to resource management procedures to obtain fonts,
23colors, etc., even if user customization is not desired.
24    </para>
25  </listitem>
26  <listitem>
27    <para>
28Convenient access to user input dispatch and translation management procedures.
29    </para>
30  </listitem>
31  <listitem>
32    <para>
33Access to callback mechanism for building higher-level application libraries.
34    </para>
35  </listitem>
36  <listitem>
37    <para>
38Customizing the interface or behavior of an existing widget to suit a
39special application need.
40    </para>
41  </listitem>
42  <listitem>
43    <para>
44Desire to allow user customization of resources such as fonts, colors,
45etc., or to allow convenient re-binding of keys and buttons to internal
46functions.
47    </para>
48  </listitem>
49  <listitem>
50    <para>
51Converting a non-Toolkit application to use the Toolkit.
52    </para>
53  </listitem>
54</itemizedlist>
55
56<para>
57In each of these cases, the operation needed to create a new widget is
58to "subclass" an existing one.  If the desired semantics of the new
59widget are similar to an existing one, then the implementation of the
60existing widget should be examined to see how much work would be
61required to create a subclass that will then be
62able to share the existing class methods.  Much time will be saved in
63writing the new widget if an existing widget class Expose, Resize and/or
64GeometryManager method can be used by the subclass.
65</para>
66<para>
67Note that some trivial uses of a <quote>bare-bones</quote> widget may be achieved by
68simply creating an instance of the Core
69widget.  The class variable to use when creating a Core widget is
70<function>widgetClass</function>.
71The geometry of the Core widget is determined entirely by the parent
72widget.
73</para>
74<para>
75It is very often the case than an application will have a special need
76for a certain set of functions and that many copies of these functions
77will be needed.  For example, when converting an older application to use
78the Toolkit, it may be desirable to have a "Window Widget" class that
79might have the following semantics:
80</para>
81<itemizedlist>
82  <listitem>
83    <para>
84Allocate 2 drawing colors in addition to a background color.
85    </para>
86  </listitem>
87  <listitem>
88    <para>
89Allocate a text font.
90    </para>
91  </listitem>
92  <listitem>
93    <para>
94Execute an application-supplied function to handle exposure events.
95    </para>
96  </listitem>
97  <listitem>
98    <para>
99Execute an application-supplied function to handle user input events.
100    </para>
101  </listitem>
102</itemizedlist>
103<para>
104It is obvious that a completely general-purpose WindowWidgetClass could
105be constructed that would export all class methods as callbacks lists,
106but such a widget would be very large and would have to choose some
107arbitrary number of resources such as colors to allocate.  An application
108that used many instances of the general-purpose widget would therefore
109un-necessarily waste many resources.
110</para>
111<para>
112In this section, an outline will be given of the procedure to follow to
113construct a special-purpose widget to address the items listed above.
114The reader should refer to the appropriate sections of the
115<olink targetdoc='intrinsics' targetptr='intrinsics'
116><citetitle>X Toolkit Intrinsics - C Language Interface</citetitle></olink>
117for complete details of the material outlined here.
118<olink targetdoc='intrinsics' targetptr='Widgets'
119>Section 1.4 of the <citetitle>Intrinsics</citetitle></olink>
120should be read in
121conjunction with this section.
122</para>
123<para>
124All Athena widgets have three separate files associated with them:
125</para>
126<itemizedlist>
127  <listitem>
128    <para>
129A "public" header file containing declarations needed by applications programmers
130    </para>
131  </listitem>
132  <listitem>
133    <para>
134A "private" header file containing additional declarations needed by the
135widget and any subclasses
136    </para>
137  </listitem>
138  <listitem>
139    <para>
140A source code file containing the implementation of the widget
141    </para>
142  </listitem>
143</itemizedlist>
144
145<para>
146This separation of functions into three files is suggested for all
147widgets, but nothing in the Toolkit actually requires this format.  In
148particular, a private widget created for a single application may easily
149combine the "public" and "private" header files into a single file, or
150merge the contents into another application header file.  Similarly, the
151widget implementation can be merged into other application code.
152</para>
153
154<para>
155In the following example, the public header file
156<filename class="headerfile">&lt;X11/Xaw/Template.h&gt;</filename>,
157the private header file
158<filename class="headerfile">&lt;X11/Xaw/TemplateP.h&gt;</filename>
159and the source code file
160<filename class="headerfile">&lt;X11/Xaw/Template.c&gt;</filename>
161will be modified to produce the "WindowWidget" described above.
162In each case, the files have been designed so that a global string
163replacement of "Template" and "template"
164with the name of your new widget, using
165the appropriate case, can be done.
166</para>
167<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="Template_public_header_file.xml"/>
168<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="Template_private_header_file.xml"/>
169<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="Template_widget_source_file.xml"/>
170</chapter>
171