diff options
Diffstat (limited to 'libXaw/spec/Template')
| -rw-r--r-- | libXaw/spec/Template | 426 |
1 files changed, 426 insertions, 0 deletions
diff --git a/libXaw/spec/Template b/libXaw/spec/Template new file mode 100644 index 000000000..b5dc050b2 --- /dev/null +++ b/libXaw/spec/Template @@ -0,0 +1,426 @@ +.\" $Xorg: Template,v 1.3 2000/08/17 19:42:28 cpqbld Exp $ +All Athena widgets have three separate files associated with them: +.LP +.IP \(bu 3 +A \*Qpublic\*U header file containing declarations needed by +applications programmers +.IP \(bu 3 +A \*Qprivate\*U header file containing additional declarations needed by the +widget and any subclasses +.IP \(bu 3 +A source code file containing the implementation of the widget +.LP +This separation of functions into three files is suggested for all +widgets, but nothing in the Toolkit actually requires this format. In +particular, a private widget created for a single application may easily +combine the \*Qpublic\*U and \*Qprivate\*U header files into a single file, or +merge the contents into another application header file. Similarly, the +widget implementation can be merged into other application code. +.LP +.sp +In the following example, the public header file +.Pn < X11/Xaw/Template.h >, +the private header file +.Pn < X11/Xaw/TemplateP.h > +and the source code file +.Pn < X11/Xaw/Template.c > +will be modified to produce the \*QWindowWidget\*U described above. +In each case, the files have been designed so that a global string +replacement of ``Template'' and ``template'' +with the name of your new widget, using +the appropriate case, can be done. +.NH 2 +Public Header File +.LP +The public header file contains declarations that will be required by any +application module that needs to refer to the widget; whether to create +an instance of the class, to perform an +.PN XtSetValues +operation, or to call a public routine implemented by the widget class. +.LP +The contents of the Template public header file, +.Pn < X11/Xaw/Template.h >, +are: +.de CB +.sp +.Ds 0 +.SM +.vs 10 +.in +.25i +.TA .25i 1.4i 2.4i 2.75i 3.5i +.ta .25i 1.4i 2.4i 2.75i 3.5i +.. +.de CE +.NL +.vs 13 +.De +.\".in -.25i +.. +.CB +.\".so ../../lib/Xaw/Template.h +/* XConsortium: Template.h,v 1.2 88/10/25 17:22:09 swick Exp $ */ +/* Copyright (c) X Consortium 1987, 1988 */ + +#ifndef _Template_h +#define _Template_h + +/**************************************************************** + * + * Template widget + * + ****************************************************************/ + +/* Resources: + + Name Class RepType Default Value + ---- ----- ------- ------------- + background Background Pixel XtDefaultBackground + border BorderColor Pixel XtDefaultForeground + borderWidth BorderWidth Dimension 1 + destroyCallback Callback Pointer NULL + height Height Dimension 0 + mappedWhenManaged MappedWhenManaged Boolean True + sensitive Sensitive Boolean True + width Width Dimension 0 + x Position Position 0 + y Position Position 0 + +*/ + +/* define any special resource names here that are not in <X11/StringDefs.h> */ + +#define XtNtemplateResource "templateResource" + +#define XtCTemplateResource "TemplateResource" + +/* declare specific TemplateWidget class and instance datatypes */ + +typedef struct _TemplateClassRec* TemplateWidgetClass; +typedef struct _TemplateRec* TemplateWidget; + +/* declare the class constant */ + +extern WidgetClass templateWidgetClass; + +#endif /* _Template_h */ +.CE +.LP +.sp +You will notice that most of this file is documentation. The crucial +parts are the last 8 lines where macros for any private resource names +and classes are defined and where the widget class datatypes and class +record pointer are declared. +.LP +For the \*QWindowWidget\*U, we want 2 drawing colors, a callback list for +user input and an +\fBexposeCallback\fP callback list, and we will declare three +convenience procedures, so we need to add +.LP +.sp +.CB +/* Resources: + ... + callback Callback Callback NULL + drawingColor1 Color Pixel XtDefaultForeground + drawingColor2 Color Pixel XtDefaultForeground + exposeCallback Callback Callback NULL + font Font XFontStruct* XtDefaultFont + ... + */ + +#define XtNdrawingColor1 "drawingColor1" +#define XtNdrawingColor2 "drawingColor2" +#define XtNexposeCallback "exposeCallback" + +extern Pixel WindowColor1(\|/* Widget */\|); +extern Pixel WindowColor2(\|/* Widget */\|); +extern Font\ \ WindowFont(\|/* Widget */\|); +.CE +.LP +Note that we have chosen to call the input callback list by the generic +name, \fBcallback\fP, rather than a specific name. If widgets that define +a single user-input action all choose the same resource name then there +is greater possibility for an application to switch between widgets of +different types. +.NH 2 +Private Header File +.LP +The private header file contains the complete declaration of the class +and instance structures for the widget and any additional private data +that will be required by anticipated subclasses of the widget. +Information in the private header file is normally hidden from the +application and is designed to be accessed only through other public +procedures; e.g. +.PN XtSetValues . +.LP +The contents of the Template private header file, +.Pn < X11/Xaw/TemplateP.h >, +are: +.CB +.\".so ../../lib/Xaw/TemplateP.h +/* XConsortium: TemplateP.h,v 1.2 88/10/25 17:31:47 swick Exp $ */ + +/* Copyright (c) X Consortium 1987, 1988 + */ + +#ifndef _TemplateP_h +#define _TemplateP_h + +#include <X11/Xaw/Template.h> +/* include superclass private header file */ +#include <X11/CoreP.h> + +/* define unique representation types not found in <X11/StringDefs.h> */ + +#define XtRTemplateResource "TemplateResource" + +typedef struct { + int empty; +} TemplateClassPart; + +typedef struct _TemplateClassRec { + CoreClassPart core_class; + TemplateClassPart template_class; +} TemplateClassRec; + +extern TemplateClassRec templateClassRec; + +typedef struct { + /* resources */ + char* resource; + /* private state */ +} TemplatePart; + +typedef struct _TemplateRec { + CorePart core; + TemplatePart template; +} TemplateRec; + +#endif /* _TemplateP_h */ +.CE +.LP +.sp +The private header file includes the private header file of its +superclass, thereby exposing the entire internal structure of the widget. +It may not always be advantageous to do this; your own project +development style will dictate the appropriate level of detail to expose +in each module. +.LP +The \*QWindowWidget\*U needs to declare two fields in its instance structure to +hold the drawing colors, a resource field for the font and a field for the +expose and user input callback lists: +.CB +typedef struct { + /* resources */ + Pixel color_1; + Pixel color_2; + XFontStruct* font; + XtCallbackList expose_callback; + XtCallbackList input_callback; + /* private state */ + /* (none) */ +} WindowPart; +.CE +.NH 2 +Widget Source File +.LP +The source code file implements the widget class itself. The unique +part of this file is the declaration and initialization of the +widget class record structure and the declaration of all resources and +action routines added by the widget class. +.LP +The contents of the Template implementation file, +.Pn < X11/Xaw/Template.c >, +are: +.CB +.\".so ../../lib/Xaw/Template.c +/* XConsortium: Template.c,v 1.2 88/10/25 17:40:25 swick Exp $ */ + +/* Copyright (c) X Consortium 1987, 1988 + */ + +#include <X11/IntrinsicP.h> +#include <X11/StringDefs.h> +#include "TemplateP.h" + +static XtResource resources[] = { +#define offset(field) XtOffsetOf(TemplateRec, template.field) + /* {name, class, type, size, offset, default_type, default_addr}, */ + { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource, + sizeof(char*), offset(resource), XtRString, (XtPointer) "default" }, +#undef offset +}; + +static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */); + +static XtActionsRec actions[] = +{ + /* {name, procedure}, */ + {"template", TemplateAction}, +}; + +static char translations[] = +" <Key>: template(\|) \\n\\ +"; + +TemplateClassRec templateClassRec = { + { /* core fields */ + /* superclass */ (WidgetClass) &widgetClassRec, + /* class_name */ "Template", + /* widget_size */ sizeof(TemplateRec), + /* class_initialize */ NULL, + /* class_part_initialize */ NULL, + /* class_inited */ FALSE, + /* initialize */ NULL, + /* initialize_hook */ NULL, + /* realize */ XtInheritRealize, + /* actions */ actions, + /* num_actions */ XtNumber(actions), + /* resources */ resources, + /* num_resources */ XtNumber(resources), + /* xrm_class */ NULLQUARK, + /* compress_motion */ TRUE, + /* compress_exposure */ TRUE, + /* compress_enterleave */ TRUE, + /* visible_interest */ FALSE, + /* destroy */ NULL, + /* resize */ NULL, + /* expose */ NULL, + /* set_values */ NULL, + /* set_values_hook */ NULL, + /* set_values_almost */ XtInheritSetValuesAlmost, + /* get_values_hook */ NULL, + /* accept_focus */ NULL, + /* version */ XtVersion, + /* callback_private */ NULL, + /* tm_table */ translations, + /* query_geometry */ XtInheritQueryGeometry, + /* display_accelerator */ XtInheritDisplayAccelerator, + /* extension */ NULL + }, + { /* template fields */ + /* empty */ 0 + } +}; + +WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec; + +.CE +The resource list for the \*QWindowWidget\*U might look like the following: +.CB +static XtResource resources[] = { +#define offset(field) XtOffsetOf(WindowWidgetRec, window.field) + /* {name, class, type, size, offset, default_type, default_addr}, */ + { XtNdrawingColor1, XtCColor, XtRPixel, sizeof(Pixel), + offset(color_1), XtRString, XtDefaultForeground }, + { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel), + offset(color_2), XtRString, XtDefaultForeground }, + { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), + offset(font), XtRString, XtDefaultFont }, + { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), + offset(expose_callback), XtRCallback, NULL }, + { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), + offset(input_callback), XtRCallback, NULL }, +#undef offset +}; +.CE +.LP +The user input callback will be implemented by an action procedure which +passes the event pointer as call_data. The action procedure +is declared as: +.CB +/* ARGSUSED */ +static void InputAction(w, event, params, num_params) + Widget w; + XEvent *event; + String *params; /* unused */ + Cardinal *num_params; /* unused */ +{ + XtCallCallbacks(w, XtNcallback, (XtPointer)event); +} + +static XtActionsRec actions[] = +{ + /* {name, procedure}, */ + {"input", InputAction}, +}; +.CE +.LP +and the default input binding will be to execute the input callbacks on +.PN KeyPress +and +.PN ButtonPress : +.LP +.CB +static char translations[] = +" <Key>: input(\|) \\n\\ + <BtnDown>: input(\|) \\ +"; +.CE +.LP +In the class record declaration and initialization, the only field that +is different from the Template is the expose procedure: +.CB +/* ARGSUSED */ +static void Redisplay(w, event, region) + Widget w; + XEvent *event; /* unused */ + Region region; +{ + XtCallCallbacks(w, XtNexposeCallback, (XtPointer)region); +} + +WindowClassRec windowClassRec = { + + ... + + /* expose */ Redisplay, +.CE +.LP +.sp +The \*QWindowWidget\*U will also declare three public procedures to return the +drawing colors and the font id, saving the application the effort of +constructing an argument list for a call to +.PN XtGetValues : +.LP +.CB +Pixel WindowColor1(w) + Widget w; +{ + return ((WindowWidget)w)->window.color_1; +} + +Pixel WindowColor2(w) + Widget w; +{ + return ((WindowWidget)w)->window.color_2; +} + +Font WindowFont(w) + Widget w; +{ + return ((WindowWidget)w)->window.font->fid; +} +.CE +.LP +The \*QWindowWidget\*U is now complete. The application can retrieve the two +drawing colors from the widget instance by calling either +.PN XtGetValues , +or the \fBWindowColor\fP functions. The actual window created for the +\*QWindowWidget\*U is available by calling the +.PN XtWindow +function. +.ds LH +.ds CH +.ds RH +.nr PN +1 +.XS +Index +.XE +.tm .pn \n(PN +.nr PN -1 +.\" print Table of Contents +.if o .bp \" blank page to make count even +.bp 3 +.af PN i +.PX |