specs/CH7.xml

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