TclInterface              package:tcltk              R Documentation

_L_o_w-_l_e_v_e_l _T_c_l/_T_k _I_n_t_e_r_f_a_c_e

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

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

     tkdestroy(win)
     is.tkwin(x)

     tclvar$name
     tclvar$name <- value

_A_r_g_u_m_e_n_t_s:

     win: a window structure

       x: an object

      ID: a window ID

_D_e_t_a_i_l_s:

     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 functions are passed via the result of
     `.Tcl.callback'. Tags are converted to option flags simply by
     prepending a `-'

     `.Tcl.callback' converts R functions to Tcl command strings.  The
     argument must be a function closure.  The return value is
     something of the form `{ R_call 0x408b94d4 }' in which the
     hexadecimal number is the memory address of the function.  
     `.Tcl.args' takes special precautions to ensure that the function
     will exist at that address by assigning the function into the
     relevant window environment (see below).

     Tk windows are represented as R environments, all of which are
     enclosed in the `.TkWin' environment.  They contain initially just
     an `ID' variable identical to the Tk window name, a `parent'
     variable and a `num.subwin' variable (possibly inherited from
     `.TkWin').  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.  `.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.

_N_o_t_e:

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

_E_x_a_m_p_l_e_s:

     ## 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

     tclvar$xyzzy <- 7913 ; .Tcl("set xyzzy")
     .Tcl("set xyzzy 3917") ; tclvar$xyzzy

     top <- tktoplevel() # a Tk widget, see Tk-widgets
     ls(envir=top, all=TRUE)
     ls(envir=.TkRoot, all=T)# .Tcl.args put a callback ref in here

