Alpha_1 Programmers's Manual

Writing Alpha_1 Tcl/Tk Applications

Tcl/Tk Application Architecture

The diagram on the right illustrates the basic architecture of a Tcl/Tk based application. From the top down, first is the tcl code (that is interpreted) that describes the graphical user interface and the actions associated with events. Next is the implementation of whatever additional (alpha_1 specific) tcl commands have been added by the application or other alpha_1 libraries. This implementation itself is in C++. Then there is general C++ code specific to the application followed by the alpha_1 libraries. Finally there is the Tcl/Tk, X11, etc. system libraries.

The bottom four layers combine to make an executable program which contains an extended Tcl interpreter. Some of these extensions are general and provided by the alpha_1 library libTCL.a but others can be specific to the application.

To make an application out of this program, a set of tcl commands is interpreted at startup time. There are various ways of packaging up such applications (see below).

Alpha_1 Tcl Application Library

The Alpha_1 Tcl application library (libTCL.a) provides common code for writing Tcl based applications. The include files for this library on in $a$ai/tcl. The library itself is in $a$clib/tcl. There are two main categories of functionality: 1) implementation of Tcl commands for extending the Tcl interpreter, and 2) common code used in application initialization (i.e. the "main" program).

The most basic extension to the Tcl interpreter is the a1canvas command which creates a Tk widget that is a wrapper on the Alpha_1 display list window dl_window_type.

Other Tcl extensions are provided for the mi_type remote client interface to c_shape_edit and for applications that link the c_shape_edit library (libModel.a) directly into the application.

Writing the Main Program

There are currently four Tcl based applications in Alpha_1: a1wish, tk3d, shape3d, (all on $a$a1wishd) and fsketch ($a$fsketchd). The Tcl command extensions used by a1wish, tk3d, and shape3d are all in the libTCL.a library. Fsketch implements application specific Tcl extensions in its program directory.

A1wish is the most basic and is meant to be analogous to the standard Tcl/Tk wish program. Here is the main program:

#include 
#include 
#include 
#include 

/******************************************************************************
 * TAG( a1wish )
 */
void
main( int argc, char **argv )
{
    /* Check for Alpha1 display device command line args first. */
    override_display_device( NULL, argc, argv );
    
    Tk_Main( argc, argv, tcl_app_init );
    exit( 0 );
}

A1wish is used as follows:

	a1wish [tclfile] [-displaymode x11] [wish options]
	cat gui.tcl | a1wish ...

By using the Tk_Main routine from the Tk library, a1wish has the same command line options that the standard wish program does. A tcl file can be provided as the first argument or on stdin (like the "cat" example above). If a tcl file is provided (by file name or on stdin), the application reads and interprets the tcl file and then closes stdin. If no tcl file is provided, the application runs the Tcl interpreter interactively on the terminal.

The -displaymode option is an Alpha_1 option provided by the override_display function. The tcl_app_init function is provided by libTCL and creates the standard a1canvas Tcl commands.

As long as the set of Tcl command extensions is sufficient, the a1wish executable can be used to implement various interfaces and applications by just providing the Tcl code that defines the interface. Such applications can be installed by checking in the tcl file and setting the makefile variable TCLPROGRAMS. This uses the install-tcl-pgms script to install a csh script that runs a1wish with the tcl file provided on the standard input. However, many applications need application specific Tcl command extensions in addition to the standard "a1canvas" related commands.

Tk3d Main Program

The tk3d main program is an example of a slightly more complicated main program (some comments removed for brevity):

#include 
#include 
#include 
#include 

static int
app_init( Tcl_Interp *interp );

/******************************************************************************
 * TAG( tk3d )
 */
void
main( int argc, char **argv )
{
    /* Check for tcl file to load. Default is $b$datatcl/tk3d.tcl. */
    string_type tcl_file = tcl_file_to_load( "tk3d.tcl", argc, argv );

    /* Check for Alpha1 display device command line args first. */
    override_display_device( NULL, argc, argv );	
    a1_app_init_fn = app_init;

    /* If there is a tcl file to read, load it. */
    if ( tcl_file )
    {
	if ( create_tcl_interp( argc, argv, tcl_file ) != TCL_OK )
	{
	    eprintf( "Error in Tcl initialization file.\n" );
	    exit( 1 );
	}
	Tk_MainLoop();		/* No tcl top-loop. */
    }
    else	/* Run the tcl interpreter top-loop. */
	Tk_Main( argc, argv, tcl_app_init );

    exit( 0 );
}

/****************************************************************
 * TAG( app_init )
 */
static int
app_init( Tcl_Interp *interp )
{
    return tcl_mi_init( interp );
}

The first difference is that tk3d uses a different install strategy. Tk3d uses the libTCL functions tcl_file_to_load and create_tcl_interp to load a predetermined tcl file at startup instead of having a csh script run the interpreter and feed it a Tcl file. This looks more like a standard application. The X resource application name is the name of the executable and the class is set to "A1wish" so common X defaults can be set. This setup implements the following command line options:

    tk3d [gui.tcl | -tcl] [-displaymode x11] ...

    If there is no first argument (a tcl file or -tcl), then the default
    interface is loaded from $b$datatcl/tk3d.tcl. Does not run the Tcl toploop.

    tk3d -tcl ... - runs the Tcl/Tk interpreter without loading any tcl file.

    tk3d gui.tcl ... - Loads the file gui.tcl and does not run the Tcl/Tk toploop.

This is a more flexible setup, especially for applications that might want to run their own toploop (like c_shape_edit), but still be able to run the Tcl toploop for development purposes.

The other difference from a1wish is that tk3d sets the global:

    a1_app_init_fn = app_init;

This is a function pointer defined in the libTCL library. If set, this function is called at the end of the library tcl_app_init function to add application specific Tcl initialization. In this case we add the Tcl dl_mi command which allows tk3d to control connections to a remote c_shape_edit process (ala motif3d).

shape3d Main Program

Finally we look at the main program for shape3d which is a combination of Tcl/Tk based 3D viewing and c_shape_edit in one process. Here is part of the main program:

...

static int
app_init( Tcl_Interp *interp );

/*****************************************************************
 * TAG( shape3d )
 */
void
main( int argc, char **argv )
{
    ...

    /* If there is a tcl file to read, load it and then run the 
     * c_shape_edit interpreter top-loop. 
     */
    if ( tcl_file )
    {
	if ( create_tcl_interp( argc, argv, tcl_file ) != TCL_OK )
	{
	    eprintf( "Error in Tcl initialization file.\n" );
	    exit( 1 );
	}

	/* Stdin file handler feeds c_shape_edit toploop. */
	Tk_CreateFileHandler( 0, TK_READABLE, scl_handle_stdin, NULL );

	model_obj::print_banner();	/* Print initial prompt. */
	Tk_MainLoop();
    }
    else	/* Run the tcl interpreter top-loop. */
	Tk_Main( argc, argv, tcl_app_init );	/* Never returns. */

    exit( 0 );
}

This main program uses the command line arguments to either run the c_shape_edit toploop or the Tcl toploop. The options are the same as tk3d, but when there is a tcl file to load, it is loaded and then the c_shape_edit toploop is run (by using Tk_CreateFileHandler).

The fsketch main program is similar to shape3d but has additional application specific initializations.

Writing the Tcl Code

Currently, most of the Tcl code for these applications is in the $a$datatcl directory. The standard viewing menus and toolbars are implemented using [incr Tcl] which is an object oriented extension to standard Tcl.

Alpha_1 Programmer's Manual Home Page

alpha1@gr.utah.edu