Tcl supports variable traces, which associate arbitrary scripts with variable reads, writes and unsets. We developed OAT (Object Attribute Traces), a protocol for extending traces to attributes of arbitrary Tcl "objects." We wrote several OAT-based extensions including TkOAT, which provides traces on attributes of Tk widgets and canvas items. The OAT protocol and derived extensions bring the benefits of more expressive constraints to Tcl/Tk applications by providing extended traces. OAT requires no changes to the Tcl core and is implemented as a loadable library; OAT-based extended trace packages introduce minimal changes to the code of existing extensions (Tk, CMT, etc.). The new version of our formula manager, TclProp, takes advantage of extended traces provided by OAT.

Tcl’s trace mechanism allows the Tcl script programmer to specify arbitrary scripts to be executed when a given variable is read, written, or unset. It provides, among other things, a good means for propagating changes to variables [Sah95]. For instance, Tcl uses traces internally for the following:

The built-in trace mechanism is limited to variables only. This limitation becomes significant, for instance, when one attempts to use traces and formulas with UI widgets. It is often desirable to detect changes to the state of Tk widgets, or to link widget attributes with formulas. Because many attributes of Tk widgets are not associated with variables, they are not traceable. Examples of such widget attributes include:

• button state, normal or disabled
• state of a menu item, normal or disabled
• button or label color and bitmap
• the number of items in a listbox

We propose OAT, a generic protocol for extending Tcl traces. We target two types of users: Tcl script programmers and Tcl extension developers. Script programmers will benefit from the OAT-based extended traces, because the trace-based Tcl code is more compact and easier to maintain. Extension developers can use OAT to make their objects traceable, to bring the benefits of declarative trace-based programming to users of their extensions. We discuss our experience of making Tk widgets and CMT clocks traceable. Finally, we describe the OAT implementation.

The Listbox Pager shown in Figure 1 demonstrates the usefulness of traces set directly on widget attributes. The "Prev Page" and "Next Page" buttons scroll the contents of the listbox by the number of visible lines. They are disabled when the listbox is positioned on the last page (starting at item 5) and the first page (starting at item 0), respectively. The state of the pager buttons depends on the following three attributes of the listbox:

1. the total number of items
2. the number of visible items
3. the number of the first visible item

Figure 1. A listbox pager using extended traces: first and last pages

Updates to these three listbox attributes can be scattered throughout the script code and widget callbacks. Without extended traces, these updates must be followed by the code that enables and disables the "Prev Page" and "Next Page" buttons. With traces on the listbox attributes available, the Tcl programmer only needs to specify the code to set the state of the pager button once, in the trace callback. The working code in Figure 2 creates the extended traces on listbox attributes, and defines a procedure to check whether the listbox is on the last page, and to enable or disable the buttons accordingly. The trace callback that controls the state of the "Prev Page" button is similar. Since listbox attributes are not traceable in stock Tk and no variables are associated with them, this example demonstrates the need for extended traces for UI development.

Extended traces on canvas attributes also help to maintain geometric relationships among them. For instance, graph drawing packages [Ellson96] and programs for structured drawing benefit from the ability to keep canvas items attached as they are dragged. A line is attached to a circle by creating traces on both line and circle coordinates. The code associated with the traces moves one item as the other is dragged.

# create extended traces on topIndex, numElements, and fullLines
# attributes of listbox widget .lb
trace widget .lb topIndex    w setNextPageState
trace widget .lb numElements w setNextPageState
trace widget .lb fullLines   w setNextPageState
 
# define trace callback
proc setNextPageState {nameSpace widgName attrName op} {
 
    set fraction2 [lindex [$widgName yview] 1]
    if {$fraction2 < 1} {
        .nextPage conf -state normal
    } else {
        .nextPage conf -state disabled
    }
}

Figure 2. Code for trace-based "Next Page" button

These examples and our experience with Tcl/Tk development motivated us to create a protocol for defining traces on attributes of arbitrary Tcl "objects" [Roseman95]. We call an object type enhanced to support traces on its attributes a traceable type. Variables constitute a traceable type with only one (implicit) attribute: their value. Other traceable types we created are Tk widgets, Tk canvas items, CMT clocks, and [incr Tcl] namespaced variables and objects (work on the latter is still in progress).

Our primary goals in the development of OAT were:

1. to define a clean protocol for easily adding traces to new and existing extensions that employ the concept of state-holding objects;
2. to extend the benefits of traces to arbitrary Tcl objects.
3. to make OAT and OAT-based extensions easy to integrate with existing Tcl/Tk installations.

As a proof of concept and for general use, we developed TkOAT, supporting traces on Tk widgets and canvas attributes, and MediOAT, adding traces to CMT clocks. We tried to conform as much as possible to the Tcl interface provided by the trace command, and internal C interfaces, since we found these well-designed and implemented. To ease integration of OAT and OAT-based extensions with Tcl/Tk installations, we created the extensions as loadable libraries, and made changes to the original code only where it was absolutely necessary.

The OAT protocol consists of two parts:

• Tcl API, used by the Tcl script programmer. It defines creation, querying, and deletion of extended traces on objects of traceable types from Tcl code.
• C API, used by the Tcl extension developer. The OAT C API defines a protocol for creating new traceable types, and checking and triggering traces on attributes of traceable type objects.

TclProp [Iyengar95], a trace-based formula manager for Tcl, was updated to take advantage of extended traces. The new TclProp API includes type identification for objects whose attributes are terms in a formula.

trace option ?arg arg ...?

Figure 3: The extended trace command syntax

The traceable type creation protocol permits a writer or a maintainer of a Tcl extension to define new traceable types. The creation of a traceable type involves three main steps:

• extend the trace command: the trace command is extended to accept keywords for new subcommands that create, query, and delete traces on this type.
• register the callback function: the OAT-supplied or custom C callback is registered to be called when these keywords are supplied with the trace command.
• insert checks for traces: checks for traces are inserted in the attribute update code for the traceable type.

Register the callback function. The developer can use the standard OAT-supplied callback for trace subcommands, or write a custom one. The first

approach significantly simplifies creating a traceable type. The extension developer should use the OAT-supplied callback if all extension objects are "global" like Tk widgets, that is, are not contained within a namespace.

Object systems can require additional information to identify an object being traced. For example, traces on canvas item attributes require both a canvas name and an item tag or id to uniquely identify the traced attribute. To support this behavior, OAT allows the extension developer to specify a custom C function that is called when the Tcl interpreter processes the trace subcommands for this type. The prototype for the OAT custom trace callback is shown on Figure 5. We are investigating how to make OAT-supplied trace callbacks more general so that they accommodate objects with namespaces.

Insert checks for traces. The extension developer needs to insert the check for traces in the C code where extension object attributes are updated. This check is done in a single line of code, as shown on Figure6.

Figure 4: A traceable type data structure

typedef int (Oat_CmdProc) (ClientData dummy, Tcl_Interp* interp,
                                int argc, char* argv[]);

Figure 5. Type definition for the custom OAT trace callback.

/* Call traces for widget or canvas item attribute being configured. */
Oat_CallObjTraces(interp, objRec, specPtr->argvName, TCL_TRACE_WRITES);