/ gears / sp / software / opendx / tutorials / dxlink

Constructing Tcl/Tk Custom Interactors for Data Explorer

Data Explorer provides an adequate selection of generic user-interactors and control panels to accomodate the need to provide data and specifications to dx applications. In many instances, however, the functionality of a data explorer application can be inhanced by a discipline-specific Graphic User Interface (GUI). Often, it can also be advantageous to have the ability to perform calculations, generate displays and output, etc., external to data explorer that ultimately assist the user in adjusting and specifying application parameters back to data explorer.

The functionality of the provided module library can be extended through a macro-program facility that allows new modules to be created by grouping specific combinations of library modules. Alternately, new modules can be written in C, following well-defined guidelines, and added to local DX libraries. Additionally, one can author applications in C that link directly to either individual modules or entire applications in DX to extend DX functionality. These applications often do not use the native DX user interface and instead create a custom environment that provides a look and feel appropriate to a particular discipline or application. In this project, a facility available in DX called DXLink has been used in conjunction with a custom C program and Tcl/TK to create a unique, appropriate, graphic user interface for controlling a visualization application authored in DX.

Tcl (Tool Command Language) is a simple, yet powerful, platform independent (runs on Unix, Windows and Macintosh) scripting language that is easily imbedded into other applications. Tk is a window system toolkit that adds the functionality of creating and manipulating very sophisticated graphical user interfaces. Tcl/Tk scripts can run standalone, be linked with C programs, or extended over the Web. Tcl/Tk provides a simple, pragmatic, yet elegant, way of defining a graphic user interface that can control complex processes in a visually intuitive fashion. DXLink is a C programming interface that can be used to communicate with the Data Explorer user interface (dxui) or the Data Explorer executive (dxexec). Functions are provided to load programs, enable the setting and retrieval of named variables, control execution, handle errors, and define application-specific messaging. For the user interface, functions are also available to control window visibility and to load configuration files. For the executive, a function is provided to send arbitrary scripting-language commands. Support for X windows is built in but is not required.

A feature of Tcl/Tk is the availability of a custom command interpreter from within a C program, and an important element of this is the ability to extend the functionality of Tcl by adding custom commands that are defined as C procedures. The DXLink facility of DX provides an interface between a C program and the Data Explorer User Interface and the Data Explorer Executive. Functions are available to load and exit DX programs, set and retrieve named variables, control execution, handle errors, process configuration files and scripting commands, control window visibility, and define messaging between the C program and DX. Creating custom commands that Tcl/Tk interactors can access and use to control DX is accomplished by writing C procedures that invoke DXLink facilities and then adding those procedures to the repertoire of commands recognized by the Tcl/Tk interpreter. If only one possible DX application can be executed, it can be started in the C program and the control of it passed on to the Tcl/Tk interpreter. If more than one DX application is possible, specific individual invocations can be defined and added to the Tcl/Tk interpreter for user selection. Alternatively, a command can be created that uses a character string supplied by the user interface to determine which DX application to invoke.

Every user interaction to DX can be managed in this fashion, from simple, context-based scalar input to sophisticated launches of other application programs that recalculate massive streams of data that ultimately arrive back at DX for additional inspection and interaction. Indeed, visualization applications that are authored within a Tcl/Tk context can easily cascade through whatever analysis and display software a user feels is appropriate to the current insight they glean from the visualization process. For example, a C program can define, launch and manage a DX application. Depending on the resulting DX analysis, additional C programs, additional Tcl/Tk scripts, and additional applications (say, ArcInfo or Tecplot or even locally-written programs in any language) can be launched either serially or in parallel with the current application, on the local host or on remote resources, hidden or visable to the user. In this manner, the most appropriate visualization software environment for an application can be presented, even when that context is not known ahead of time and/or continually changes throughout the visualization process.

A Tcl/Tk--DX visualization application consists of three parts: 1.) a DX program that performs the appropriate analysis and display; 2.) a Tcl/Tk script that presents and manages the graphic user interface; and, 3.) a C program that defines the execution context and linkages between Tcl/Tk and DX. For this tutorial, an example provided with the Tcl/Tk distribution has been linked with an example provided with the Data Explorer distribution. The dx application is one which displays how the coastline of the southeastern United States will change with rising sealevel. The standard interactor would usually be a simple scalar number specifying a positive shift for sealevel. However, by providing a sliding vertical arrow as a Tcl/Tk interactor for specifying that value, an additional, visually intuitive, element is added to the transaction that reinforces the concept that sealevel is being moved up and down.

The Tcl/Tk code that creates this graphic user interface is reasonably straightforward. The only non-standard components are references to two commands, "dx" and "dxexit", which are two user-defined commands that have been added to a unique instantiation of the Tcl/Tk interpreter for this example. The C program, dxtcltk.c illustrates how these commands are added to Tcl. A simple script, mktcl, compiles this program, and provides the definition of the various libraries used. This particular script is for a Sun Solaris (2.6, Sun Ultra10 with Creator3D graphics), so it the various paths will need to be changed to reflect local installations on a another machine.

The Tcl procedure, "Tcl_GetVar", is used by the C program to access the value of sealevel being indicated by the user through the GUI. One needs to be sure to global all variables that will be accessed in this way. The sequence of execution begins with the command, "dxtcltk dxtest.tcl", for this example. The command, "dxtcltk", is the compiled and linked dxtcltk.c program. The argument, "dxtest.tcl", is the name of the Tcl/Tk file containing the GUI code that will be passed to the custom Tcl/Tk interpreter that has been created by the C program. The C program begins by starting Data Explorer and establishing an unique connection to it (multiple, concurrent, dx applications can be managed through their unique connection identifier). Then, via this connection, the appropriate dx application is loaded ( sealevel.netand its configuration file, sealevel.cfg). The topographic data file, southeastern_topo.dx is referenced in the .net file and read by dx when the C program sets an initial value of zero and toggles a cycle of execution. Then, the C program passes control to the procedure, "Tk_Main", along with the name of the Tcl file to interpret. Tk_Main, in turn, calls the C program back via the procedure, "TclAppInit". In this user-supplied procedure the two aforementioned commands, "dx" and "dxexit" are added to this instantiation of the Tcl interpreter. Once this procedure returns the only interaction between the Tcl file and the C program is via those newly-defined commands. If the GUI invokes the command, "dx", control is passed back to that portion of the C program that reads the value of sealevel being displayed by the GUI and sends it to data explorer, and subsequently toggles a cycle of execution for dx to process that new value. At the end of the analysis, the "dxexit" command will call the user-specified C procedure to terminate data explorer and quit the Tcl interpreter.

If you would like to look at another Tcl/Tk--Data Explorer project, here is a recent application in geographic visualization. Some additional, related, work is also available at the Penn State GeoVISTA Center.

Additional Data Explorer tips are being developed and added on an irregular basis.

Please send questions or suggestions about this web page to: sp@rcc.its.psu.edu

ASET | ITS | Penn State