1 <sect2 id="Public_Header_File">
2 <title>Public Header File</title>
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.
12 The contents of the Template public header file,
13 <function>< X11/Xaw/Template.h >, </function>
16 <literallayout class="monospaced">
19 <!-- .\".so ../../lib/Xaw/Template.h -->
20 /* Copyright (c) X Consortium 1987, 1988 */
25 /****************************************************************
29 ****************************************************************/
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
48 /* define any special resource names here that are not in <X11/StringDefs.h> */
50 #define XtNtemplateResource "templateResource"
52 #define XtCTemplateResource "TemplateResource"
54 /* declare specific TemplateWidget class and instance datatypes */
56 typedef struct _TemplateClassRec* TemplateWidgetClass;
57 typedef struct _TemplateRec* TemplateWidget;
59 /* declare the class constant */
61 extern WidgetClass templateWidgetClass;
63 #endif /* _Template_h */
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.
76 For the "WindowWidget", we want 2 drawing colors, a callback list for
78 <function>exposeCallback</function> callback list, and we will declare three
79 convenience procedures, so we need to add
81 <literallayout class="monospaced">
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
95 #define XtNdrawingColor1 "drawingColor1"
96 #define XtNdrawingColor2 "drawingColor2"
97 #define XtNexposeCallback "exposeCallback"
99 extern Pixel WindowColor1(\|/* Widget */\|);
100 extern Pixel WindowColor2(\|/* Widget */\|);
101 extern Font\ \ WindowFont(\|/* Widget */\|);
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
113 <sect2 id="Private_Header_File">
114 <title>Private Header File</title>
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
123 <function>XtSetValues .</function>
127 The contents of the Template private header file,
128 <function>< X11/Xaw/TemplateP.h >, </function>
132 <!-- .\".so ../../lib/Xaw/TemplateP.h -->
133 <literallayout class="monospaced">
134 /* Copyright (c) X Consortium 1987, 1988
140 #include <X11/Xaw/Template.h>
141 /* include superclass private header file */
142 #include <X11/CoreP.h>
144 /* define unique representation types not found in <X11/StringDefs.h> */
146 #define XtRTemplateResource "TemplateResource"
152 typedef struct _TemplateClassRec {
153 CoreClassPart core_class;
154 TemplateClassPart template_class;
157 extern TemplateClassRec templateClassRec;
165 typedef struct _TemplateRec {
167 TemplatePart template;
170 #endif /* _TemplateP_h */
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
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:
186 <literallayout class="monospaced">
192 XtCallbackList expose_callback;
193 XtCallbackList input_callback;
200 <sect2 id="Widget_Source_File">
201 <title>Widget Source File</title>
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.
211 The contents of the Template implementation file,
212 <function>< X11/Xaw/Template.c >,</function>
216 <!-- .\".so ../../lib/Xaw/Template.c -->
217 <literallayout class="monospaced">
218 /* Copyright (c) X Consortium 1987, 1988
221 #include <X11/IntrinsicP.h>
222 #include <X11/StringDefs.h>
223 #include "TemplateP.h"
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" },
233 static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */);
235 static XtActionsRec actions[] =
237 /* {name, procedure}, */
238 {"template", TemplateAction},
241 static char translations[] =
242 " <Key>: template(\|) \\n\\
245 TemplateClassRec templateClassRec = {
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,
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,
280 { /* template fields */
285 WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec;
289 The resource list for the "WindowWidget" might look like the following:
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 },
312 The user input callback will be implemented by an action procedure which
313 passes the event pointer as call_data. The action procedure
317 <literallayout class="monospaced">
319 static void InputAction(w, event, params, num_params)
322 String *params; /* unused */
323 Cardinal *num_params; /* unused */
325 XtCallCallbacks(w, XtNcallback, (XtPointer)event);
328 static XtActionsRec actions[] =
330 /* {name, procedure}, */
331 {"input", InputAction},
337 and the default input binding will be to execute the input callbacks on
338 <function>KeyPress</function> and <function>ButtonPress : </function>
340 <literallayout class="monospaced">
341 static char translations[] =
342 " <Key>: input(\|) \\n\\
343 <BtnDown>: input(\|) \\
348 In the class record declaration and initialization, the only field that
349 is different from the Template is the expose procedure:
352 <literallayout class="monospaced">
354 static void Redisplay(w, event, region)
356 XEvent *event; /* unused */
359 XtCallCallbacks(w, XtNexposeCallback, (XtPointer)region);
362 WindowClassRec windowClassRec = {
366 /* expose */ Redisplay,
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>
379 <literallayout class="monospaced">
380 Pixel WindowColor1(w)
383 return ((WindowWidget)w)->window.color_1;
386 Pixel WindowColor2(w)
389 return ((WindowWidget)w)->window.color_2;
395 return ((WindowWidget)w)->window.font->fid;
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.