| Page: | 1 | 2 | 3 |
|---|
Although the task of creating a new widget may at first appear a little daunting, there is a basic simple pattern that all widgets follow. The Athena Widget library contains a special widget called the Template widget that is intended to assist the novice widget programmer in writing a custom widget.
Reasons for wishing to write a custom widget include:
In each of these cases, the operation needed to create a new widget is to "subclass" an existing one. If the desired semantics of the new widget are similar to an existing one, then the implementation of the existing widget should be examined to see how much work would be required to create a subclass that will then be able to share the existing class methods. Much time will be saved in writing the new widget if an existing widget class Expose, Resize and/or GeometryManager method can be used by the subclass.
Note that some trivial uses of a "bare-bones" widget may be achieved by simply creating an instance of the Core widget. The class variable to use when creating a Core widget is widgetClass. The geometry of the Core widget is determined entirely by the parent widget.
It is very often the case than an application will have a special need for a certain set of functions and that many copies of these functions will be needed. For example, when converting an older application to use the Toolkit, it may be desirable to have a "Window Widget" class that might have the following semantics:
It is obvious that a completely general-purpose WindowWidgetClass could be constructed that would export all class methods as callbacks lists, but such a widget would be very large and would have to choose some arbitrary number of resources such as colors to allocate. An application that used many instances of the general-purpose widget would therefore unnecessarily waste many resources.
In this section, an outline will be given of the procedure to follow to construct a special-purpose widget to address the items listed above. The reader should refer to the appropriate sections of the X Toolkit Intrinsics-C Language Interface for complete details of the material outlined here. Section 1.4 of the Intrinsics should be read in conjunction with this section.
All Athena widgets have three separate
files associated with them:
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 "public"
and "private" 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.
In the following example, the public header file <X11/Xaw/Template.h>, the private header file <X11/Xaw/TemplateP.h> and the source code file <X11/Xaw/Template.c> will be modified to produce the "WindowWidget" 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.
| Home |
|---|
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 XtSetValues operation, or to call a public routine implemented by the widget class.
The contents of the Template public header file, <X11/Xaw/Template.h>, are:
#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 XtNtemplateResource "TemplateResowce"
/* declare specific TemplateWidget class and instance datatypes */
| typedef struct _TemplateClassRec* | TemplateWidgetClass; |
| typedef struct _TemplateRec* | TemplateWidget; |
/* declare the class constant */
exterm WidgetClass templateWidgetClass;
#endif /* _Template_h */
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.
For the "WindowWidget", we want 2 drawing colors, a callback list for user input and an exposeCallback callback list, and we will declare three convenience procedures, so we need to add
| /* Resources: | |||
| ... | |||
| callback | Callback | Callback | NULL |
| drawingColor1 | Color | Pixel | XtDefaultForeground |
| drawingColor2 | Color | Pixel | XtDefaultForeground |
| exposeCallback | Callback | Callback | NULL |
| font | Font | XFontStruct* | XtDefaultFont |
| ... | |||
| */ |
#define XtNdrawingColor 1 "drawingColor 1 "
#de fine X tNdrawingColor2 " draw ingColor2 "
#define XtNexposeCallback "exposeCallback"
extem Pixel WindowColor1(/* Widget
*/);
extem Pixel WindowColor2(/* Widget */);
extem Font WindowFont(/* Widget */);
Note that we have chosen to call the
input callback list by the generic name, callback, 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.
| Home |
|---|
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. XtSetValues.
The contents of the Template private header file, <X11/Xaw/TemplateP.h>, are:
/* Copyright (c) X Consortiums 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 "TemplateResowce"
typedef struct {
int empty;
} TemplateClassPart;
typedef struct _TemplateClassRec {
CoreClassPart core_class;
TemplateClassPart template_class;
} TemplateClassRec;
extem TemplateClassRec templateClassRec;
typedef struct {
/* resources */
char resource;
/* private state */
} TemplatePart;
typedef struct _TemplateRec {
CorePart core;
TemplatePart template;
} TemplateRec;
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.
The "WindowWidget" 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:
typedef struct {
/* resources */
Pixel color_1;
Pixel color_2;
XFontStruct* font;
XtCallbackList expose_callback;
XtCallbackList input_callback;
/* private state */
/* (none) */
} WindowPart;
| Home |
|---|
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.
The contents of the Template implementation file, <X11/Xaw/Template.c>, are:
/* Copyright (c) X Consortium 1987, 1988
*/
#include <X11/lntrinsicP.h>
#include <X11/StringDefs.h>
#include "Template P.h"
static XtResourse 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 XtActionsRec actions[ ] =
{
/* {name, procedure], */
{"template", TemplateAetion},
};
static char translations [ ] =
" <Key>: template()\n\
";
Template ClassRec templateClassRec = {
{ /* core fields */
/* superclass */ (WidgetClass)&widgetClassRee,
/* class_name */ "Template",
/* widget_size */ sizeof(TemplateRec),
/* class_initialize */ NULL,
/* elass_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_elass */ 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
}
};
The resource list for the "WindowWidget" might look like the following:
static XtResourse resources[] = {
#define offset(field) XtOffsetOf(WindowWidgetRec, window.field)
/* {name, class, type, size, offset, default_type, default_addr} */
{ XtNdrawingColorl, 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
};
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:
/* ARGSUSED */
static void InputAction(w, event, params, nurn_params)
Widget w;
XEvent *event;
String *pararns; /* unused */
Cardinal *num_params; /* unused */
{
XtCallCallbacks(w, XtNcallback, (XtPointer)event);
}
static XtActionsRec actions[] =
{
/* { name, procedure }, */
{ "input", InputAction },
};
and the default input binding will be to execute the input callbacks on KeyPress and ButtonPress:
static char translations[] =
" <Key>: input( ) \n\
<BtnDown>: input( ) \
";
In the class record declaration and initialization, the only field that is different from the Template is the expose procedure:
/* ARGSUSED */
static void Redisplay(w, event, region)
Widget w;
XEvent *event; /* unused */
Region region;
{
XtCallCallbacks(w, XtNcxposeCallback, (XtPointer)region);
}
WindowClassRec windowClassRec = {
...
/* expose */ Redisplay,
The "WindowWidget" 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 XtGetValues:
Pixel WindowColorl(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;
}
The "WindowWidget" is now complete. The application can retrieve the two drawing colors from the widget instance by calling either XtGelValues, or the WindowColor functions. The actual window created for the "WindowWidget" is available by calling the XtWindow function.
| Home |
|---|
| Contents | Previous Chapter | Index |