TclInterface              package: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
     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)
     .TkWin
     .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 method for class 'tclVar':
     tclvalue(x) <- value

     tclArray()
     \method{[[}{tclArray}(x,...)
     \method{[[}{tclArray}(x,...) <- value
     \method{$}{tclArray}(x, i)
     \method{$}{tclArray}(x, i) <- value
     ## S3 method for class 'tclArray':
     names
     ## S3 method for class 'tclArray':
     length

     tclObj(x)
     tclObj(x) <- value
     ## S3 method for class 'tclVar':
     tclObj(x)
     ## S3 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 method:
     tclvalue(x) <- value

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

Arguments:

    objv: a named vector of Tcl objects

     win: a window structure

       x: an object

    drop: logical. Indicates whether a single-element vector should be
          made into a simple Tcl object or a list of length one

   value: For 'tclvalue' assignments, a character string. For 'tclObj'
          assignments, an object of class 'tclObj'

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

     'tclArray' creates a new Tcl array and initalizes 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"', or '"integer"'. 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 distiction 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 'tkread',
     'tkgetOpenFile', and similar functions. 

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

Note:

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

See Also:

     'TkWidgets', 'TkCommands', 'TkWidgetcmds'.

     'capabilities("tcltk")'

Examples:

     ## 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)
     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
     ## End(Not run)

