sourcenav-6.0.tar.gz

Tcl/Tk has proven to be an excellent language for building small programs that require a Graphical User Interface (GUI). However, it is often inadequate for use in large commercial applications for a number of reasons: * Execution speed is usually too slow for serious computation. * Complex data structures are difficult to construct. * The lack of structure and typing in the Tcl language complicates the development of large codes. * Tcl/Tk source code is easily read by the end user, making it hard for developers to protect proprietary algorithms. * Large Tcl/Tk programs typically consist of many separate files that must be correctly positioned within the target computer's file system. This can make the programs difficult to install, maintain and administer. To circumvent these problems, we have constructed a system that makes it easy for a C or C++ program to invoke and interact with Tcl/Tk. This allows data structures and compute-intensive algorithms to be coded in C or C++ while the GUI is coded in Tcl/Tk. It also allows the entire application to be compiled into a single stand-alone executable, which is not easily readable by the end user and which can be run on computers that do not have Tcl/Tk installed. We call our system "ET" for "Embedded Tk". 1. A Simple Example: ``Hello, World!'' The following is an ET implementation of the classic "Hello, World!" program: void main(int argc, char **argv){ Et_Init(&argc,argv); ET( button .b -text {Hello, World!} -command exit; pack .b ); Et_MainLoop(); } This example is short, but is serves to illustrate the basic structure of any ET application. The first line of the main() procedure is a call to the function Et_Init(). This function initializes the ET system by creating a Tcl/Tk interpreter, connecting to the X11 server, and creating a main window. The last line of main() implements the event loop. Everything in between constitutes setup code. In this example, the setup code is a short Tcl/Tk script contained within the special macro ET(). The et2c macro preprocessor will replace this ET() macro with C code that causes the enclosed Tcl/Tk script to be executed. Of course, there is nothing in this example that could not also be done by calling Tcl/Tk library routines directly, without the intervening ET abstraction. The advantage of using ET is that it makes the interface between C and Tcl/Tk considerably less cumbersome and error-prone, allowing the programmer to focus more mental energy on the algorithm and less on the syntax of the programming language. 1.1 Compiling ``Hello, World!'' To compile the hello world example, we must first process the source file using the et2c macro preprocessor, then link the results with the et.o library. Suppose the example code is contained in the file hello.c. Then to compile the example (on most systems) requires the following steps: et2c hello.c >hello_.c cc -o hello hello_.c et.o -ltk -ltcl -lX11 -lm Assuming it is statically linked, the resulting executable file hello contains everything needed to run the program: the Tcl/Tk interpreter, the startup scripts and the application code. The program can be moved to other binary-compatible computers and executed there even if the other computers do not have Tcl/Tk installed. Additional information is provided below. 1.2 How to obtain sources and documentation Complete sources to the et2c macro preprocessor and et.o library comprise less than 2000 lines of code, including comments. These sources, together with source code to all example programs discussed below, are available for anonymous FTP from ftp.vnet.net in the directory /pub/users/drh. A copy of this documentation is also available from the same FTP site. The documentation is available in either PostScript, HTML, or an ASCII text file. 2. A Summary Of Services Provided By ET The overall goal of ET is to simplify the interface between C and an embedded Tcl/Tk-based GUI. To this end, the ET system provides a number of services that aid in initializing the Tcl/Tk interpreter and in transferring data and control between Tcl/Tk and C. The services provided by ET are summarized here and described in more detail in subsequent sections. 2.1 Routines to initialization the Tcl/Tk interpreter The et.o library includes routines Et_Init() and Et_MainLoop() that initialize the ET package and implement the X11 event loop. A third routine Et_ReadStdin() allows standard input to be read and interpreted by the Tcl/Tk interpreter at run-time. 2.2 Macros to invoking Tcl/Tk from within C The ET() macro looks and works just like a function in C, except that its argument is a Tcl/Tk script instead of C code. ET() returns either ET_OK or ET_ERROR depending upon the success or failure of the script. Similar routines ET_STR(), ET_INT() and ET_DBL() also take a Tcl/Tk script as their argument, but return a string, an integer, or a double-precision floating point number instead of the status code. 2.3 A method to pass variable contents from C to Tcl/Tk Wherever the string %d(x) occurs inside an ET() macro, the integer C expression x is converted to ASCII and substituted in place of the %d(x). Similarly, %s(x) can be used to substitute a character string, and %f(x) will substitute a floating point value. The string %q(x) works like %s(x) except that a backslash is inserted before each character that has special meaning to Tcl/Tk. 2.4 Macros for creating new Tcl/Tk commands in C The macro "ET_PROC( newcmd ){ ... }" defines a C function that is invoked whenever the newcmd command is executed by the Tcl/Tk interpreter. Parameters argc and argv describe the arguments to the command. If a file named xyzzy.c contains one or more ET_PROC macros, then the commands associated with those macros are registered with the Tcl/Tk interpreter by invoking "ET_INSTALL_COMMANDS( xyzzy.c )" after the Et_Init() in the main procedure. 2.5 Macros for linking external Tcl/Tk scripts into a C program The macro "ET_INCLUDE( script.tcl )" causes the Tcl/Tk script in the file script.tcl to be made a part of the C program and executed at the point in the C program where the ET_INCLUDE macro is found. The external Tcl/Tk script is normally read into the C program at compile-time and thus becomes part of the executable. However, if the -dynamic option is given to the et2c macro preprocessor, loading of the external Tcl/Tk script is deferred to run-time. 2.6 Tcl/Tk return status macros The macros ET_OK and ET_ERROR are set equal to TCL_OK and TCL_ERROR. This often eliminates the need to put "#include " at the beginning of files that use ET. 2.7 Convenience variables ET defines three global C variables as a convenience to the programmer. Et_Interp is a pointer to the Tcl/Tk interpreter used by ET. Et_MainWindow is the main window of the ET application. Et_Display is the Display pointer required as the first argument to many XLib routines. ET also provides two global Tcl variables, cmd_name and cmd_dir. These contain the name of the executable and the directory where the executable is found. 3. Example 2: A Decimal Clock The preceding "Hello, World!" example program demonstrated the basic structure of an ET application including the use of the Et_Init() function to initialize the Tcl/Tk interpreter and the Et_MainLoop() function for implementing the X11 event loop. The following program will demonstrate additional aspects of the the ET system. 3.1 Source code for the decimal clock example /* This file implements a clock that shows the hour as ** fixed-point number X, such that ** ** 0.000 <= X < 24.000 ** ** X represents a fractional hour, not hours and minutes. ** Thus the time "8.500" means half past 8 o'clock, not ** ten minutes till 9. */ #include <time.h> void main(int argc, char **argv){ Et_Init(&argc,argv); ET_INSTALL_COMMANDS; ET(