ET_PROC( name-of-the-new-command ){
    /* C code to implement the command */
  }

Though they do not appear explicitly in the source code, every function created using ET_PROC has four formal parameters.

• argc

  This parameter is an integer that holds the number of arguments on the Tcl command that invokes the function. Its role is exactly the same as the argc parameter to the main function of a standard C program.

• argv

  Like argc before it, this parameter works just like the argv parameter to main. The variable argv[0] contains the name of the the command itself (DecimalTime in this example), argv[1] contains the name of the first argument, argv[2] contains the name of the second argument, and so forth up to argv[argc] which is a null pointer.

• interp

  This parameter is a pointer to the Tcl/Tk interpreter. It has type Tcl_Interp*. The interp parameter has many uses, but is most often used to set the return value of the Tcl/Tk function. (Note that you have to #include either <tcl.h> or <tk.h> somewhere in your source file in order to use the interp parameter, since one of these header files are needed to define the fields of the Tcl_Interp structure.)

• clientData

  This is a pointer to the Tk_Window structure that defines the main window (e.g. the . window) of the application. It has a type of void* and will need to be typecast before it is used. On the other hand, it is seldom used, so this isn't normally a problem.

The decimal clock example uses the interp formal parameter on the sixth line of the ET_PROC function. In particular, the DecimalTime function writes its result (e.g. the time as a decimal number) into the result field of interp. It's OK to write up to about 200 bytes of text into the result field of the interp parameter, and that text will become the return value of the Tcl/Tk command. If you need to return more than about 200 bytes of text, then you should set the result using one of the routines from the Tcl library designed for that purpose: Tcl_SetResult, Tcl_AppendResult, or Tcl_AppendElement. (These routines are documented by Tcl's manual pages under the name SetResult.) If all this seems too complicated, then you can choose to do nothing at all, in which case the return value defaults to an empty string.

Another important feature of every ET_PROC function is its return value. Every ET_PROC should return either ET_OK or ET_ERROR, depending on whether or not the function encountered any errors. (ET_OK and ET_ERROR are #define constants inserted by et2c and have the save values as TCL_OK and TCL_ERROR.) It is impossible for the DecimalClock function to fail, so it always returns ET_OK, but most ET_PROC functions can return either result.

Part of Tcl's result protocol is that if a command returns ET_ERROR it should put an error message in the interp->result field. If we had wanted to be pedantic, we could have put a test in the DecimalTime function to make sure it is called with no arguments. Like this:

  ET_PROC( DecimalTime ){
    struct tm *pTime;  /* The time of day decoded */
    time_t now;        /* Number of seconds since the epoch */

    if( argc!=1 ){
      Tcl_AppendResult(interp,"The ",argv[0],
        " command should have no argument!",0);
      return ET_ERROR;
    } 
    /* The rest of the code is omitted ... */
  }

The ET_INSTALL_COMMANDS statement

We've seen how the ET_PROC constuct will create a new Tcl/Tk command. But that command must still be registered with the Tcl interpreter before it can be used. Fortunately, ET makes this very easy.

ET uses the ET_INSTALL_COMMANDS keyword to register ET_PROC commands with the Tcl interpreter. The et2c preprocessor converts the ET_INSTALL_COMMANDS keyword into a sequence of C instructions that register every ET_PROC in the current file. In the main procedure of the decimal clock example, the ET_INSTALL_COMMANDS keyword that immediately follows the Et_Init function is used to register the DecimalTime command. As it turns out, DecimalTime is the only ET_PROC function in the same source file, but even if there had be 100 others, they would have all been registered by that single ET_INSTALL_COMMANDS statement.

The ET_INSTALL_COMMANDS keyword can also be used to register ET_PROC functions in separate source files, simply by putting the name of the source file in parentheses after the ET_INSTALL_COMMANDS keyword. Like this:

   ET_INSTALL_COMMANDS( otherfile.c );

Summary Of Writing Tcl/Tk Commands In C

Before leaving this section, let's briefly summarize the steps needed to create new Tcl/Tk commands in C using ET. First you create one or more commands using the ET_PROC construct, as follows:

  ET_PROC( name-of-the-new-command ){
    /* C code to implement the command */
    return ET_OK;  /* Don't forget the return value! */
  }

  ET_INSTALL_COMMANDS( name-of-file-containing-ET_PROCs.c );

The ET_PROC construct lets you put a C routine in the middle of Tcl/Tk. The next section will take a closer look at ET which allows you to put Tcl/Tk in the middle of a C routine.

The ET() Function And Its Siblings

If you've been keeping up with the examples, you've already seen the ET function used twice to insert a few lines of Tcl/Tk in the middle of a C procedure. But the ET function can do a lot more, as this section will show.

Moving Information From Tcl/Tk To C

The first thing to note about ET is that, just like a real C function, it has a return value. ET returns an integer status code which is either ET_OK or ET_ERROR depending on whether the enclosed Tcl/Tk was successful or failed. (ET might also return TCL_RETURN, TCL_BREAK, or TCL_CONTINUE under rare circumstances.)

The status return of ET is nice, but in practice it turns out to be mostly useless. What you really need is the string value returned by the enclosed Tcl/Tk script. That's the purpose of the ET_STR function.

The ET_STR function works a lot like ET. You put in a Tcl/Tk script as the argument, and the script gets executed. But instead of returning a status code, ET_STR returns a pointer to a string that was the result of the last Tcl/Tk command in its argument.

The ET_STR function turns out to be a very handy mechanism for querying values from Tcl/Tk. For instance, suppose your program has an entry widget named .entry and some piece of C code needs to know the current contents of the entry. You can write this:

  char *entryText = ET_STR(.entry get);

  int width, height, x, y;
  sscanf(ET_STR(wm geometry .),"%dx%d+%d+%d",&width,&height,&x,&y);

  char *zCustomerName = ET_STR(set CustomerName);

But, there are two subtleties with ET_STR that programmers should always keep in mind. The first is that the Tcl/Tk script in the argument is executed at Tcl's global variable context level. This means that all of the Tcl/Tk variables ET_STR creates, and the only Tcl/Tk variables it can access, are global variables. This limitation also applies to the regular ET function, and to two other function we haven't talked about yet: ET_INT and ET_DBL. ET provides no means for C code to access or modify local variables. On the other hand, this has not proven to be a serious hardship in practice.

The second subtlety with ET_STR is more dangerous, but fortunately applies to ET_STR only. Recall that ET_STR returns a pointer to a string, not the string itself. The string actually resides in memory that is held deep within the bowels of Tcl/Tk. The danger is that the next Tcl/Tk command may choose to change, deallocate, or reuse this memory, corrupting the value returned by ET_STR. We say that the return value of ET_STR is ephemeral.

One way to overcome the ephemerality of ET_STR is by making a copy of the returned string. The strdup function is good for this. (Unfortunately, strdup is missing from a lot of C libraries. You may have to write your own string duplicator.) In place of the examples given above, you might write

  char *entryText = strdup( ET_STR(.entry get) );

  char *zCustomerName = strdup( ET_STR(set CustomerName) );

The other way to overcome the ephemerality of ET_STR is simply not to use the returned string for very long. You should be safe in using the returned string as long as you don't invoke any other Tcl/Tk commands, or return to the event loop. Code like this

  sscanf(ET_STR(wm geometry .),"%dx%d+%d+%d",&width,&height,&x,&y);

In addition to ET and ET_STR, the ET system provides two other functions named ET_INT and ET_DBL. Both take a Tcl/Tk script for their argument, as you would expect. But ET_INT returns an integer result and ET_DBL returns a floating-point value (a double). In a sense, these two functions are extensions of ET_STR. In fact, ET_INT does essentially the same thing as

   int v = strtol( ET_STR(...), 0, 0);

   double r = strtod( ET_STR(...), 0);

Moving Information From C To Tcl/Tk

We've seen how ET_STR, ET_INT and ET_DBL can be used to pass values from Tcl/Tk back to C. But how do you go the other way and transfer C variable values into Tcl/Tk? ET has a mechanism to accomplish this too, of course.

Within the argument to any ET function (or ET_STR or ET_INT or ET_DBL), the string %d(x) is special. When ET sees such a string, it evalutes the integer C expression x, converts the resulting integer into decimal, and substitutes the integer's decimal value for the original string. For example, suppose you want to initialize the Tcl/Tk variable named nPayment to be twelve times the value of a C variable called nYear. You might write the following code:

    ET( set nPayment %d(12*nYear) );

    id = ET_INT( .cnvs create oval %d(x-r) %d(y-r) %d(x+r) %d(y+r) );

    ET( .cnvs itemconfig %d(id) -fill skyblue );

If you want to substitute a string or floating-point value into an ET argument, you can use %s(x) and %f(x) in place of %d(x). The names of these substitutions phrases were inspired by the equivalent substitution tokens in the standard C library function printf. Note, however, that you cannot specify a field-width, precision, or option flag in ET like you can in printf. In other words, you can use conversions like %-10.3f in prinf but not in ET. The ET function will accepts only specification, such as %f.

But the ET function does support a conversion specifier that standard printf does not: the %q(x) substitution. The %q works like %s in that it expects its argument to be a null-terminated string, but unlike %s the %q converter inserts extra backslash characters into the string in order to escape characters that have special meaning to Tcl/Tk. Consider an example.

  char *s = "The price is $1.45";
  ET( puts "%q(s)" );

  puts "The price is \$1.45"

  can't read "1": no such variable

Summary Of The ET() Function

And that's everything there is to know about the ET function and its siblings. In case you missed something amid all the details, here's a 10-second review of the essential facts:

• The ET executes Tcl/Tk code and returns a success/failure code.
• ET_STR, ET_INT and ET_DBL do the same, but return a string, and integer or a double which was the result of the last Tcl/Tk command executed.
• The return value from ET_STR is ephemeral.
• The strings %s(...), %d(...) and %f(...) insert string, integer and double C expressions into the argument of ET and its siblings.
• The string %q(...) works like %s(...) but adds backslashes before characters that are special to Tcl/Tk.

Including External Tcl/Tk Scripts In A C Program

In the sample programs seen so far in this article, Tcl/Tk code in an ET function was used to construct the main window. This works fine for the examples, since their windows are uncomplicated and can be constructed with a few lines code. But in a real application, or even a more complex example, the amount of Tcl/Tk code needed to initialize the program's windows can quickly grow to hundreds or thousands of lines. It is impractical and irksome to put this much code into an ET statement, so the ET system provides another way to get the job done: the ET_INCLUDE statement.

The ET_INCLUDE statement is similar in concept to the #include statement in the C preprocessor. Both take a filename as their argument, and both read the named file into the original source program. The ET_INCLUDE statement expects its file to be pure Tcl/Tk code, though. Its job is to turn the Tcl/Tk source into a form that the C compiler can understand, and to arrange for the Tcl/Tk to be executed when control reaches the ET_INCLUDE statement.

An example may help to clarify this idea. In the decimal clock program (way back at the beginning of section ), there are 7 lines of Tcl/Tk in an ET function used to create the application's main window. Now suppose we move those 7 lines of Tcl/Tk into a separate file named dclock.tcl. Then we could replace the ET function with an ET_INCLUDE statement that references the new file like this:

  void main(int argc, char **argv){
    Et_Init(&argc, argv);
    ET_INSTALL_COMMANDS;
    ET_INCLUDE( dclock.tcl );
    Et_MainLoop();
  }

Well, almost like an ET function. There are a couple of minor differences. The ET_INCLUDE does not understand the various %s(...) substitutions as ET does. Also, ET_INCLUDE is a true procedure, not a function. It doesn't return a value like ET so you can't use an ET_INCLUDE in an expression.

It is important to understand the difference between an ET_INCLUDE statement like this

    ET_INCLUDE( dclock.tcl );

    ET( source dclock.tcl );

The ability to read an external Tcl/Tk script and make it part of the executable program is an important feature of ET. But while you are developing and testing a program, it is sometimes convenient to turn this feature off and to have the application read its scripts at run-time instead of compile-time. That way, you can make changes to the Tcl/Tk script and rerun your program with the changes, but without having to recompile. You can do this using the -dynamic option to the et2c proprocessor. Whenever you run et2c with the -dynamic command-line option, it effective turns instances of the statement

    ET_INCLUDE( filename.tcl );

    ET( source filename.tcl );

There is just one other feature of the ET_INCLUDE statement that we need to discuss before moving on, and that is the algorithm it uses to locate the Tcl/Tk source code files. Just like the C preprocessor's #include statement, the ET_INCLUDE mechanism can include files found in other directories.

The et2c preprocessor always looks first in the working directory for files named by an ET_INCLUDE statement. If the file is found there, no further search is made. But if the file is not found, then et2c will also look in all directories named in -I command line options. For example, if you run et2c like this:

    et2c -I../tcl -I/usr/local/lib/tcl app.c >app_.c

    ET_INCLUDE( setup.tcl );

Global Variables In ET

The et.o library for ET defines three global C variables that are sometimes of use to programmers. In addition, Et_Init creates two new global Tcl/Tk variables that many programs find useful. This section will describe what all of these variables do, and suggest ways that they can be used.

Global C Variables Created By ET

Perhaps the most useful of the global variables available in ET is Et_Interp. This variable is a pointer to the Tcl/Tk interpreter, the one created by Et_Init and used to execute all Tcl/Tk commands within the program. The Et_Interp variable has the same value as the interp formal parameter found in every ET_PROC function.

The Et_Interp variable is useful because you may often want to call C routines in the Tcl/Tk library, and most of these routines require a pointer to the interpreter as their first parameter. For instance, suppose in the initialization code you want to create a link between the global C variable nClients and a Tcl/Tk variable by the same name. Using the Et_Interp variable as the first parameter to the Tcl function Tcl_LinkVar, you could write:

   Tcl_LinkVar(Et_Interp,"nClients",(char*)&nClients,TCL_LINK_INT);

Perhaps the second most useful global varible is Et_Display. This variable contains the Display pointer required as the first argument to most Xlib routines. It is used by daring, down-to-the-bare-metal programmers who like to call Xlib directly.

Here's an example. Suppose you want to create a new Tcl/Tk command, PitchedBell, that makes the X terminal emit a beep with a pitch specified by its sole argument. Once such a command is implemented, then the following Tcl/Tk code would emit a single tone at the pitch of concert A:

   PitchedBell 440

   foreach pitch {784 784 784 659} {
      PitchedBell $pitch
      after 200
   }

   #include <tk.h>   /* Will also pickup <Xlib.h> */

   ET_PROC( PitchedBell ){
      XKeyboardControl ctrl;   /* For changing the bell pitch */

      if( argc!=2 ){
        interp->result = 
          "Wrong # args.  Should be: ``PitchedBell PITCH''";
        return ET_ERROR;
      }
      ctrl.bell_pitch = atoi( argv[1] );
      XChangeKeyboardControl(Et_Display,KBBellPitch,&ctrl);
      XBell(Et_Display,0);
      XFlush(Et_Display);
      return ET_OK;
   }

The third and final global C variable in ET is Et_MainWindow. This variable is a pointer to the Tcl/Tk structure that defines the application's main window. Back in the days of Tk3.6, several Tcl/Tk library functions required this value as a parameter. But the Tcl/Tk library interface changed in the move to Tk4.0, so that the main window pointer is no longer required. Hence, the Et_MainWindow variable isn't used much any more. It has been kept around as an historical artifact.

Tcl/Tk Variables Created By ET

Besides the 3 global C variables, ET also provides two Tcl/Tk variables that are of frequent use: cmd_name and cmd_dir. The cmd_name variable contains the name of the file holding the executable for the application, and cmd_dir is the name of the directory containing that file.

The cmd_name and cmd_dir variables are useful to programs that need to read or write auxiliary data files. In order to open an auxiliary file, the program needs to know the files pathname, but it is not a good idea to hard-code a complete pathname into the program. Otherwise, the auxiliary file can't be moved without recompiling the program. By careful use of cmd_name and/or cmd_dir, we can arrange to have auxiliary files located in a directory relative to the executable, rather that at some fixed location. That way, a system adminstrator is free to move the auxiliary file to a different directory as long as the executable moves with it.

For example, suppose you are writing a program named acctrec that needs to access a data file named acctrec.db. Furthermore, suppose the data file is located in a directory ../data relative to the executable. Then to open the data file for reading, a program could write:

  char *fullName = ET_STR( return $cmd_dir/../data/$cmd_name.db );
  FILE *fp = fopen(fullName,"r");

Reading From Standard Input

There's one last feature of ET that we haven't discussed: the Et_ReadStdin procedure. If this procedure is called (with no arguments) in between the calls to Et_Init and Et_MainLoop, ET will make arrangements to read all data that appears on standard input and interpret that data as Tcl/Tk commands.

You can use the Et_ReadStdin to implement the interactive wish interpreter for Tcl/Tk. The code would look like this:

  main(int argc, char **argv){
    Et_Init(&argc,argv);
    Et_ReadStdin();
    Et_MainLoop();
  }

The second difference between wish and the etwish program shown above is that etwish is always interactive. It will not read a script from a file given as a command line argument like standard wish will. But we can remove that difference using a little more code.

  main(int argc, char **argv){
    Et_Init(&argc,argv);
    if( argc>2 && (strcmp(argv[1],"-f")==0 || strcmp(argv[1],"-file")==0) ){
      ET( source "%q(argv[2])" );
    }else if( argc>1 ){
      ET( source "%q(argv[1])" );
    }else{
      Et_ReadStdin();
    }
    Et_MainLoop();
  }

Compiling ET Applications

We've already discussed the basics of compiling ET applications back in section when we put together the Hello, World! example. Basically, all you do is preprocess your source files with et2c and then run the results through the C compiler. But that synopsis omits a lot of detail. This section fills in the missing information.

Compiling ET Itself

But before we begin talking about how to compile ET applications, we need to first mention how to compile ET itself -- the et2c preprocessor and the et.o library. (If you have one of the platforms supported by the CD-ROM in the back of this book, then you already have precompiled versions of et2c and et.o and can skip this step.)

The source code to the et2c preprocessor is contained in a single file named et2c.c. The preprocessor is written in highly portable K&R C and should compile without change on just about any 32-bit architecture. All you have to do is this:

  cc -O -o et2c et2c.c

Compiling the et.o library is a little more problematic, but still not difficult. There are three steps. First you have to select an appropriate source code file. There are different versions of the source code (sometimes radically different) depending on which version of Tcl/Tk you are using. For Tk version 3.6, choose et36.c. For Tk version 4.0, choose et40.c. For Tk version 4.1 on UNIX and X11, choose et41.c. Your ET distribution may also have other options, such as versions for MS-Windows or Macintosh, or versions with built-in support for various Tcl extensions.

Let's suppose, for the sake of discussion, that you selected the source file et41.c. The next step is to preprocess this file using et2c. This step is a little tricky because we have to use the -I option to et2c to tell the preprocessor where to find the Tcl/Tk startup scripts.

Recall that the stardard Tcl/Tk interpreter program, wish, reads and executes a series of Tcl/Tk scripts when it first starts up. These scripts set up default widget bindings, create procedures for handling menus, and so forth. The names of the directories from which these scripts are loaded are hard-coded in the wish executable. There are about 15 different startup scripts (the number varies from one version of Tcl/Tk to the next) and wish will not run without them.

But ET applications don't read the startup scripts at run-time. Instead, a series of ET_INCLUDE statements inside the Et_Init function bind the startup scripts into an ET executable at compile-time. This feature is what enables ET applications to run on machines that do not have Tcl/Tk installed.

It is because of 15 or so startup scripts included by ET_INCLUDE statements in the ET library that we have to preprocess the library source code using et2c. But we also have to tell et2c what directories to use when searching for the startup scripts. If Tcl/Tk has already been installed on your system, then you can find out the names of the startup script directories by executing the following wish script:

  #! wish
  puts $tk_library
  puts $tcl_library

  et2c -I/usr/local/lib/tcl -I/usr/local/lib/tk et41.c >et.c

After preprocessing the library source code, all that remains is to compile it. The library references the <tk.h> header file, which in turn references <tcl.h>, so you may have to add some -I options to the compiler command line to specify the directories where these header files are located. The following is typical:

  cc -c -o et.o -I/usr/include/tcl -I/usr/include/tk et.c

Compiling The Application Code

Once you get et2c and et.o compiled, the hard work is done. To build your application, simply run each source file through the et2c preprocessor before compiling it, and add the et.o library with the final link. For example, the steps to compile a program from two source files, appmain.c and appaux.c, are the something like following on most systems:

   et2c appmain.c >temp.c
   cc -c temp.c -o appmain.o
   et2c appaux.c >temp.c
   cc -c temp.c -o appaux.o
   cc appmain.o appaux.o et.o -ltk -ltcl -lX11 -lm

If you're using a Makefile, you might want to redefine the default rule for converting C source code into object code to incorporate the et2c preprocessor step. Like this:

    .c.o:
          et2c $< >temp.c
          cc -c -o $@ temp.c

Turning Off Script Compression In The Preprocessor

The et2c preprocessor attempts to save memory and improve performance of your application by removing comments and unnecessary spaces from the Tcl/Tk code inside ET functions and loaded by ET_INCLUDE statements. This mechanism works well most of the time, but it is not foolproof. It is theoretically possible for a valid Tcl/Tk script to be corrupted by et2c's compression attempts. If you experience trouble, and suspect that et2c is messing up your Tcl/Tk code, then you can turn script compression off using the -nocompress command line option.

Compiling Using An Older K&R Compiler

If it is your misfortune not to have an ANSI C compiler, you can still use ET. The source code to et2c is pure K&R C and should work fine under older compilers. The source code to et.o is another matter. To compile the library using an older compiler you need to first give a -K+R option to et2c and then give a -DK_AND_R option to the C compiler:

  et2c -K+R -I/usr/local/lib/tcl -I/usr/local/lib/tk et40.c >et.c
  cc -DK_AND_R -I/usr/include/tcl -I/usr/include/tk -c et.c

Other ET Sample Programs

Besides the very simple Hello, World! and decimal clock programs presented above, ET is distributed with a number of non-trivial sample programs. This section will briefly overview what several of these example programs do, and why ET was important to their implementation. We won't try to explain the details of how the programs work, though. You can figure that out for yourself by looking at the source code.

The Color Chooser

There is a color chooser tool for X11 called color. The sources to color are in the files color.c and color.tcl. A screen image of the program is shown in figure .

The X11 Window System supports displays with over 280 quadrillion distinct colors (48 bits per pixel). But from this vast number, a few hundred colors are assigned English names like blue or turquoise or peachpuff. All the rest are given arcane hexadecimal designations like #b22cd8517f32. It is best to use colors with English names whenever possible.

The purpose of the color program it to help select colors with English names. At the top of the application is large swatch showing one of the 280 quadrillion X11 colors, together with either its English name (if it has one) or its hexadecimal value. Sliders on the lower left side of the window allow the user to vary the color of the swatch by changing various color components. On the lower right side of the window are six smaller swatches that show colors with English names that are similar to the color in the main swatch. Moving any of the six color component sliders causes the colors in all swatches, and the other sliders, to update in real time. Clicking on any of the smaller swatches transfers its color to the main swatch, updating all of the sliders and swatches appropriately.

In theory, there is nothing to prevent the color program from being coded in pure Tcl/Tk, but in practice, such an implementation would be much too slow. For this reason, two key routines are coded in C. The ET_PROC command ChangeComponent is called whenever one of the color component sliders is moved. This routine moves the other sliders, changes the color of the main swatch, then computes close colors for the smaller swatches. Another ET_PROC command named ChangeColor is called whenever the user clicks on one of the smaller swatches. This routine changes the color of the main swatch, then updates the sliders and the smaller swatches accordingly.

The VT100 Terminal Emulator

The example named tkterm implements a VT100 terminal emulator. The tkterm program can be used as a direct replacement for the more familiar emulator programs xterm or rxvt.

The sources for tkterm are contained in three separate files. The main procedure is in tkterm.c. Tcl/Tk for constructing the main window for the application is in tkterm.tcl. Finally, the file getpty.c takes care of the messy details of allocating a pseudo-TTY for the emulator and invoking a shell in the pseudo-TTY. (Much of the code in getpty.c was copied from rxvt.)

The tkterm program simulates the VT100 display using an ordinary Tcl/Tk text widget. C routines in tkterm.c interpret the characters and escape sequences coming into the program and use ET functions to insert characters into their proper places within the text widget. The tkterm.c file is almost 1000 lines long, and is mostly devoted to interpreting the VT100 escape codes.

The tkterm program is an example of an application that could not be coded in pure Tcl/Tk, since Tcl/Tk has no provisions for dealing with pseudo-TTYs or TTYs in raw mode. But even if it could, we would probably still want to use some C code, since it seems unlikely that a Tcl/Tk script would be able to process the VT100 escape sequences efficiently.

A Real-Time Performance Monitor For Linux

The perfmon program is a system performance monitor for the Linux operating system. It uses bar graphs to shows the amount of memory, swap space, CPU time currently being used. The display is updated 10 times per second. There are two source code files for this application: perfmon.c and perfmon.tcl.

The main display of the perfmon program is implemented using a Tcl/Tk canvas widget. But for efficiency's sake, the logic that computes the current memory, swap space, and CPU usages is all coded in C. The C code obtains the system performance data by reading the files /proc/stat and /proc/meminfo. It then processes this information into the desired preformance measurements and makes appropriate changes to the Tcl/Tk bar graphs using ET function calls.

On a 90MHz Pentium and with an update frequency of 10 times per second, the prefmon program uses a negligible amount of the CPU time. So in addition to being a nifty desktop utility for a Linux workstation, this example demonstrates that Tcl/Tk applications can be very efficient.

An ASCII Text Editor And A File Browser

The two programs tkedit and browser implement, respectively, an ASCII text editor and a UNIX file browser utility. Source code to these programs is in the files tkedit.c, tkedit.tcl, browser.c and browser.tcl.

Both of these programs could just as well have been implemented as pure Tcl/Tk scripts, with no loss of features or performance. (In fact, the browser can be used as pure script by invoking the browser.tcl using wish.) But, sometimes you want a program to be a real executable, not a script. For instance, you may want to be able to run the program on machines that do not have Tcl/Tk installed. Or, perhaps you want the programs to run on machines that have a different, incompatible version of Tcl/Tk installed.

The tkedit and browser programs are examples of how to convert a pure Tcl/Tk script into a stand-alone program using ET. The idea is very simple. Your C code simply initializes ET, invokes your script using a single ET_INCLUDE statement, and then enters the event loop. Like this:

  void main(int argc, char **argv){
    Et_Init(&argc,argv);
    ET_INCLUDE( browser.tcl );
    Et_MainLoop();
  }

Using ET To Build MS-Windows And Macintosh Applications

ET, like Tcl/Tk, was originally written to support the open X11 windowing system only. But nowadays, people often need to write applications for popular proprietary windowing systems such as Windows95 or Macintosh. Beginning with release 4.1, Tcl/Tk supports these proprietary products, and so does ET. (Actually, only Windows95 is supported as of this writing. The author has no access to a Macintosh system on which to develop and test a Macintosh port.)

On a Macintosh, ET applications that don't call Xlib directly should compile with little or no change. The Mac won't support the Et_ReadStdin routine, or the Et_Display global variable, but then again, neither of these make much sense on a Mac. The application will compile in much the same way as it does for X11, except that you should use the et41mac.c source file to the et.o library.

More change is required to support Windows95, however. The Windows version of ET doesn't contain either Et_Init or Et_MainLoop. Instead these functions will be invoked automatically. An ET program for Windows should contain a single Et_Main procedure definition to do all its setup, and nothing more. Hence, if your application used to look like this:

  void main(int argc, char **argv){
    Et_Init(&argc,argv);
    /* Your setup code here */
    Et_MainLoop();
  }

  void Et_Main(int argc, char **argv){
    /* Your setup code here */
  }

Summary And Acknowledgements

Over the past two years, many people have used ET to build programs from a mixture of Tcl/Tk and C. Projects have ranged in size from student programming assignments up to large-scale (100,000+ lines) commercial development efforts. In all cases, ET has proven to be an effective alternative to other GUI toolkits.

The original implementation of ET grew out of a programming contract from Lucent Technologies (formerly AT&T Bell Laboratories). Lucent Technologies was in turn funded under a contract from the United States Navy. Many thanks go to Richard Blanchard at Lucent Technologies and to Charlie Roop, Dave Toms and Clair Guthrie at PMO-428 for allowing ET to be released to the public domain.

The author can be reached at:

D. Richard Hipp
Hipp, Wyrick & Company, Inc.
6200 Maple Cove Lane
Charlotte, NC 28269
704-948-4565
drh@vnet.net