diff options
Diffstat (limited to 'libXaw/spec/Template')
| -rw-r--r-- | libXaw/spec/Template | 426 |
1 files changed, 0 insertions, 426 deletions
diff --git a/libXaw/spec/Template b/libXaw/spec/Template deleted file mode 100644 index b5dc050b2..000000000 --- a/libXaw/spec/Template +++ /dev/null @@ -1,426 +0,0 @@ -.\" $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 |