\HeaderA{TclInterface}{Low-level Tcl/Tk Interface}{TclInterface}
\aliasA{\$.tclArray}{TclInterface}{.Rdol..tclArray}
\aliasA{\$<\Rdash.tclArray}{TclInterface}{.Rdol.<.Rdash..tclArray}
\aliasA{.Tcl}{TclInterface}{.Tcl}
\methaliasA{.Tcl.args}{TclInterface}{.Tcl.args}
\aliasA{.Tcl.args.objv}{TclInterface}{.Tcl.args.objv}
\aliasA{.Tcl.callback}{TclInterface}{.Tcl.callback}
\aliasA{.Tcl.objv}{TclInterface}{.Tcl.objv}
\aliasA{.Tk.ID}{TclInterface}{.Tk.ID}
\aliasA{.Tk.newwin}{TclInterface}{.Tk.newwin}
\aliasA{.Tk.subwin}{TclInterface}{.Tk.subwin}
\aliasA{.TkRoot}{TclInterface}{.TkRoot}
\aliasA{addTclPath}{TclInterface}{addTclPath}
\aliasA{as.character.tclObj}{TclInterface}{as.character.tclObj}
\aliasA{as.character.tclVar}{TclInterface}{as.character.tclVar}
\aliasA{as.double.tclObj}{TclInterface}{as.double.tclObj}
\aliasA{as.integer.tclObj}{TclInterface}{as.integer.tclObj}
\aliasA{as.tclObj}{TclInterface}{as.tclObj}
\aliasA{is.tclObj}{TclInterface}{is.tclObj}
\aliasA{is.tkwin}{TclInterface}{is.tkwin}
\aliasA{length.tclArray}{TclInterface}{length.tclArray}
\aliasA{length<\Rdash.tclArray}{TclInterface}{length<.Rdash..tclArray}
\aliasA{names.tclArray}{TclInterface}{names.tclArray}
\aliasA{names<\Rdash.tclArray}{TclInterface}{names<.Rdash..tclArray}
\aliasA{print.tclObj}{TclInterface}{print.tclObj}
\aliasA{tclArray}{TclInterface}{tclArray}
\aliasA{tclObj}{TclInterface}{tclObj}
\methaliasA{tclObj.tclVar}{TclInterface}{tclObj.tclVar}
\aliasA{tclObj<\Rdash}{TclInterface}{tclObj<.Rdash.}
\methaliasA{tclObj<\Rdash.tclVar}{TclInterface}{tclObj<.Rdash..tclVar}
\aliasA{tclRequire}{TclInterface}{tclRequire}
\aliasA{tclvalue}{TclInterface}{tclvalue}
\methaliasA{tclvalue.default}{TclInterface}{tclvalue.default}
\methaliasA{tclvalue.tclObj}{TclInterface}{tclvalue.tclObj}
\methaliasA{tclvalue.tclVar}{TclInterface}{tclvalue.tclVar}
\aliasA{tclvalue<\Rdash}{TclInterface}{tclvalue<.Rdash.}
\methaliasA{tclvalue<\Rdash.default}{TclInterface}{tclvalue<.Rdash..default}
\methaliasA{tclvalue<\Rdash.tclVar}{TclInterface}{tclvalue<.Rdash..tclVar}
\aliasA{tclVar}{TclInterface}{tclVar}
\aliasA{tclvar}{TclInterface}{tclvar}
\aliasA{tkdestroy}{TclInterface}{tkdestroy}
\aliasA{[[.tclArray}{TclInterface}{[[.tclArray}
\aliasA{[[<\Rdash.tclArray}{TclInterface}{[[<.Rdash..tclArray}
\keyword{misc}{TclInterface}
\begin{Description}\relax
These functions and variables provide the basic glue between \R{} and the
Tcl interpreter and Tk GUI toolkit. Tk
windows may be represented via \R{} objects. Tcl variables can be accessed
via objects of class \code{tclVar} and the C level interface to Tcl
objects is accessed via objects of class \code{tclObj}.
\end{Description}
\begin{Usage}
\begin{verbatim}
.Tcl(...)
.Tcl.objv(objv)
.Tcl.args(...)
.Tcl.args.objv(...)
.Tcl.callback(...)
.Tk.ID(win)
.Tk.newwin(ID)
.Tk.subwin(parent)
.TkRoot

tkdestroy(win)
is.tkwin(x)

tclvalue(x)
tclvalue(x) <- value

tclVar(init="")
## S3 method for class 'tclVar':
as.character(x, ...)
## S3 method for class 'tclVar':
tclvalue(x)
## S3 replacement method for class 'tclVar':
tclvalue(x) <- value

tclArray()
## S3 method for class 'tclArray':
x[[...]]
## S3 replacement method for class 'tclArray':
x[[...]] <- value
## S3 method for class 'tclArray':
x$i
## S3 replacement method for class 'tclArray':
x$i <- value

## S3 method for class 'tclArray':
names(x)
## S3 method for class 'tclArray':
length(x)

tclObj(x)
tclObj(x) <- value
## S3 method for class 'tclVar':
tclObj(x)
## S3 replacement method for class 'tclVar':
tclObj(x) <- value

as.tclObj(x, drop=FALSE)
is.tclObj(x)

## S3 method for class 'tclObj':
as.character(x, ...)
## S3 method for class 'tclObj':
as.integer(x, ...)
## S3 method for class 'tclObj':
as.double(x, ...)
## S3 method for class 'tclObj':
tclvalue(x)

## Default S3 method:
tclvalue(x)
## Default S3 replacement method:
tclvalue(x) <- value

addTclPath(path = ".")
tclRequire(package, warn = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{objv}] a named vector of Tcl objects
\item[\code{win}] a window structure
\item[\code{x}] an object
\item[\code{i}] character or (unquoted) name
\item[\code{drop}] logical. Indicates whether a single-element vector should
be made into a simple Tcl object or a list of length one
\item[\code{value}] For \code{tclvalue} assignments, a character string. For
\code{tclObj} assignments, an object of class \code{tclObj}
\item[\code{ID}] a window ID
\item[\code{parent}] a window which becomes the parent of the resulting window
\item[\code{path}] path to a directory containing Tcl packages
\item[\code{package}] a Tcl package name
\item[\code{warn}] logical. Warn if not found?
\item[\code{...}] Additional arguments. See below.
\item[\code{init}] initialization value
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Many of these functions are not intended for general use but are used
internally by the commands that create and manipulate Tk widgets and
Tcl objects.  At the lowest level \code{.Tcl} sends a command as a text
string to the Tcl interpreter and returns the result as an object of
class \code{tclObj} (see below).  A newer variant \code{.Tcl.objv}
accepts arguments in the form of a named list of \code{tclObj}
objects. 

\code{.Tcl.args} converts an R argument list of \code{tag=value} pairs
to the Tcl \code{-option value} style, thus
enabling a simple translation between the two languages. To send a
value with no preceding option flag to Tcl, just use an untagged
argument. In the rare case one needs an option with no subsequent
value \code{tag=NULL} can be used. Most values are just converted to
character mode and inserted in the command string, but window objects
are passed using their ID string, and callbacks are passed via the
result of \code{.Tcl.callback}. Tags are converted to option flags
simply by prepending a \code{-}

\code{.Tcl.args.objv} serves a similar purpose as \code{.Tcl.args} but
produces a list of \code{tclObj} objects suitable for passing to
\code{.Tcl.objv}. The names of the list are converted to Tcl option
style internally by \code{.Tcl.objv}. 

Callbacks can be either \emph{atomic callbacks} handled by
\code{.Tcl.callback} or expressions. An expression is treated as a
list of atomic callbacks, with the following exceptions: if an
element is a name, it is first evaluated in the callers frame, and
likewise if it is an explicit function definition; the \code{break}
expression is translated directly to the Tcl counterpart.
\code{.Tcl.callback} converts \R{} functions and unevaluated calls to
Tcl command strings.  The argument must be either a function closure
or an object of mode \code{"call"} followed by an environment.  The
return value in the first case is of the form \code{R\_call
  0x408b94d4} in which the hexadecimal number is the memory address of
the function. In the second case it will be of the form
\code{R\_call\_lang 0x8a95904 0x819bfd0}. For expressions, a sequence
of similar items is generated, separated by
semicolons. \code{.Tcl.args} takes special precautions to ensure
that functions or calls will continue to exist at the specified
address by assigning the
callback into the relevant window environment (see below).

Tk windows are represented as objects of class \code{tkwin} which are
lists containing  a \code{ID} field and an \code{env} field which is
an \R{} environments, enclosed in the global environment.  The value of
the \code{ID} field is identical to the Tk window name. The \code{env}
environment contains a \code{parent} variable and a \code{num.subwin}
variable.  If the window obtains sub-windows and  callbacks, they are
added as variables to the environment.   \code{.TkRoot} is the top
window with ID "."; this window is not  displayed in order to avoid
ill effects of closing it via window  manager controls. The
\code{parent} variable is undefined for \code{.TkRoot}.

\code{.Tk.ID} extracts the \code{ID} of a window,
\code{.Tk.newwin} creates a new window environment with a given ID and
\code{.Tk.subwin} creates a new window which is a sub-window of a given
parent window.

\code{tkdestroy} destroys a window and also removes the reference to a
window from its parent.

\code{is.tkwin} can be used to test whether a given object is a window
environment.

\code{tclVar} creates a new Tcl variable and initializes it to
\code{init}.  An R object of class \code{tclVar} is created to
represent it.  Using \code{as.character} on the object returns the Tcl
variable name.  Accessing the Tcl variable from R is done using the 
\code{tclvalue} function, which can also occur on the left-hand side of
assignments.  If \code{tclvalue} is passed an argument which is not a
\code{tclVar} object, then it will assume that it is a character string
explicitly naming global Tcl variable. Tcl variables created by 
\code{tclVar} are uniquely named and automatically unset by the
garbage collector when the representing object is no longer in use. 

\code{tclArray} creates a new Tcl array and initializes it to the empty
array.  An R object of class \code{tclArray} and inheriting from class
\code{tclVar} is created to represent it. You can access elements of
the Tcl array using indexing with \code{[[} or \code{\$}, which also
allow replacement forms.  Notice that Tcl arrays are associative by
nature and hence unordered; indexing with a numeric index \code{i}
refers to the element with the \emph{name}
\code{as.character(i)}.  Multiple indices are pasted together separated
by commas to form a single name.  You can query the
length and the set of names in an array using methods for
\code{length} and \code{names}, respectively; these cannot
meaningfully be set so assignment forms exist only to print an error
message. 

It is possible to access Tcl's \sQuote{dual-ported} objects directly,
thus avoiding parsing and deparsing of their string representation.
This works by using objects of class \code{tclObj}.  The string
representation of such objects can be extracted (but not set) using
\code{tclvalue} and conversion to vectors of mode \code{"character"},
\code{"double"}, or \code{"integer"}.  Conversely, such vectors can be
converted using \code{as.tclObj}.  There is an ambiguity as to what
should happen for length one vectors, controlled by the \code{drop}
argument; there are cases where the distinction matters to Tcl,
although mostly it treats them equivalently.  Notice that
\code{tclvalue} and \code{as.character} differ on an object whose
string representation has embedded spaces, the former is sometimes to
be preferred, in particular when applied to the result of
\code{tclread}, \code{tkgetOpenFile}, and similar functions. 

The object behind a \code{tclVar} object
is extracted using \code{tclObj(x)} which also allows an assignment
form, in which the right hand side of the assignment is automatically
converted using \code{as.tclObj}.  There is a print method for
\code{tclObj} objects; it prints \code{<Tcl>} followed by the string
representation of the object.  Notice that \code{as.character} on a
\code{tclVar} object is the \emph{name} of the corresponding Tcl
variable and not the value. 

Tcl packages can be loaded with \code{tclRequire}; it may be necessary
to add the directory where they are found to the Tcl search path with
\code{addTclPath}.
\end{Details}
\begin{Note}\relax
Strings containing unbalanced braces are currently not handled
well in many circumstances.
\end{Note}
\begin{SeeAlso}\relax
\code{\LinkA{TkWidgets}{TkWidgets}},
\code{\LinkA{TkCommands}{TkCommands}},
\code{\LinkA{TkWidgetcmds}{TkWidgetcmds}}.

\code{\LinkA{capabilities}{capabilities}("tcltk")} to see if Tcl/Tk support was
compiled into this build of \R.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
## These cannot be run by example() but should be OK when pasted
## into an interactive R session with the tcltk package loaded
.Tcl("format \"%s\n\" \"Hello, World!\"")
f <- function()cat("HI!\n")
.Tcl.callback(f)
.Tcl.args(text="Push!", command=f) # NB: Different address

xyzzy <- tclVar(7913)
tclvalue(xyzzy)
tclvalue(xyzzy) <- "foo"
as.character(xyzzy)
tcl("set", as.character(xyzzy))

top <- tktoplevel() # a Tk widget, see Tk-widgets
ls(envir=top$env, all=TRUE)
ls(envir=.TkRoot$env, all=TRUE)# .Tcl.args put a callback ref in here
## End(Not run)
\end{ExampleCode}
\end{Examples}

