Instructions For Writing Tclets

Here is a cookbook for how to write your first tclet:

The simplest Tk program is shown below. Create a file named simple.tcl with this program in it.
button .b -text "Hello, world!"
pack .b
Create a file named simple.html with the following HTML in it:
<p>Here is my first embedded tclet:</p>
<p><embed src="simple.tcl" width=140 height=30></p>

That's IT. You're done. This page should look like what you've created above. A full version of the tclet html source template is as follows to work with both NPAPI and ActiveX based browsers, and to specify the plugin page (for those without the plugin already installed):

  <OBJECT
	ID="PluginHostCtrl"
	CLASSID="CLSID:14E78123-A693-4F27-B6EE-DDDE18F93D3A"
	WIDTH="400"
	HEIGHT="150"
  >
	  <PARAM name="type" value="application/x-tcl"/>
	  <PARAM name="pluginspage" value="http://www.tcl.tk/software/plugin/"/>
	  <PARAM name="src"  value="http://path/to/myTclet.tcl"/>
	  <PARAM name="someArg" value="itsValue"/>

	<EMBED
	  TYPE="application/x-tcl"
	  PLUGINSPAGE="http://plugin.tcl.tk/"
	  FRAMEBORDER="NO"
	  WIDTH="400"
	  HEIGHT="150"
	  SRC="http://path/to/myTclet.tcl"
	  someArg="itsValue"
	>
	</EMBED>
  </OBJECT>

Safe Tcl and Safe Tk

These instructions need to be updated for version 2 and 3 features.

You can test your Tclet by running it in the wish shell; you don't have to run it inside Netscape. However, when you are running in the Tcl plugin you have a restricted set of Tcl commands for security reasons. The following Tcl commands are not available:

bell - ring terminal bell
cd - change directory
clipboard - access CLIPBOARD selection
exec - run programs
glob - match file names in a directory
grab - grab the cursor
menu - display a menu
pwd - query current directory
send - send Tcl commands to other Tk applications
socket - open a network socket
tk - set/query Tk application name
tkwait - block on events. You can use vwait to wait for variables to change.
toplevel - create toplevel windows.
wm - window manager control

Stand Alone or Plugin?

You can detect if you are running in the plugin by testing for the existing of the embed_args variable. This is an array whose values come from the <embed> tag in the document. For example, $embed_args(src) contains the name of the Tcl script for the applet. You can put whatever NAME=VALUE pairs you want in the <embed> tag. The plugin looks at SRC, WIDTH, and HEIGHT. Any others are for your own use.

Other Tcl variables defined especially for the plugin are:

plugin(version): String describing the plugin version such as "2.0"
plugin(patchLevel): String describing the plugin patch level, such as "2.0.1"

Window sizing

The plugin turns off geometry propagation for the main window. All it does is:

pack propagate . false

This helps make the window the same size as the HTML width and height specifiers in the <embed> tag. Tclets you write should still work if they depend on the grid geometry manager, but in that case, you'll have to size the window yourself.

grid propagate . false