Tcl-Tk Mode Help

Name:	Tcl-Tk Mode
Version:	3.4
Last update:	2020-05-27 14:28:45

Introduction
Basic usage
- Tcl Coloring
- Tcl Completion
The Tcl Menu
- Keyboard Shortcuts
Running Tcl code
Current Tcl interpreter
Tcl-Tk Shell Windows
Debugging with TclPro Debugger
Tracing function execution
Learning Tcl/Tk
Other Tcl-Tk Resources

Introduction

This mode is for editing Tcl code. You can edit code for internal use with Alpha (since a large part of Alpha is actually implemented in Tcl and the application contains its own Tcl interpreter), or use Alpha as an external editor for code destined for use with Tcl and Tk interpreters. The site https://www.tcl.tk distributes the tclsh and wish programs, as well as extensions, documentation etc.
When editing .tcl, .tk, .itk and .itcl files, the Tcl-Tk mode is automatically active, and provides a large range of useful, powerful editing functionality.
Beyond that, however, it also allows you to run your Tcl scripts, and modify those scripts while they are running.
This help file is primarily to show you how to write code for use with general Tcl, Tk interpreters. For much more information and specifics on writing Tcl code to extend the AlphaTcl library, please read the help file Extending Alpha. A very useful resource is the Alpha Developer Menu (click here to activate this package in Alpha).

Basic usage

The Tcl mode supports all the usual array of powerful Alpha editing features. These include:

auto-indentation
code templates and argument templates
command completion
variable completion
syntax coloring
file marking

Tcl Coloring

You can customize the syntax coloring in Tcl mode through the following preferences:

Command Color defines the color of all chosen commands. This may include Itcl, PseudoTcl, TclX and Tk keywords depending on the Recognise Itcl, Recognise PseudoTcl, Recognise TclX, and Recognise Tk preferences respectively.
Comment Color defines the color for Tcl comments.
Variables Color defines the color of words started by '$'. Tcl mode considers such words to be variables.
String Color defines the color for strings (enclosed in double quotes).
Alpha Color defines the color to use for Alpha's built-in commands.

Tcl Completion

Tcl mode offers a rich set fo completion procedures. It does its best to guess the context of a partial word and to complete it appropriately. It can detect, based on the surrounding context, that a word is a command, a procedure, a variable or an array: the hints it provides will then be different.
As with many other modes in Alpha, the basic keywords of the language are recognized (reserved keywords and Tcl Core commands). For instance, if you type arr then hit the completion key (which is ⌃-Tab by default), this is completed as array and, if you hit the completion key again, a dialog proposes all the subcommands supported by the [array] command (anymore, donesearch, exists, etc.).
Other sets of keywords can be completed depending on the Recognise Alpha, Recognise Itcl, Recognise PseudoTcl, Recognise TclX, and Recognise Tk preferences respectively.
Another nice feature (for AlphaTcl programmers) is the namespace completion. You can type the name of a namespace followed by two colons and then hit the completion key to display a dialog containing all the known procedures loaded in this namespace at the time of the execution. For instance, type alpha:: then hit the completion key. You can also type alpha:: followed by a few letters to get all possible completions starting with these letters: for instance, type alpha::li and the completion mechanism could offer a choice between alpha::library and alpha::listAlphaTclPackages (and maybe others depending on the context).
Tcl mode also has path completion support, very much like with a shell in a Terminal window. For instance, type something like

set path
~/

, then hit the completion key: all the files and folders of your home directory are proposed (Desktop, Documents, etc.). Choose one of them, say Documents, then hit the completion key again: then all the items contained in Documents are proposed. You can also type the first few letters of an item: if there is only one possibility, it is inserted automatically.
Another handy feature is the use of contractions. These are very short abbreviations for composite commands that get fully expanded. For instance, type a'g, then hit the completion key: this is immediately completed as array get. If you type a's, there are several possible completions and a dialog lets you select the one you want (array set, array size, array startsearch, or array statistics). If you type a'se (instead of just a's), then there is no ambiguity and you obtain array set.
All contractions use this syntax: a first letter, followed by a single quote, followed by one or more letters. The first letter is the initial of a composite command. The following letters are currently supported:

Letter	Command
a	array
b	binding
c	clock
d	dict
e	encoding
f	file
i	info
n	namespace
s	string
t	text
v	view

For instance, d'k gives dict keys and i'ex gives info exists.
Finally, Tcl mode also provides electric completions. Type, for instance, the word ifelse, then hit the completion key. You obtain the following template with bullets (use the tab key to jump from a bullet to the next one while you fill out the template):

if {•} {
	•
} else {
	•
} •

Other preset electrics include the words if, for, while, proc.
See the Better Templates Help for more fancy electric completions with named fields.

The Tcl Menu

When you open a file in Tcl mode, the Tcl Menu is automatically inserted into the menu bar. This menu contains a number of commands that are useful both for editing .tcl files, as well as interpreting them.

Keyboard Shortcuts

Most of the Tcl Menu items have pre-assigned keyboard shortcuts that you are able to adjust (or remove entirely). To change the shortcuts, select the command Tcl Menu ↣ Tcl-Tk Help ↣ Menu Shortcuts -- you will then be presented with a dialog containing the categories of menu commands.
Click here to display the currently available Tcl Mode bindings.

Running Tcl code

Open the Tcl Example file, and then try using the Tcl Menu ↣ Run menu item (Click on Save To Temp when prompted).
Else, starting from scratch, create a new .tcl file (e.g. test.tcl) and type the following:

    tk_messageBox -message "hello"

then, after saving the file, select the Tcl Menu ↣ Run menu command. You may be prompted for the location of a wish executable and, once selected, this script will be launced and you should see the hello message you have just requested.
If you want this same script to be easily accessible for future usage, you should create a Tcl project. Do this with Edit Projects followed by the New… button. You will then have easy access to this project from the tcl-tk project submenu of the Tcl menu. (Selecting them will startup a remote shell, source that .tcl file into it, and put Alpha into remote mode. Subsequent loading of code will go to the remote shell automatically, so you can use Alpha to edit and reload procedures in the remote shell, very simply.)
Once you have started running a Tcl file, you will notice that the top item in the Tcl menu changes to reflect the interpreter being used for that file. This means that any changes to Tcl/Tk scripts that are Evaluated (⌘L) will be sent to the wish application you just launched.
This means you can now add some more lines to the current window, select them and, with ⌘L, have the new lines take effect immediately. For example, type the following into a new line in your test.tcl:

    . configure -bg blue

then select all of that line and press ⌘L. The external Wish process should now have a blue background. In this way you can develop your Tcl/Tk applications interactively.

Current Tcl interpreter

The top item in the Tcl menu shows which interpreter will normally be used when you evaluate any command/script or generally carry out any Tcl-interpreter related action. If it shows Internal Interpreter, then the interpreter inside Alpha is the one in use. When you carry out a command like Tcl Menu ↣ Run, and under certain other circumstances, the current interpreter is automatically updated.

Tcl-Tk Shell Windows

The Tcl Menu ↣ Tcl-tk Shells submenu includes items for evaluating single lines of Tcl-Tk code via an Alpha shell window. Results are displayed in the shell window, no matter where the commands are evaluated.

Alpha's Tcl Shell: This shell window evaluates code using Alpha's internal interpreter. This is identical to the Tools ↣ Tcl Shell menu item. Note that changes to any AlphaTcl procedures or variables will likely affect the application's behavior, for better or worse!
Remote Tcl Shell: This shell window sends code to your remote Tcl interpreters. This effectively allows you to use this window to control and debug other Tcl/Tk interpreters (either on this machine or other machines). Try remoteTclShell.

See the Console Commands History section to learn how to browse through the commands history.
You can adjust the Keyboard Shortcuts for opening any of these shell windows by selecting the menu item Tcl Menu ↣ Tcl-Tk Help ↣ Menu Shortcuts.

Debugging with TclPro Debugger

On some platforms, Alpha comes integrated with the TclPro debugger for interactive debugging of Tcl scripts. To use this, open your main .tcl file (or, for example, open the Tcl Example file) and then select the menu item Debug in TclPro…. This will launch the debugger (as a subinterpreter inside AlphaTcl), and start it up with the current window. The TclPro debugger is a full, interactive debugger (you can set breakpoints, examine variables etc).
This is currently supported in Alphatk on Windows, but there is no reason it cannot be made to work seamlessly on any Unix or MacOS X system, or even MacOS Classic.

Tracing function execution

Tracing functions helps both to learn how they work and to debug them if they are not operating correctly. Unlike a conventional debugger that allows you to set breakpoints and single step through the code, tracing provides a complete snapshot of everything that took place inside a function. It does this by recording the parameters and results of every single operation that was carried out inside the given function. This information is dumped (in its entirety) into a window (or can be saved to file) so that you can look through it carefully to analyse what actually happened. Sometimes this is a much quicker way of working out what has gone wrong than the more labour-intensive single-stepping approach.
The following instructions on tracing when using Alpha with Tcl 8.6.10 make use of the Tcl Menu ↣ Tcl Tracing submenu commands.
Tracing operates in the same way whether you are tracing procedures internal to Alpha (i.e. you are developing or debugging parts of the editor itself) or whether you are tracing procedures inside external interpreters. Obviously, if you are tracing a procedure inside an external interpreter, you must first launch it so the code is running. Do this with the usual Run… or Debug in TclPro… menu selections.
Now, to start tracing, use either the Trace Tcl Proc… or Trace This Proc menu commands. The former will prompt you with a list of all available procedures, and the latter will start tracing the procedure in which the cursor currently lies.
Now, you should carry out some action that will cause the traced procedure to be executed (unless that is going to happen automatically due to some timer scripts). For example if the procedure is attached to a button-press or menu-selection, then click on that button, or make that menu selection. Assuming the procedure is reasonably long, you will probably notice a longer-than-usual delay before the action finishes. This is due to the overhead associated with execution tracing.
Once the procedure has completed, you can select Stop Tracing to turn off the tracing (otherwise the same procedure will be traced each time it is executed). Otherwise select Display Traces.
A new window will be opened in Alpha containing the results of the execution. Each individual Tcl command within the procedure will be shown, together with the results of that command. In this way, through some careful analysis, you can see exactly where things went wrong (alternatively, if the problem is less subtle and an error is thrown inside the procedure, you will be able to see that very clearly!).

Learning Tcl/Tk

There are some wonderful examples of Tcl/Tk on the Tcler's Wiki. These show off the power of Tcl with some very impressive demos achieved in only a hundred lines of code, for example:

Other Tcl-Tk Resources

Most of Alpha's functionality is contained in the AlphaTcl library of Tcl code. Alpha's core contains its own Tcl interpreter, so that you do not have to worry about Tcl being present or not on your machine. The current version of Alpha uses Tcl 8.6.10.
Most Tcl resources can be found through https://www.tcl.tk/, and the sources and related projects accessed through https://sourceforge.net/foundry/tcl-foundry/.
On the other hand, the Mac OS X system also contains standalone versions of Tcl and Tk. More recent versions may be available on the aforementioned sites.
The newsgroup news:comp.lang.tcl is both active, and full of very helpful people (including all the most active developers of Tcl and many Alpha developers) so it's often a good place to look for more information, and to coordinate work in specific areas.
Another useful resource is the Tcler's Wiki.
There are also a number of good books on Tcl/Tk, both for beginners and for experts.