specs/Template.xml

   1 <sect2 id="Public_Header_File">
   2 <title>Public Header File</title>
   3 <para>
   4 The public header file contains declarations that will be required by any
   5 application module that needs to refer to the widget; whether to create
   6 an instance of the class, to perform an
   7 <xref linkend='XtSetValues' xrefstyle='select: title'/>
   8 operation, or to call a public routine implemented by the widget class.
   9 </para>
  10 <para>
  11 <!-- .LP -->
  12 The contents of the Template public header file,
  13 <function>&lt; X11/Xaw/Template.h &gt;, </function>
  14 are:
  15 </para>
  16 <literallayout class="monospaced">
  17 ..
  18 <!-- .CB -->
  19 <!-- .\".so ../../lib/Xaw/Template.h -->
  20 /* Copyright (c) X Consortium 1987, 1988 */
  21
  22 #ifndef _Template_h
  23 #define _Template_h
  24
  25 /****************************************************************
  26  *
  27  * Template widget
  28  *
  29  ****************************************************************/
  30
  31 /* Resources:
  32
  33  Name   Class           RepType Default Value
  34  ----           -----           ------- -------------
  35  background     Background              Pixel   XtDefaultBackground
  36  border BorderColor             Pixel   XtDefaultForeground
  37  borderWidth    BorderWidth             Dimension       1
  38  destroyCallback        Callback                Pointer NULL
  39  height Height          Dimension       0
  40  mappedWhenManaged      MappedWhenManaged       Boolean True
  41  sensitive      Sensitive               Boolean True
  42  width  Width           Dimension       0
  43  x              Position                Position        0
  44  y              Position                Position        0
  45
  46 */
  47
  48 /* define any special resource names here that are not in &lt;X11/StringDefs.h&gt; */
  49
  50 #define XtNtemplateResource "templateResource"
  51
  52 #define XtCTemplateResource "TemplateResource"
  53
  54 /* declare specific TemplateWidget class and instance datatypes */
  55
  56 typedef struct _TemplateClassRec*       TemplateWidgetClass;
  57 typedef struct _TemplateRec*    TemplateWidget;
  58
  59 /* declare the class constant */
  60
  61 extern WidgetClass templateWidgetClass;
  62
  63 #endif /* _Template_h */
  64 <!-- .CE -->
  65 </literallayout>
  66 <para>
  67 <!-- .LP -->
  68 <!-- .sp -->
  69 You will notice that most of this file is documentation.  The crucial
  70 parts are the last 8 lines where macros for any private resource names
  71 and classes are defined and where the widget class datatypes and class
  72 record pointer are declared.
  73 </para>
  74 <para>
  75 <!-- .LP -->
  76 For the "WindowWidget", we want 2 drawing colors, a callback list for
  77 user input and an
  78 <function>exposeCallback</function> callback list, and we will declare three
  79 convenience procedures, so we need to add
  80 </para>
  81 <literallayout class="monospaced">
  82 <!-- .LP -->
  83 <!-- .sp -->
  84 <!-- .CB -->
  85 /* Resources:
  86         ...
  87  callback       Callback        Callback        NULL
  88  drawingColor1  Color   Pixel           XtDefaultForeground
  89  drawingColor2  Color   Pixel           XtDefaultForeground
  90  exposeCallback Callback        Callback        NULL
  91  font           Font    XFontStruct*    XtDefaultFont
  92         ...
  93  */
  94
  95 #define XtNdrawingColor1 "drawingColor1"
  96 #define XtNdrawingColor2 "drawingColor2"
  97 #define XtNexposeCallback "exposeCallback"
  98
  99 extern Pixel WindowColor1(\|/* Widget */\|);
 100 extern Pixel WindowColor2(\|/* Widget */\|);
 101 extern Font\ \ WindowFont(\|/* Widget */\|);
 102 <!-- .CE -->
 103 </literallayout>
 104 <para>
 105 <!-- .LP -->
 106 Note that we have chosen to call the input callback list by the generic
 107 name, <function>callback</function>, rather than a specific name.  If widgets that define
 108 a single user-input action all choose the same resource name then there
 109 is greater possibility for an application to switch between widgets of
 110 different types.
 111 </para>
 112 </sect2>
 113 <sect2 id="Private_Header_File">
 114 <title>Private Header File</title>
 115 <para>
 116 <!-- .LP -->
 117 The private header file contains the complete declaration of the class
 118 and instance structures for the widget and any additional private data
 119 that will be required by anticipated subclasses of the widget.
 120 Information in the private header file is normally hidden from the
 121 application and is designed to be accessed only through other public
 122 procedures; e.g.
 123 <function>XtSetValues .</function>
 124 </para>
 125 <para>
 126 <!-- .LP -->
 127 The contents of the Template private header file,
 128 <function>&lt; X11/Xaw/TemplateP.h &gt;, </function>
 129 are:
 130 </para>
 131 <!-- .CB -->
 132 <!-- .\".so ../../lib/Xaw/TemplateP.h -->
 133 <literallayout class="monospaced">
 134 /* Copyright (c) X Consortium 1987, 1988
 135  */
 136
 137 #ifndef _TemplateP_h
 138 #define _TemplateP_h
 139
 140 #include &lt;X11/Xaw/Template.h&gt;
 141 /* include superclass private header file */
 142 #include &lt;X11/CoreP.h&gt;
 143
 144 /* define unique representation types not found in &lt;X11/StringDefs.h&gt; */
 145
 146 #define XtRTemplateResource "TemplateResource"
 147
 148 typedef struct {
 149         int empty;
 150 } TemplateClassPart;
 151
 152 typedef struct _TemplateClassRec {
 153         CoreClassPart   core_class;
 154         TemplateClassPart       template_class;
 155 } TemplateClassRec;
 156
 157 extern TemplateClassRec templateClassRec;
 158
 159 typedef struct {
 160         /* resources */
 161         char* resource;
 162         /* private state */
 163 } TemplatePart;
 164
 165 typedef struct _TemplateRec {
 166         CorePart        core;
 167         TemplatePart    template;
 168 } TemplateRec;
 169
 170 #endif /* _TemplateP_h */
 171 <!-- .CE -->
 172 </literallayout>
 173 <para>
 174 The private header file includes the private header file of its
 175 superclass, thereby exposing the entire internal structure of the widget.
 176 It may not always be advantageous to do this; your own project
 177 development style will dictate the appropriate level of detail to expose
 178 in each module.
 179 </para>
 180 <para>
 181 The "WindowWidget" needs to declare two fields in its instance structure to
 182 hold the drawing colors, a resource field for the font and a field for the
 183 expose and user input callback lists:
 184 </para>
 185
 186 <literallayout class="monospaced">
 187 typedef struct {
 188         /* resources */
 189         Pixel color_1;
 190         Pixel color_2;
 191         XFontStruct* font;
 192         XtCallbackList expose_callback;
 193         XtCallbackList input_callback;
 194         /* private state */
 195         /* (none) */
 196 } WindowPart;
 197 </literallayout>
 198
 199 </sect2>
 200 <sect2 id="Widget_Source_File">
 201 <title>Widget Source File</title>
 202 <para>
 203 <!-- .LP -->
 204 The source code file implements the widget class itself.  The unique
 205 part of this file is the declaration and initialization of the
 206 widget class record structure and the declaration of all resources and
 207 action routines added by the widget class.
 208 </para>
 209 <para>
 210 <!-- .LP -->
 211 The contents of the Template implementation file,
 212 <function>&lt; X11/Xaw/Template.c &gt;,</function>
 213 are:
 214 </para>
 215 <!-- .CB -->
 216 <!-- .\".so ../../lib/Xaw/Template.c -->
 217 <literallayout class="monospaced">
 218 /* Copyright (c) X Consortium 1987, 1988
 219  */
 220
 221 #include &lt;X11/IntrinsicP.h&gt;
 222 #include &lt;X11/StringDefs.h&gt;
 223 #include "TemplateP.h"
 224
 225 static XtResource resources[] = {
 226 #define offset(field) XtOffsetOf(TemplateRec, template.field)
 227         /* {name, class, type, size, offset, default_type, default_addr}, */
 228     { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource,
 229           sizeof(char*), offset(resource), XtRString, (XtPointer) "default" },
 230 #undef offset
 231 };
 232
 233 static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */);
 234
 235 static XtActionsRec actions[] =
 236 {
 237         /* {name,       procedure}, */
 238         {"template",    TemplateAction},
 239 };
 240
 241 static char translations[] =
 242 "       &lt;Key&gt;:    template(\|) \\n\\
 243 ";
 244
 245 TemplateClassRec templateClassRec = {
 246   { /* core fields */
 247         /* superclass   */      (WidgetClass) &amp;widgetClassRec,
 248         /* class_name   */      "Template",
 249         /* widget_size  */      sizeof(TemplateRec),
 250         /* class_initialize     */      NULL,
 251         /* class_part_initialize        */      NULL,
 252         /* class_inited */      FALSE,
 253         /* initialize   */      NULL,
 254         /* initialize_hook      */      NULL,
 255         /* realize      */      XtInheritRealize,
 256         /* actions      */      actions,
 257         /* num_actions  */      XtNumber(actions),
 258         /* resources    */      resources,
 259         /* num_resources        */      XtNumber(resources),
 260         /* xrm_class    */      NULLQUARK,
 261         /* compress_motion      */      TRUE,
 262         /* compress_exposure    */      TRUE,
 263         /* compress_enterleave */       TRUE,
 264         /* visible_interest     */      FALSE,
 265         /* destroy      */      NULL,
 266         /* resize       */      NULL,
 267         /* expose       */      NULL,
 268         /* set_values   */      NULL,
 269         /* set_values_hook      */      NULL,
 270         /* set_values_almost    */      XtInheritSetValuesAlmost,
 271         /* get_values_hook      */      NULL,
 272         /* accept_focus */      NULL,
 273         /* version      */      XtVersion,
 274         /* callback_private     */      NULL,
 275         /* tm_table     */      translations,
 276         /* query_geometry       */      XtInheritQueryGeometry,
 277         /* display_accelerator  */      XtInheritDisplayAccelerator,
 278         /* extension    */      NULL
 279   },
 280   { /* template fields */
 281         /* empty        */      0
 282   }
 283 };
 284
 285 WidgetClass templateWidgetClass = (WidgetClass)&amp;templateClassRec;
 286 </literallayout>
 287 <!-- .CE -->
 288 <para>
 289 The resource list for the "WindowWidget" might look like the following:
 290 </para>
 291 <!-- .CB -->
 292 <literallayout class="monospaced">
 293 static XtResource resources[] = {
 294 #define offset(field) XtOffsetOf(WindowWidgetRec, window.field)
 295         /* {name, class, type, size, offset, default_type, default_addr}, */
 296         { XtNdrawingColor1, XtCColor, XtRPixel, sizeof(Pixel),
 297                   offset(color_1), XtRString, XtDefaultForeground },
 298         { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel),
 299                   offset(color_2), XtRString, XtDefaultForeground },
 300         { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*),
 301                   offset(font), XtRString, XtDefaultFont },
 302         { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList),
 303                   offset(expose_callback), XtRCallback, NULL },
 304         { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList),
 305                   offset(input_callback), XtRCallback, NULL },
 306 #undef offset
 307 };
 308 </literallayout>
 309 <!-- .CE -->
 310 <para>
 311 <!-- .LP -->
 312 The user input callback will be implemented by an action procedure which
 313 passes the event pointer as call_data.  The action procedure
 314 is declared as:
 315 <!-- .CB -->
 316 </para>
 317 <literallayout class="monospaced">
 318 /* ARGSUSED */
 319 static void InputAction(w, event, params, num_params)
 320         Widget w;
 321         XEvent *event;
 322         String *params;         /* unused */
 323         Cardinal *num_params;   /* unused */
 324 {
 325         XtCallCallbacks(w, XtNcallback, (XtPointer)event);
 326 }
 327
 328 static XtActionsRec actions[] =
 329 {
 330         /* {name,       procedure}, */
 331         {"input",       InputAction},
 332 };
 333 </literallayout>
 334 <!-- .CE -->
 335 <para>
 336 <!-- .LP -->
 337 and the default input binding will be to execute the input callbacks on
 338 <function>KeyPress</function> and <function>ButtonPress : </function>
 339 </para>
 340 <literallayout class="monospaced">
 341 static char translations[] =
 342 "       &lt;Key&gt;:    input(\|) \\n\\
 343         &lt;BtnDown&gt;:        input(\|) \\
 344 ";
 345 </literallayout>
 346 <!-- .CE -->
 347 <para>
 348 In the class record declaration and initialization, the only field that
 349 is different from the Template is the expose procedure:
 350 </para>
 351 <!-- .CB -->
 352 <literallayout class="monospaced">
 353 /* ARGSUSED */
 354 static void Redisplay(w, event, region)
 355         Widget w;
 356         XEvent *event;  /* unused */
 357         Region region;
 358 {
 359         XtCallCallbacks(w, XtNexposeCallback, (XtPointer)region);
 360 }
 361
 362 WindowClassRec windowClassRec = {
 363
 364         ...
 365
 366         /* expose       */      Redisplay,
 367 </literallayout>
 368 <!-- .CE -->
 369 <para>
 370 <!-- .LP -->
 371 <!-- .sp -->
 372 The "WindowWidget" will also declare three public procedures to return the
 373 drawing colors and the font id, saving the application the effort of
 374 constructing an argument list for a call to
 375 <function>XtGetValues :</function>
 376 </para>
 377 <!-- .LP -->
 378 <!-- .CB -->
 379 <literallayout class="monospaced">
 380 Pixel WindowColor1(w)
 381         Widget w;
 382 {
 383         return ((WindowWidget)w)->window.color_1;
 384 }
 385
 386 Pixel WindowColor2(w)
 387         Widget w;
 388 {
 389         return ((WindowWidget)w)->window.color_2;
 390 }
 391
 392 Font WindowFont(w)
 393         Widget w;
 394 {
 395         return ((WindowWidget)w)->window.font->fid;
 396 }
 397 </literallayout>
 398
 399 <para>
 400 The "WindowWidget" is now complete.  The application can retrieve the two
 401 drawing colors from the widget instance by calling either
 402 <function>XtGetValues ,</function>
 403 or the <function>WindowColor</function> functions.  The actual window created for the
 404 "WindowWidget" is available by calling the
 405 <function>XtWindow</function> function.
 406 </para>
 407 </sect2>