R: Low-level Tcl/Tk Interface

TclInterface {tcltk} | R Documentation

## 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 the pseudo-list `tclvar`.

### Usage

    .Tcl(...)
    .Tcl.args(...)
    .Tcl.callback(...)
    .Tk.ID(win)
    .Tk.newwin(ID)
    .Tk.subwin(parent)
    .TkWin
    .TkRoot

    tkdestroy(win)
    is.tkwin(x)

    tclvar$name           # Deprecated
    tclvar$name <- value  # Deprecated

    tclVar(init="")
    as.character.tclVar(x)
    tclvalue(x)
    tclvalue(x) <- value

    addTclPath(path = ".")
    tclRequire(package, warn = TRUE)

### Arguments

`win` | a window structure
`x` | an object
`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 a text string.

`.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 `-`

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 the function will exist at that 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 subwindows 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 subwindow 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` is used to access Tcl variables. The Tcl variable name is used as if it were a list element name in `tclvar`, but in reality `tclvar` is an object of class `tclvar` and `$` and `$<-` have special methods for that class. NOTE: This interface is deprecated, use the `tclVar` object class instead.

`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 sie 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.

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`.

### Note

Strings containing unbalanced braces are currently not handled well in many circumstances.

### See Also

`TkWidgets`, `TkCommands`, `TkWidgetcmds`.

`capabilities("tcltk"`

### Examples

    ## 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()"HI!"
    .Tcl.callback(f)
    .Tcl.args(text="Push!", command=f) # NB: Different address

    xyzzy <- tclVar(7913)
    tclvalue(xyzzy)
    tclvalue(xyzzy) <- "foo"
    as.character(xyzzy)
    tkcmd("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

[Package Contents]