Added libXaw

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