Tcl/Tk Interface

Tcl/Tk is a programming language that is used by uDraw(Graph) for the realization of the user interface. General information about Tcl/Tk is for example provided by the Tcl Developer Xchange.

uDraw(Graph) offers a Tcl/Tk interpreter that is accessible by the API. This interface can be used by application programmers to create their own application specific windows. The uDraw(Graph) Tcl/Tk interface is able to execute any Tcl/Tk 8.4 script in the same way as a "wish shell" (i.e. Tcl/Tk execution environment) can do. So the application program does not need to embed its own "wish shell" (or a separate Tcl/Tk interpreter) in order to use Tcl/Tk, because that function is offered by uDraw(Graph). This way the application does not need to deal with an additional toolkit to realize a graphical front-end. All it has to do to implement a graphical user interface is sending API commands with Tcl/Tk scripts to the API.

Tcl/Tk scripts can be sent either to uDraw(Graph) with API command tcl(eval(string)), where "string" is the Tcl/Tk script, or the script can be loaded from a file with API command tcl(eval_file(filename)). Sending the complete script via the API with command tcl(eval(string)) is only useful for small scripts or Tcl/Tk function calls, because the string parameter 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). These restrictions are not necessary for Tcl/Tk scripts loaded from file with 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 reasonable approach 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 start time of uDraw(Graph). During run-time, particular Tcl/Tk functions of the script can be called by sending API command tcl(eval(string)).

The "uDrawGraph" command in Tcl/Tk

The uDraw(Graph) Tcl/Tk interpreter that can be accessed by the API has all the features of a usual Tcl/Tk 8.4 interpreter (i.e. everything a "wish shell" can do), plus one additional object (or function) "uDrawGraph" that supports the two methods (or parameters) "tcl_answer" and "command", see below. The "uDrawGraph" 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 uDraw(Graph) from inside the script.

Note: the user interface and graph visualization of uDraw(Graph) cannot be manipulated with the Tcl/Tk interface, so the "uDrawGraph" Tcl object does not offer the options you might expect. Precautions have been taken to avoid that the Tcl/Tk interface is misused to mesh with internal operations, disfigure dialog windows, etc. The only way to manipulate the uDraw(Graph) system is by communicating with the API.

Security Restrictions in Socket Server Mode

When uDraw(Graph) acts as a socket server by using the command-line option -server, an unknown application program can connect to the API at any time from any computer in the network. This can be a security problem, especially when all features of the Tcl/Tk interpreter would be offered to an unknown application. Therefore the uDraw(Graph) Tcl/Tk interface is restricted to a "safe Tcl" interpreter after entering the socket server mode. Safe Tcl is a mechanism for executing untrusted Tcl/Tk scripts safely and for providing mediated access by such scripts to potentially dangerous functionality. Please refer to the Tcl/Tk documentation about the restrictions for scripts in a safe Tcl/Tk interpreter. Make sure that you have read about security risks in the documentation of command-line option "-server".

Tcl command "uDrawGraph tcl_answer <string>"

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

By sending this API command with a Tcl/Tk script to the uDraw(Graph) API, 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 not possible to use the Tcl/Tk delimiters (i.e. "{" and "}") inside the string parameter of command "tcl_answer". So it is not allowed to use "...-command {uDrawGraph tcl_answer {Pressed}}" in the example above, although it is a valid Tcl/Tk expression.

Tcl command "uDrawGraph command <api-command>"

This Tcl command can be used in a Tcl/Tk script to send API commands directly to uDraw(Graph) without detour through the application. The result of the Tcl command in the Tcl/Tk script is the answer of the API command that was executed. So if the application has to be informed about the answer of the API command, then the Tcl/Tk script has to forward this result to the application using the Tcl command "uDrawGraph tcl_answer {...}".

By sending this API command with a Tcl/Tk script to the uDraw(Graph) API, a window with a button "Clear" will appear. After pressing this button, the API command menu(file(new)) will be executed by uDraw(Graph). This will clear the graph that is probably loaded.