This is Info file gtcltk.info, produced by Makeinfo version 1.67 from the input file gtcltk.texi.  File: gtcltk.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) This file documents how to use Tk and Tcl with Guile. * Menu: * Copying:: * Tcl Facilities:: * Tk Facilities:: * Gwish::  File: gtcltk.info, Node: Copying, Next: Tcl Facilities, Prev: Top, Up: Top Copying ******* Copyright (C) 1995 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. NO WARRANTY BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.  File: gtcltk.info, Node: Tcl Facilities, Next: Tk Facilities, Prev: Copying, Up: Top Tcl Facilities ************** If you have Tcl extension modules written in C, these can be accessed from Guile programs. If you have an application that uses the Tcl interpreter, you can use Guile to define new modules for it - modules that can be loaded without having to re-compile. Documented here are the low-level facilities linking Tcl to Guile. In the future, a friendlier Scheme interface will be provided in preference to these entry points. - Function: tcl-create-interp Return a new Tcl interpreter object. An interpreter object is a namespace of functions and variables managed by modules that use the Tcl calling conventions. - Function: tcl-global-eval INTERPRETER STRING Evaluate a string according to Tcl's evaluation rules. INTERPRETER must be an object returned by `tcl-create-interp'. The return value is an integer/string pair. The integer is the Tcl status code, the string is the Tcl result. This is not the way to call a Tcl command. See the functions `tcl-command' and `tcl-apply-command'. Using those functions is faster. N.B.: by default, most built-in Tcl commands are absent in Guile. Consequently, most Tcl programs will not run. However, facilities exist so that you can link all of libtcl with Guile programs - in which case all the usual built-in commands will be present. [add reference!] - Function: tcl-get-int INTERPRETER STRING - Function: tcl-get-double INTERPRETER STRING - Function: tcl-get-boolean INTERPRETER STRING Convert strings to Scheme types according to the conventions of Tcl. - Function: tcl-split-list INTERPRETER STRING Split a Tcl-style "list" (a string following Tcl's list syntax) into a list. - Function: tcl-merge INTERPRETER LIST Combine a list of strings into a string following Tcl's list syntax. - Function: tcl-create-command INTERPRETER NAME PROCEDURE Define a new Tcl command which is recognized by the Tcl evaluator. INTERPRETER must be an object returned by `tcl-create-command'. NAME must be a string which is a valid Tcl identifier. PROCEDURE may be any Scheme procedure object. When the Tcl evaluator invokes the new command, PROCEDURE is called with as many arguments as were passed to the Tcl command. The arguments are all passed as strings. The return value of PROCEDURE is used as the Tcl result. The return value of PROCEDURE determines the Tcl return value according to these rules: if PROCEDURE returns: the Tcl result is: and Tcl status is: __________________________________________________________________ string (e.g. "foo") that string ("foo") TCL_OK integer (e.g. 1) the empty string the int (1) an int/string pair the string the int (e.g. (1 . "bogus frob")) ("bogus frob") (1) - Function: tcl-delete-command INTERPRETER NAME Remove the named command from a Tcl interpreter. - Function: tcl-trace-var2 INTERPRETER NAME INDEX FLAGS PROCEDURE - Function: tcl-untrace-var2 INTERPRETER NAME INDEX FLAGS PROCEDURE Add a callback to a Tcl variable. NAME is the name of the variable. INDEX is the subscript of the variable, or `#f' for a scalar. After `tcl-trace-var2', modifications to the named variable or array position cause procedure to be called with four arguments: a tcl interpreter, the variable being modified, an index into the named variable (possible the empty string), and an integer of flags. - Function: tcl-set-var2 INTERPRETER NAME INDEX VALUE FLAGS - Function: tcl-get-var2 INTERPRETER NAME INDEX FLAGS Set or return the current value of a Tcl variable. Symbolic names for Tcl flags are provided in the source file Gtcl.scm and are the same as their C counterparts. The procedure `flags' is used to combine flags. For example: (flags TCL_TRACE_READS TCL_TRACE_WRITES TCL_TRACE_UNSETS) Tcl commands can be invoked from Scheme directly, without having to use the Tcl evaluator: - Function: tcl-command INTERPRETER NAME Return an object representing the named command (or #f if none is defined). - Function: tcl-apply-command COMMAND ARGS Apply Tcl command COMMAND to the list of strings ARGS. COMMAND should be an object returned by `tcl-command'. ARGS should be a list of arguments. The return value is an integer/string pair. The integer is a Tcl return code, the string the Tcl result. The arguments can be of several types but must ultimately be converted to strings because of the way Tcl and Tk work internally. Types are converted this way: ;;---------------------------------------- ;; Argument Converted argument ;;---------------------------------------- 123 "123" 123.34 "123.34" "a-string" "a-string" 'a-symbol "a-symbol" :keyword "-keyword" #t "1" #f "0" (lambda (...) ...) "*__guile#234" The automatic conversion of a procedure works this way. First, a new Tcl name is generated for the procedure and a Tcl command with that name is defined. When evaluated, the Tcl command calls the Scheme procedure. Second, if the procedure has a property defined called 'tcl-calling-convention, and if that is bound to a string, then that string is appended to the name with an intervening space. For example, if a procedure's properties bind 'tcl-calling-convention to "%x %y", then the name is appended and winds up like "__guile#234 %x %y". Finally, an asterix is prepended to the name (e.g. "*__guile#234 %x %y"). In the GNU modified version of Tcl/Tk, an asterix prepended to a command name has special meaning if the name is passed as a "-command" or similar configuration parameter to a widget, or if passed as the command argument to a "bind" operation. In that case, the command is renamed to a canonical name that is unique to the widget or binding sequence (overwriting any previous definition). If the widget or binding sequence is later deleted, so is the canonicalized command. This is an extremely twisted way to trick Tcl into managing anonymous Scheme procedures with acceptable semantics (e.g., without core leaks and without requiring Scheme programmers to invent liveness for anonymous procedures they'd otherwise drop).  File: gtcltk.info, Node: Tk Facilities, Next: Gwish, Prev: Tcl Facilities, Up: Top Tk Facilities ************* So that Tk widgets can be used form Scheme, Guile provides the following functions: - Function: tk-init-main-window INTERPRETER DISPLAY NAME CLASS Initialize a Tcl interpreter as a Tk main window. DISPLAY, NAME, and CLASS must all be strings. - Function: tk-do-one-event FLAGS Process one window system event. Symbolic definitions for FLAGS are provided in Gtk.scm and have the same name as their C counterparts. - Function: tk-main-loop Process window events until no windows remain.  File: gtcltk.info, Node: Gwish, Prev: Tk Facilities, Up: Top Gwish ***** Gwish is a Wish-like application of Guile, based on STk by Erick Gallesio. Running Gwish ------------- Mapping Tcl/Tk Constructs onto Gwish ------------------------------------ In Gwish, there is a single Tcl/Tk interpreter which is an implicit default. Commands defined in that interpreter are automaticly defined as Scheme commands as well (unless a Scheme-specific binding overwrites them). This means that you can write Scheme code that closely matches the corresponding Tcl code. For example: (button '.b) (.b 'configure :text "hello world" :command (tcl-lambda () (beep))) Arguments passed to a procedure implemented by a Tcl command must be converted to a string for the sake of Tcl's calling conventions and data representations. This table illustrates how argument types are converted: ;;---------------------------------------- ;; Argument Converted argument ;;---------------------------------------- 123 "123" 123.34 "123.34" "a-string" "a-string" 'a-symbol "a-symbol" :keyword "-keyword" #t "1" #f "0" (lambda (...) ...) "*__guile#234" Most of these conversions are simple and obvious but the conversion of procedure objects is subtle and non-obvious. It is not necessary to understand the details, though they are documented elsewhere. It is necessary to know that procedure arguments `do the right thing' when they are passed as command parameters to widget configuration commands, and as event bindings. You might ask: what is the right thing? A procedure passed as either an event binding or widget command is protected by the binding or widget involved. Effectively, the widget or binding keeps a reference to the procedure object. For this reason, it is possible to use an anonymous Scheme procedure as an event binding or widget command. For example: (let ((n 0)) (.b configure :command (lambda () (write n) (newline) (set! n + 1) ""))) ;; Incidently, note that the command procedure returns an empty string. ;; All procedures called by Tcl have to return a proper Tcl result. ;; Return values are explained further in the next subsection. ;; When a command or binding is overwritten and that command or binding is to a Scheme procedure, the reference to the procedure is dropped. The procedure is also dropped if the binding or widget is deleted. For this reason, there are no core leaks associated with passing anonymous procedures as these kinds of arguments. At this time, it isn't generally useful to pass Scheme procedures to Tcl commands other than as an argument to a binding command or widget configuration command. The details of how procedures are translated are described in the documentation for `tcl-apply-command'. *Note Tcl Facilities::. Defining Tcl Command in Scheme ------------------------------ Gwish provides a convenient syntax for defining new Tcl commands. - Syntax: proc NAME FORMALS . BODY Define a new Tcl command and Scheme procedure simultaneously. ;; A two argument string-append callable as a Tcl command. ;; (proc string-smash (s1 s2) (string-append s1 s2)) Proc expands to a `tcl-lambda' form, which is explained below. The example above is equivalent to: (begin (define string-smash (tcl-lambda (s1 s2) (string-append s1 s2))) (tcl-create-command the-interpreter 'string-smash string-smash)) - Syntax: tcl-lambda (?CALLING-CONVENTION? ?.? FORMALS) . BODY Similar to lambda, but imposes Tcl-specific calling conventions. Type declarations are supported. This is best explained via examples. A simple use of `tcl-lambda': ;; By default, when called from Tcl, all of the arguments ;; to a tcl-lambda are strings. ;; (tcl-lambda (a b) (string-append a b)) The return value of a tcl-lambda has special signficance when the function is invoked by Tcl. An integer return value is converted to a string. A string or symbol is used used directly as a Tcl result. A cons pair with an integer car and string cdr is a Tcl status/message combination. Type declarations can be used to specify that parameters passed as strings should be coerced to some other type. For example: (define tcl-plus (tcl-lambda ((number a) (number b)) (+ a b))) (tcl-plus "23" 19) => 42 Tcl-lambda is very useful for using anonymous Scheme functions as Tk event bindings. For this purpose, you can can specify a Tk "calling convention" by writing a string in the first of the argument specification. For example: (.c 'bind 'node "" (tcl-lambda ("%x %y" (number x) (number y)) (set! cur-x x) (set! cur-y y) #t)) ; Tcl-compatible return value. In that example, `"%x %y"' is the calling convention. The full command that Tcl calls when invoking the binding will be similar to: __binding#0x123123 %x %y and therefore the Scheme procedure will be passed (in this case) the x and y position of the mouse. An Example: Ousterhout's Graph Editor ------------------------------------- This program implements the toy graph editor from the Tcl/Tk .  Tag Table: Node: Top99 Node: Copying300 Node: Tcl Facilities2104 Node: Tk Facilities9121 Node: Gwish9766  End Tag Table