Tcl/Tk Extensions

For the present, I have just one well-documented, online example of a Tcl extension for you. Some others are given in my book, Tcl/Tk for Programmers, which, I think, is the book with the largest coverage of Tcl extensions (but not of Tcl/Tk extensions). However, almost none of that book's material on extensions is online. The exception is the C code for two of the examples.

The example described in detail here will be of interest to those of you who are learning to write Tcl extensions even if (as is likely) you have no need for the extension itself. The extension implements file input for situations in which a file consists of a mixture of text and tokens.

This extension is organized with the style of object-orientation seen in Tk. This style lets the script writer create objects but not classes. In Tk an object is called a widget. Tk has no classes -- it doesn't permit programmers to create new types of objects.

This extension adds one procedure to Tcl. When the extension is loaded, a sbf namespace is created and this procedure, whose name is intoke, is placed inside. I intend to create other extensions with procedures which will also load into the sbf namespace.

After loading the extension, if you execute

info commands sbf::*

The sbf::intoke procedure is used to create or destroy objects. Each newly created object comes with another procedure of the same name and it is this new object procedure which directly supports token/text input.

This is analogous to what happens when you execute

button .b

in Tk. A button object/widget is created along with a procedure named .b which lets you manipulate that button object/widget.

Both the sbf::intoke procedure and any object procedure it creates are actually families of actions. The particular action they execute is determined by their first argument, e.g.

sbf::intoke open ...
sbf::intoke close ...

The sbf::intoke open action creates an object procedure whose purpose is to read one file. This object procedure has actions suitable for its purpose. It is implementd with a single C function, named Sbfintoke_ObjectCmd. As with Sbfintoke_ClassCmd, Sbfintoke_ObjectCmd has a switch statement that serves to execute another C function which implements a single object action.

How can one C function be used for all the different object procedures created by Sbfintoke_ClassCmd? The answer is that Tcl executes each of these object commands by passing a pointer to a private area to Sbfintoke_ObjectCmd. Tcl knows to do this because Sbfintoke_ClassCmd creates this private data area and tells Tcl about it as it registers Sbfintoke_ObjectCmd as the function to execute for a given object procedure.

In the code you see for this example, a Metamark translator has created both Sbfintoke_ClassCmd and Sbfintoke_ObjectCmd but you don't need to know about Metamark translators to read this example.

The main things to look at are the user documentation and the annotated C code. The latter describes code which can be passed to a gcc compiler. That code is available without the annotations. Also available are C code for the Borland C++ compiler and for the Microsoft's Visual C++ compiler.

There is also a Borland version for the IDE of version 5.0. A DEF file is also available. Simply create a project named sbfintoke in a directory that contains these two files. (You'll have to change the extension of one from BOR to CPP and check the the DLL option while creating the project.)

Finally, there is a Microsoft version for the command line compiler of Visual C++ version 5.0. Here is a makefile. Instructions for its use are included in it.

All five files for use with these three C/C++ compilers (together will all the annotated web pages) were created from one document source by the Metamark system mentioned above.