How to write a complex item class

The Slate tutorial ran quickly through creation of a class to implement a new complex item on the Slate. This page list the steps you need to take in more detail. (Of course, the best way is to make a copy of an existing class that is close to what you need, but this page should help you make sure that you don't miss anything.)

Inheritance
The class must inherit from ::tycho::ComplexItem or one of its subclasses.

Methods
Every "method" is implemented as a public procedure. The first three arguments must always be the item ID, the canvas name, and the slate name.

Constructor and destructor
The class must contain a procedure called construct with the above three arguments, followed by a list of tags to be attached to components, followed by two or more coordinates, followed by option-value pairs. Unless the class has no options, it must start with this code:
foreach {opt value} [concat [array get optiondefault] $args] {
    set option([string trimleft $opt -]$id) $value
}
The construction procedure does not automatically call its superclass "constructors": if your class needs that, you have to do it yourself. The destructor is optional, and is needed only if the class needs to do something other than destroy its components.

Virtual method table
Complex item classes simulate inheritance explicitly using an array as a "virtual method table." Every class must contain the declaration
common methodtable
(Do not change the name!) The class must (in the class body) initialize the table with the contents of the table in its superclass; assuming that the superclass is ComplexItem, the class body then contains:
array set methodtable [array get ::tycho::ComplexItem::methodtable]
The class must then "override" superclass "methods" with its own. The construct method is compulsory; others are optional. Suppose your class overrides coords (which many classes do), your class body contains:
set methodtable(construct)   ::tycho::Bar::construct
set methodtable(coords)      ::tycho::Bar::coords
where "Bar" is the name of your class. If your class adds options, you must also add the option update procedures (see below).

Instance variables
"Instance variables" are stored in the common array variable, declared in the ComplexItem class. Index the elements of this array by variable and followed by item id. For example, to set a variable foo, use
set variable(foo$id) "bar"

Option declarations
For each option, say -foo, the class must contain a public procedure named _foo. Option variable values are stored in the common array option, declared in the ComplexItem superclass. Each element of the array is indexed by the option name (without leading dash) followed by the item id. For example, to read the option foo, use
$option(foo$id)

The procedure _foo is called by the IncrCanvas when an option is changed (with its itemconfigure method). The procedure must take, in addition to the usual three arguments, one argument that it assigns to option(foo$id); it can then perform any actions that would normally (in a regular [incr Tcl] object) be done by the configuration body of a public variable or itk_option.

Option defaults
The class body must contain the declaration:
common optiondefault
The class body must contain the declaration:
array set optiondefault [array get ::tycho::ComplexItem::optiondefault]

Each option defined in this class must have its default value added to this array:

set optiondefault(-foo) bool

Option update

Each option must have its update procedure added to the "virtual method table":

set methodtable(_foo) ::tycho::Bar::_foo

Item shape
The class body may need to set a different value of the -shape option:
set optiondefault(-shape) rectangle
where instead of rectangle you could have oval, point, line, or polygon.
Um, OK, other than that, you can do whatever you want... The best way to do this, really, is just to go and use the existing classes as examples. It's simpler than it sounds.

Back up
Tycho Home Page


Copyright © 1996-1998, The Regents of the University of California. All rights reserved.
Last updated: 05/19/98, comments to: johnr@eecs.berkeley.edu