Next: CGI Environment Extensions for W3Kit
Up: W3Kit 2.2, An Object-Oriented Toolkit for Interactive WWW Applications
Prev: Designing a W3Kit Application

Creating a custom widget in W3Kit

W3Kit provides abstract classes for a variety of purposes:

These classes are designed to simplify common application tasks. What remains for subclass code is to
  1. Define the appearance of the widget in terms of HTML, PostScript, or MinneGraphics, as appropriate.
  2. Define the response of the widget to user events such as text entry and mouse clicks.
  3. Define the object's state, and designate which part of that state is to be considered ``essential.''

Drawing

In order to provide a custom appearance for graphics classes, you would typically also override the appropriate (initially empty) methods:

- renderMinneGraphics; // W3MinneGraphics subclasses
- drawPostScript; // W3PostScript subclasses

Control widgets would instead display their appearance by directly overriding

- printHtml;

Note that most control widgets implemented by the kit display their original value in addition to the current value being edited, when they display a title. That's because the edited input remains attached in the browser to the old (uneditable) output generated by the previous run. Even with the availability of a RESET button, the potential for confusion is sufficient that it is better to display uneditable copies of the original input values whenever feasible. You can either weave the numbers into your own text, or the kit will display them if you give the widget a title.

Events

In order to handle events, graphics classes override

- mouseClick:(const Point2 *)aPoint;
The point is provided in PostScipt user coordinates in the 2D case, and in coordinates ranging between -1 and +1 in the 3D case. (The W3MinneSelection class provides support for using this click to choose a 3D location based on hitting an OOGL geometry.)

Control widgets would override the lower-level event messages sent directly by W3App:

- enterStringValue:(const char *)aString;
- enterIntPointValue:(const IntPoint *)aPoint;
- enterImpliedValue;
The click point here is given in HTML image coordinates, which have pixel units and an origin in the top left corner.

Creation, Destruction, and State Maintenance

In addition, all widgets will generally override the following administrative methods, which allow W3App to properly manage their state.

You must decide what is "essential" vs. "non-essential" state among the variables you add in your subclass. Essential state is that which you want to retain from one iteration to the next, independent of whether there is an explicit post form element to control it; for such state, it is not good enough to just use "reasonable" default values. Non-essential state is all the rest. Try to minimize the amount of essential state.

@implementation MyClass
- reset
{
	if(![super reset]) return nil;
	// ... (Re-)initialize non-essential state ...
	return self;
}

- init
{
	// ... Pre-initialize any essential state on which -reset depends ...
	if(![super init]) return nil;
	// ... Initialize essential state ...
	return self;
}

- free
{
	// ... free allocated instance vars ...
	return [super free];
}

- write:(TypedStream *)stream
{
	[super write:stream];
	// ... write essential state to stream ...
	return self;
}

- read:(TypedStream *)stream
{
	[super read:stream];
	// ... read essential state from stream ...
	return self;
}
@end
See w3io.h for functions you can use to read and write object data. See also Known Bugs for problems with archiving under GNU Objective-C.


Next: CGI Environment Extensions for W3Kit
Up: W3Kit 2.2, An Object-Oriented Toolkit for Interactive WWW Applications
Prev: Designing a W3Kit Application

[HOME] The Geometry Center Home Page

Author: Paul Burchard
Comments to: webmaster@geom.umn.edu
Created: Apr 18 1994 --- Last modified: Tue Jun 18 10:23:32 1996