Overview -> Reference -> API Reference -> Commands of Category Tcl

daVinci API Definition - Tcl/Tk Commands

On this page, API commands of the tcl category are described. This category covers all commands to use the daVinci Tcl/Tk interface. The commands of this category are enclosed by keyword tcl(...). Click here to get an overview of all API commands.

The daVinci Tcl/Tk Interface

General informations about Tcl/Tk are provided by SunScript.

The daVinci Tcl/Tk Interface can be used by application programmers to create their own application specific windows. The daVinci Tcl/Tk interface is able to execute any Tcl 7.4/Tk 4.0 script in the same way as a wish shell would do. So, the application program does not need to start its own wish (or another interpreter) to use Tcl/Tk, because "daVinci is the wish". This way, the application does not need to deal with another X-Window toolkit to realize its graphical front-end. All it has to do to implement a graphical user interface is sending API commands and Tcl/Tk scripts to the daVinci API.

Tcl/Tk scripts can either be sent to daVinci with API command tcl(eval(string)), whereby string is the Tcl/Tk script, or loaded from file with API command tcl(eval_file(filename)). Command tcl(eval(string)), i.e. sending the complete Tcl/Tk script via pipe, is only useful for small scripts or Tcl/Tk function calls, because the string argument has to fulfill the conventions for API strings, especially double quote characters inside the string have to be escaped (i.e. \") and newline or return characters are not allowed (use \n instead). This restriction is not required for Tcl/Tk scripts loaded from file with API command tcl(eval_file(filename)). For both commands, the result of the Tcl/Tk script will be immediately returned to the application with answer tcl_answer(...) as soon as the script is executed.

A possible scenario for using the Tcl/Tk interface is to save a script of Tcl/Tk functions in a file and execute it with API command tcl(eval_file(filename)) at startup time of daVinci. During runtime, the particular functions can be called by sending API command tcl(eval(string)).

The daVinci command in Tcl

The daVinci Tcl/Tk interpreter, accessible by the API, has all the features of a usual Tcl/Tk interpreter, e.g. the one in the wish shell, plus one additional object (or function) daVinci which supports the two methods (or parameters) tcl_answer and command, see below. The daVinci Tcl-object can be used in a Tcl/Tk script to send strings back to the application via the API or to send API commands directly to daVinci from inside the script.

Note: daVinci's user interface and graph visualization cannot be manipulated with the Tcl/Tk interface, so daVinci is not a Tcl object in the common sense. The daVinci system can only be accessed by using the commands of the API.

Tcl command daVinci tcl_answer string

This Tcl command can be used in a Tcl/Tk script to send an arbitrary string back to the application. daVinci will redirect the argument string via the API to the application which will receive an answer tcl_answer(...) from the API. This feature is useful to implement callbacks.

Example:

tcl(eval("button .b -text Hello -command {daVinci tcl_answer Pressed} ; pack .b"))

By sending this API command (containing a Tcl/Tk script) to daVinci, a window with a button Hello will appear. The API will send answer tcl_answer("Pressed") back to the application as soon as the user presses the button.

Note: It is currently not possible to use Tcl delimiters (i.e. '{' and '}') inside the string argument of command tcl_answer. E.g. "...-command {daVinci tcl_answer {Pressed}}" is not allowed in the example above, although it is a valid Tcl expression.

Tcl command daVinci command api-command

This Tcl command can be used in a Tcl/Tk script to send API commands directly to daVinci without detour through the application. The result of the Tcl command in the Tcl/Tk script is the answer of the executed API command, so the script may need to forward this result to the application (e.g. by using Tcl command daVinci tcl_answer {...}), if the application need to be informed about this event.

Example:

tcl(eval("button .b -text Clear -command {daVinci command menu(file(new))} ; pack .b"))

By sending this API command (containing a Tcl/Tk script) to daVinci, a window with a button Clear will appear. After pressing this button, the API command menu(file(new)) will be executed by daVinci which will clear a probably loaded graph.

Documentation of the Category Commands:

tcl(eval(string))

-> Returns answer tcl_answer(...)!

Sends a Tcl/Tk script string to daVinci's Tcl/Tk interface and waits for the result (i.e. return value) of this script which can be found in the string of the API answer tcl_answer(...), sent back to the application as soon as the script has finished. daVinci is blocked as long as the Tcl-script is executed.
Note: The Tcl/Tk script in string must not contain return or newline characters and all double quotes inside the string need to be escaped (i.e. \").

tcl(eval_file(filename))

-> Returns answer tcl_answer(...)!

Same as API command tcl(eval(...)) above, but the Tcl/Tk script is read from the specified file rather than taken from the string parameter. So, the Tcl/Tk script does not need to be transfered via pipe. Use this API command for large scripts or if you cannot fulfill the API convention for strings (i.e. no return/newline characters and no unescaped double quotes in the Tcl/Tk script).

daVinci V2.1 Online Documentation - Page update: June 15, 1998