427 lines
11 KiB
Plaintext
427 lines
11 KiB
Plaintext
.\" $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
|