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