1<sect2 id="Public_Header_File"> 2<title>Public Header File</title> 3<para> 4The public header file contains declarations that will be required by any 5application module that needs to refer to the widget; whether to create 6an instance of the class, to perform an 7<xref linkend='XtSetValues' xrefstyle='select: title'/> 8operation, or to call a public routine implemented by the widget class. 9</para> 10<para> 11<!-- .LP --> 12The contents of the Template public header file, 13<filename class="headerfile"><X11/Xaw/Template.h></filename>, 14are: 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 <X11/StringDefs.h> */ 49 50#define XtNtemplateResource "templateResource" 51 52#define XtCTemplateResource "TemplateResource" 53 54/* declare specific TemplateWidget class and instance datatypes */ 55 56typedef struct _TemplateClassRec* TemplateWidgetClass; 57typedef struct _TemplateRec* TemplateWidget; 58 59/* declare the class constant */ 60 61extern WidgetClass templateWidgetClass; 62 63#endif /* _Template_h */ 64<!-- .CE --> 65</literallayout> 66<para> 67<!-- .LP --> 68<!-- .sp --> 69You will notice that most of this file is documentation. The crucial 70parts are the last 8 lines where macros for any private resource names 71and classes are defined and where the widget class datatypes and class 72record pointer are declared. 73</para> 74<para> 75<!-- .LP --> 76For the "WindowWidget", we want 2 drawing colors, a callback list for 77user input and an 78<function>exposeCallback</function> callback list, and we will declare three 79convenience 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 99extern Pixel WindowColor1( /* Widget */ ); 100extern Pixel WindowColor2( /* Widget */ ); 101extern Font WindowFont( /* Widget */ ); 102<!-- .CE --> 103</literallayout> 104<para> 105<!-- .LP --> 106Note that we have chosen to call the input callback list by the generic 107name, <function>callback</function>, rather than a specific name. If widgets that define 108a single user-input action all choose the same resource name then there 109is greater possibility for an application to switch between widgets of 110different types. 111</para> 112</sect2> 113<sect2 id="Private_Header_File"> 114<title>Private Header File</title> 115<para> 116<!-- .LP --> 117The private header file contains the complete declaration of the class 118and instance structures for the widget and any additional private data 119that will be required by anticipated subclasses of the widget. 120Information in the private header file is normally hidden from the 121application and is designed to be accessed only through other public 122procedures; e.g. 123<function>XtSetValues</function>. 124</para> 125<para> 126<!-- .LP --> 127The contents of the Template private header file, 128<filename class="headerfile"><X11/Xaw/TemplateP.h></filename>, 129are: 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 <X11/Xaw/Template.h> 141/* include superclass private header file */ 142#include <X11/CoreP.h> 143 144/* define unique representation types not found in <X11/StringDefs.h> */ 145 146#define XtRTemplateResource "TemplateResource" 147 148typedef struct { 149 int empty; 150} TemplateClassPart; 151 152typedef struct _TemplateClassRec { 153 CoreClassPart core_class; 154 TemplateClassPart template_class; 155} TemplateClassRec; 156 157extern TemplateClassRec templateClassRec; 158 159typedef struct { 160 /* resources */ 161 char* resource; 162 /* private state */ 163} TemplatePart; 164 165typedef struct _TemplateRec { 166 CorePart core; 167 TemplatePart template; 168} TemplateRec; 169 170#endif /* _TemplateP_h */ 171<!-- .CE --> 172</literallayout> 173<para> 174The private header file includes the private header file of its 175superclass, thereby exposing the entire internal structure of the widget. 176It may not always be advantageous to do this; your own project 177development style will dictate the appropriate level of detail to expose 178in each module. 179</para> 180<para> 181The "WindowWidget" needs to declare two fields in its instance structure to 182hold the drawing colors, a resource field for the font and a field for the 183expose and user input callback lists: 184</para> 185 186<literallayout class="monospaced"> 187typedef 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 --> 204The source code file implements the widget class itself. The unique 205part of this file is the declaration and initialization of the 206widget class record structure and the declaration of all resources and 207action routines added by the widget class. 208</para> 209<para> 210<!-- .LP --> 211The contents of the Template implementation file, 212<filename class="headerfile"><X11/Xaw/Template.c></filename>, 213are: 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 <X11/IntrinsicP.h> 222#include <X11/StringDefs.h> 223#include "TemplateP.h" 224 225static 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 233static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */); 234 235static XtActionsRec actions[] = 236{ 237 /* {name, procedure}, */ 238 {"template", TemplateAction}, 239}; 240 241static char translations[] = 242" <Key>: template( ) \\n\\ 243"; 244 245TemplateClassRec templateClassRec = { 246 { /* core fields */ 247 /* superclass */ (WidgetClass) &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 285WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec; 286</literallayout> 287<!-- .CE --> 288<para> 289The resource list for the "WindowWidget" might look like the following: 290</para> 291<!-- .CB --> 292<literallayout class="monospaced"> 293static 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 --> 312The user input callback will be implemented by an action procedure which 313passes the event pointer as call_data. The action procedure 314is declared as: 315<!-- .CB --> 316</para> 317<literallayout class="monospaced"> 318/* ARGSUSED */ 319static 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 328static XtActionsRec actions[] = 329{ 330 /* {name, procedure}, */ 331 {"input", InputAction}, 332}; 333</literallayout> 334<!-- .CE --> 335<para> 336<!-- .LP --> 337and 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"> 341static char translations[] = 342" <Key>: input( ) \\n\\ 343 <BtnDown>: input( ) \\ 344"; 345</literallayout> 346<!-- .CE --> 347<para> 348In the class record declaration and initialization, the only field that 349is different from the Template is the expose procedure: 350</para> 351<!-- .CB --> 352<literallayout class="monospaced"> 353/* ARGSUSED */ 354static void Redisplay(w, event, region) 355 Widget w; 356 XEvent *event; /* unused */ 357 Region region; 358{ 359 XtCallCallbacks(w, XtNexposeCallback, (XtPointer)region); 360} 361 362WindowClassRec windowClassRec = { 363 364 ... 365 366 /* expose */ Redisplay, 367</literallayout> 368<!-- .CE --> 369<para> 370<!-- .LP --> 371<!-- .sp --> 372The "WindowWidget" will also declare three public procedures to return the 373drawing colors and the font id, saving the application the effort of 374constructing an argument list for a call to 375<function>XtGetValues :</function> 376</para> 377<!-- .LP --> 378<!-- .CB --> 379<literallayout class="monospaced"> 380Pixel WindowColor1(w) 381 Widget w; 382{ 383 return ((WindowWidget)w)->window.color_1; 384} 385 386Pixel WindowColor2(w) 387 Widget w; 388{ 389 return ((WindowWidget)w)->window.color_2; 390} 391 392Font WindowFont(w) 393 Widget w; 394{ 395 return ((WindowWidget)w)->window.font->fid; 396} 397</literallayout> 398 399<para> 400The "WindowWidget" is now complete. The application can retrieve the two 401drawing colors from the widget instance by calling either 402<function>XtGetValues</function>, 403or 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> 408