TclInterface
Low-level Tcl/Tk Interface
Description
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 tclVar
and the C level interface to Tcl objects is accessed via objects of class tclObj
.
Usage
.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' as.logical(x, ...) ## S3 method for class 'tclObj' as.raw(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) tclVersion()
Arguments
objv | a named vector of Tcl objects |
win | a window structure |
x | an object |
i | character or (unquoted) name |
drop | logical. Indicates whether a single-element vector should be made into a simple Tcl object or a list of length one |
value | For |
ID | a window ID |
parent | a window which becomes the parent of the resulting window |
path | path to a directory containing Tcl packages |
package | a Tcl package name |
warn | logical. Warn if not found? |
... | Additional arguments. See below. |
init | initialization value |
Details
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 .Tcl
sends a command as a text string to the Tcl interpreter and returns the result as an object of class tclObj
(see below). A newer variant .Tcl.objv
accepts arguments in the form of a named list of tclObj
objects.
.Tcl.args
converts an R argument list of tag = value
pairs to the Tcl -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 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 .Tcl.callback
. Tags are converted to option flags simply by prepending a -
.Tcl.args.objv
serves a similar purpose as .Tcl.args
but produces a list of tclObj
objects suitable for passing to .Tcl.objv
. The names of the list are converted to Tcl option style internally by .Tcl.objv
.
Callbacks can be either atomic callbacks handled by .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 break
expression is translated directly to the Tcl counterpart. .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 "call"
followed by an environment. The return value in the first case is of the form 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 R_call_lang 0x8a95904 0x819bfd0
. For expressions, a sequence of similar items is generated, separated by semicolons. .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 tkwin
which are lists containing a ID
field and an env
field which is an R environments, enclosed in the global environment. The value of the ID
field is identical to the Tk window name. The env
environment contains a parent
variable and a num.subwin
variable. If the window obtains sub-windows and callbacks, they are added as variables to the environment. .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 parent
variable is undefined for .TkRoot
.
.Tk.ID
extracts the ID
of a window, .Tk.newwin
creates a new window environment with a given ID and .Tk.subwin
creates a new window which is a sub-window of a given parent window.
tkdestroy
destroys a window and also removes the reference to a window from its parent.
is.tkwin
can be used to test whether a given object is a window environment.
tclVar
creates a new Tcl variable and initializes it to init
. An R object of class tclVar
is created to represent it. Using as.character
on the object returns the Tcl variable name. Accessing the Tcl variable from R is done using the tclvalue
function, which can also occur on the left-hand side of assignments. If tclvalue
is passed an argument which is not a tclVar
object, then it will assume that it is a character string explicitly naming global Tcl variable. Tcl variables created by tclVar
are uniquely named and automatically unset by the garbage collector when the representing object is no longer in use.
tclArray
creates a new Tcl array and initializes it to the empty array. An R object of class tclArray
and inheriting from class tclVar
is created to represent it. You can access elements of the Tcl array using indexing with [[
or $
, which also allow replacement forms. Notice that Tcl arrays are associative by nature and hence unordered; indexing with a numeric index i
refers to the element with the name 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 length
and names
, respectively; these cannot meaningfully be set so assignment forms exist only to print an error message.
It is possible to access Tcl's ‘dual-ported’ objects directly, thus avoiding parsing and deparsing of their string representation. This works by using objects of class tclObj
. The string representation of such objects can be extracted (but not set) using tclvalue
and conversion to vectors of mode "character"
, "double"
, "integer"
, "logical"
, and "raw"
is performed using the standard coercion functions as.character
, etc. Conversely, such vectors can be converted using as.tclObj
. There is an ambiguity as to what should happen for length one vectors, controlled by the drop
argument; there are cases where the distinction matters to Tcl, although mostly it treats them equivalently. Notice that tclvalue
and 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 tclread
, tkgetOpenFile
, and similar functions. The as.raw
method returns a raw vector or a list of raw vectors and can be used to return binary data from Tcl.
The object behind a tclVar
object is extracted using tclObj(x)
which also allows an assignment form, in which the right hand side of the assignment is automatically converted using as.tclObj
. There is a print method for tclObj
objects; it prints <Tcl>
followed by the string representation of the object. Notice that as.character
on a tclVar
object is the name of the corresponding Tcl variable and not the value.
Tcl packages can be loaded with tclRequire
; it may be necessary to add the directory where they are found to the Tcl search path with addTclPath
. The return value is a class "tclObj"
object if it succeeds, or FALSE
if it fails (when a warning is issued). To see the current search path as an R character vector, use
strsplit(tclvalue('auto_path'), " ")[[1]]
.
The Tcl version (including patchlevel) is returned as a character string (such as "8.6.3"
).
Note
Strings containing unbalanced braces are currently not handled well in many circumstances.
See Also
TkWidgets
, TkCommands
, TkWidgetcmds
.
capabilities("tcltk")
to see if Tcl/Tk support was compiled into this build of R.
Examples
tclVersion() .Tcl("format \"%s\n\" \"Hello, World!\"") f <- function() cat("HI!\n") ## IGNORE_RDIFF_BEGIN .Tcl.callback(f) .Tcl.args(text = "Push!", command = f) # NB: Different address ## IGNORE_RDIFF_END xyzzy <- tclVar(7913) tclvalue(xyzzy) tclvalue(xyzzy) <- "foo" as.character(xyzzy) tcl("set", as.character(xyzzy)) ## Not run: ## These cannot be run by example() but should be OK when pasted ## into an interactive R session with the tcltk package loaded top <- tktoplevel() # a Tk widget, see Tk-widgets ls(envir = top$env, all.names = TRUE) ## End(Not run) ## IGNORE_RDIFF_BEGIN ls(envir = .TkRoot$env, all.names = TRUE) # .Tcl.args put a callback ref in here ## IGNORE_RDIFF_END
Copyright (©) 1999–2012 R Foundation for Statistical Computing.
Licensed under the GNU General Public License.