Itcl Widget Base Class

Introduction

The widget class encapsulates the mechanism required to wrap an Itcl object around a Tk widget. Itcl compound widgets subclassed from the widget class can be written more easily than those written from scratch.

Contents

What the Widget Class Provides

The widget class encapsulates the mechanism required to wrap an Itcl object around a Tk widget. This mechanism involves these basic steps:
  1. Rename the object's Tcl command to some temporary, hidden name
  2. Create a widget with the same name as the object
  3. Rename the widget's Tcl command to some hidden name
  4. Record that hidden name for future use
  5. Rename the object's Tcl command back to its original name
Complicated, eh? Luckily, if you use the widget class, you never have to worry about all of that!

The widget class also provides methods for testing whether the object's root widget still exists (this is useful for the code invoked when public variables are configured) for setting the values of public variables from the X resource database and for creating new sub-widgets without having to worry about their unique names (this is useful for popping up dialog boxes or creating icon-displays)

What the Widget Class Doesn't Provide

The widget class doesn't provide any mechansism for subclassing existing Tk widgets. Although such Itcl widgets can be written, I didn't think there was much point, since the WigWam library provides that already. Unlike the WigWam library, the widget superclass aims to allow the programmer to encapsulate the behaviour of a new compound widget, rather than only extend the behaviour of an existing widget. This makes it easier to write Itcl widgets which can be reimplemented in C/C++ without breaking any existing scripts which use them.

Widget Class Methods

These are the methods exported by the widget class. These methods are for use by classes derived from widget.
widget::constructor widgetType options...
The constructor for the widget class goes through the steps outlined above to create a Tk widget and wrap it with the Itcl object being constructed. The name of the new widget's Tcl command is stored in the instance variable widget::win. The constructor of a derived class should call the constructor of the widget class, passing it the Tcl command used to create the widget to be wrapped and any options to be passed to that command. For instance: ... constructor {config} { widget::constructor frame -class NewWidget ... } ...
widget::destructor
The destructor of the widget class destroys the object's Tk widgets. This triggers the cleaning up of the hidden commands created by the constructor.
widget::exists
Returns 1 if the Itcl object's root widget exists and 0 if it doesn't. This is useful for testing whether to update the window in response to changes to the object's public variables. For instance:
... public background {} { if [widget::exists] { $win configure -background $background ... } } ...
widget::option varName optionName optionClass default
If the value of the variable named varName is the empty string, it is set to a value retrieved from the X resource database using the given option name and class. If the variable's value is not the empty string, the variable is not changed.

This is useful for associating public variables with X resources. The public variables are initialised with the empty string and given their values in the constructor using the Itcl config parameter specifier in the constructors arguments and calls to widget::option after the inital widget has been created by calling widget::constructor. For instance:

itcl_class warnlabel { inherit widget public foreground {} { if [widget::exists] { $win configure -foreground $foreground } } public background {} { if [widget::exists] { $win configure -background $background } } constructor {config} { widget::constructor label -text "Danger!!!" widget::option foreground foreground Foreground black widget::option background background Background red $win configure -foreground $foreground -background $background } method configure {config} {} }
widget::subwidget widgetType options...
Create a new widget which is a child of the Itcl object's root widget without having to specify a path name for the new widget. The name of the new widget is returned.

Widget Class Instance Variables

There is only one instance variable defined by the widget class:

widget::win
The root widget of the Itcl compound widget.

Basic Steps in Deriving from the Widget Class

Not written yet...