@node Tcl/Tk, Term/Cap, Tcl, Module List
@unnumberedsec 

Tcl::Tk - Extension module for Perl giving access to Tk via the Tcl extension

@unnumberedsec DESCRIPTION

The Tcl::Tk submodule of the Tcl module gives access to the Tk library.
It does this by creating a Tcl interpreter object (using the Tcl extension)
and binding in all of Tk into the interpreter (in the same way that
@strong{wish} or other Tcl/Tk applications do).

@unnumberedsubsec Access to the Tcl and Tcl::Tk extensions

To get access to the Tcl and Tcl::Tk extensions, put the commands
    require Tcl;
    use Tcl::Tk;

near the top of your program. The Tcl extension does not alter your
namespace at all (hence the "require"). The Tcl::Tk extension imports
the widget and other Tk commands into your namespace (hence the "use").

@unnumberedsubsec Creating a Tcl interpreter for Tk

To create a Tcl interpreter initialised for Tk, use
    $i = new Tcl::Tk (DISPLAY, NAME, SYNC);

All arguments are optional. This creates a Tcl interpreter object $i,
binds in all the additional Tk/Tcl commands and creates a main toplevel
window. The window is created on display DISPLAY (defaulting to the display
named in the DISPLAY environment variable) with name NAME (defaulting to
the name of the Perl program, i.e. the contents of Perl variable $0).
If the SYNC argument is present and true then an @emph{XSynchronize()} call is
done ensuring that X events are processed synchronously (and thus slowly).
This is there for completeness and is only very occasionally useful for
debugging errant X clients (usually at a much lower level than Tk users
will want).

@unnumberedsubsec Entering the main event loop

The Perl command
    MainLoop;

enters the Tk event loop. (Notice that the name differs from the equivalent
command in TkPerl5: names of commands in the Tcl and Tcl::Tk extensions
closely follow the C interface names with leading Tcl_ or Tk_ removed.)

@unnumberedsubsec Creating widgets

If desired, widgets can be created and handled entirely by Tcl/Tk code
evaluated in the Tcl interpreter object $i (created above). However,
there is an additional way of creating widgets in the interpreter
directly from Perl. The names of the widgets (frame, toplevel, label etc.)
are exported as Perl commands by the Tcl::Tk extension. The initial
"use Tcl::Tk;" command imports those commands into your namespace.
The command
    $l = label(".l", -text => "Hello world);

(for example), executes the command
    $i->call("label", ".l", "-text", "Hello world);

and hence gets Tcl to create a new label widget .l in your Tcl/Tk interpreter.
Since Tcl/Tk then creates a command ".l" in the interpreter and creating a
similarly named sub in Perl isn@'t a good idea, the Tcl::Tk extension uses a
kludge to give a slightly more convenient way of manipulating the widget.
Instead of returning the name of the new widget as a string, the above
label command returns a Perl reference to the widget@'s name, blessed into an
almost empty class. Perl method calls on the object are translated into
commands for the Tcl/Tk interpreter in a very simplistic fashion. For example,
the Perl command
    $l->configure(-background => "green");

is translated into the command
    $i->call($$l, "configure", "-background", "green");

for execution in your Tcl/Tk interpreter. Notice that it simply dereferences
the object to find the widget name. There is no automagic conversion that
happens: if you use a Tcl command which wants a widget pathname and you
only have an object returned by @emph{label()} (or @emph{button()} or @emph{entry()}
or whatever) then you must dereference it yourself.

@unnumberedsubsec Non-widget Tk commands

For convenience, the non-widget Tk commands (such as destroy, focus, wm,
winfo and so on) are also available as Perl commands and translate into
into their Tcl equivalents for execution in your Tk/Tcl interpreter. The
names of the Perl commands are the same as their Tcl equivalents except
for two: Tcl@'s pack command becomes tkpack in Perl and Tcl@'s bind command
becomes tkbind in Perl. The arguments you pass to any of these Perl
commands are not touched by the Tcl parser: each Perl argument is passed
as a separate argument to the Tcl command.

@unnumberedsubsec AUTHOR

Malcolm Beattie, mbeattie@@sable.ox.ac.uk

