<HTML>
<HEAD>
<!-- Created by texi2html 1.56k + clip patches and <A href="http://www.clip.dia.fi.upm.es/Software">lpdoc</A> from ciao.texi on 28 January 2007 -->
<LINK rel="stylesheet" href="ciao.css" type="text/css">
<TITLE>The Ciao Prolog System - The Tcl/Tk interface</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_124.html">previous</A>, <A HREF="ciao_126.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC538" HREF="ciao_toc.html#TOC538">The Tcl/Tk interface</A></H1>
<P>
<A NAME="IDX6008"></A>
<P>
<STRONG>Author(s):</STRONG> Montse Iglesias Urraca, <CODE>http://www.clip.dia.fi.upm.es/</CODE>, The CLIP Group, Facultad de Informática, Universidad Politécnica de Madrid.
<P>
<STRONG>Version:</STRONG> 1.10#7 (2006/4/26, 19:22:13 CEST)
<P>
<STRONG>Version of last change:</STRONG> 1.9#314 (2004/2/25, 18:27:47 CET)
<P>
The
<A NAME="IDX6009"></A>
<CODE>tcltk</CODE> library package is a bidirectional interface to the <EM>Tcl</EM> language and the <EM>Tk</EM> toolkit. Tcl is an interpreted scripting language with many extension packages, particularly the graphical interface toolkit, Tk. The interaction between both languages is expressed in terms of an interface between the Tcl/Tk process and the Prolog process. This approach allows the development of mixed applications where both sides, Tcl/Tk and Prolog, can be combined in order to exploit their respective capabilities.
<P>
This library uses two sockets to connect both the Tcl and the Prolog processes: <EM>event_socket</EM> and <EM>term_socket</EM>. There are also two Tcl global variables: <EM>prolog_variables</EM> and <EM>terms</EM>. The value of any of the bound variables in a goal will be stored in the array <CODE>prolog_variables</CODE> with the variable name as index. <EM>Terms</EM> is the string which contains the printed representation of prolog <EM>terms</EM>.
<P>
<STRONG>Prolog to Tcl</STRONG>
<P>
The Tcl/Tk side waits for requests from the Prolog side, and executes the Tcl/Tk code received. Also, the Tcl/Tk side handles the events and exceptions which may be raised on its side, passing on control to the Prolog side in case it is necessary.
<P>
To use Tcl, you must create a <EM>Tcl interpreter</EM> object and send commands to it. A <EM>Tcl</EM> command is specified as follows:
<PRE>
Command --> Atom { other than [] }
| Number
| chars(PrologString)
| write(Term)
| format(Fmt,Args)
| dq(Command)
| br(Command)
| sqb(Command)
| min(Command)
| ListOfCommands
ListOfCommands --> []
|[Command|ListOfCommands]
</PRE>
<P>
where:
<DL COMPACT>
<DT><CODE>Atom</CODE>
<DD>
denotes the printed representation of the atom.
<DT><CODE>Number</CODE>
<DD>
denotes their printed representations.
<DT><CODE>chars(PrologString)</CODE>
<DD>
denotes the string represented by <EM>PrologString</EM> (a list of character codes).
<DT><CODE>write(Term)</CODE>
<DD>
denotes the string that is printed by the corresponding built-in predicate.
<DT><CODE>format(Term)</CODE>
<DD>
denotes the string that is printed by the corresponding built-in predicate.
<DT><CODE>dq(Command)</CODE>
<DD>
denotes the string specified by <EM>Command</EM>, enclosed in double quotes.
<DT><CODE>br(Command)</CODE>
<DD>
denotes the string specified by <EM>Command</EM>, enclosed in braces.
<DT><CODE>sqb(Command)</CODE>
<DD>
denotes the string specified by <EM>Command</EM>, enclosed in square brackets.
<DT><CODE>min(Command)</CODE>
<DD>
denotes the string specified by <EM>Command</EM>, immediately preceded by a hyphen.
<DT><CODE>ListOfCommands</CODE>
<DD>
denotes the strings denoted by each element, separated by spaces.
</DL>
<P>
The predicates to use Tcl from Prolog are
<A NAME="IDX6010"></A>
<CODE>tcl_new/1</CODE>,
<A NAME="IDX6011"></A>
<CODE>tcl_delete/1</CODE>,
<A NAME="IDX6012"></A>
<CODE>tcl_eval/3</CODE>, and
<A NAME="IDX6013"></A>
<CODE>tcl_event/3</CODE>.
<P>
An example of use with Prolog as master and Tcl as slave, consisting of a GUI to a program which calculates the factorial of a number:
<P>
<PRE>
:- use_module(library(tcltk)).
go :-
tcl_new(X),
tcl_eval(X,[button,'.b',min(text),dq('Compute!')],_),
tcl_eval(X,[button,'.c','-text',dq('Quit')],_),
tcl_eval(X,[entry,'.e1',min(textvariable),'inputval'],_),
tcl_eval(X,[label,'.l1',min(text),dq('The factorial of ')],_),
tcl_eval(X,[pack, '.l1','.e1'],_),
tcl_eval(X,[entry,'.e2',min(textvariable),'outputval'],_),
tcl_eval(X,[label,'.l2',min(text),dq('is ')],_),
tcl_eval(X,[pack, '.l2','.e2'],_),
tcl_eval(X,[pack,'.b','.c',min(side),'left'],_),
tcl_eval(X,[bind,'.b','<ButtonPress-1>',
br([set,'inputval','$inputval','\n',
prolog_one_event,dq(write(execute(tk_test_aux:factorial('$inputval','Outputval')))),'\n',
set, 'outputval','$prolog_variables(Outputval)'])],_),
tcl_eval(X,[bind,'.c','<ButtonPress-1>',
br([prolog_one_event,dq(write(execute(exit_tk_event_loop)))])],_),
tk_event_loop(X).
</PRE>
<P>
<STRONG>Tcl to Prolog</STRONG>
<P>
This is the usual way to build a GUI application. The slave, Prolog, behaves as a server that fulfills eventual requests from the master side, Tcl. At some point, during the user interaction with the GUI, an action may take place that triggers the execution of some procedure on the slave side (a form submit, for example). Thus, the slave is invoked, performs a service, and returns the result to the GUI through the socket connection.
<P>
This library includes two main specific Tcl commands:
<DL COMPACT>
<DT><CODE>prolog</CODE> <EM>Goal</EM>
<DD>
<EM>Goal</EM> is a string containing the printed representation of a Prolog goal. The goal will be called in the user module unless it is prefixed with another module name. The call is always deterministic and its can be either of the following:
<DL COMPACT>
<DT><EM>1</EM>, in case of success
<DD>
The value of any of the variables in the goal that is bound to a term will be returned to Tcl in the array prolog_variables with the variable name as index.
<DT><EM>0</EM>, if the execution fails
<DD>
The Prolog exception Tcl exception is raised. The error message will be "Prolog Exception: " appended with a string representation of such exception.
</DL>
<DT><CODE>prolog_event</CODE> <EM>Term</EM>
<DD>
Adds the new <EM>term</EM> to the <EM>terms</EM> queue. These can be later retrieved through predicates
<A NAME="IDX6014"></A>
<CODE>tcl_event/3</CODE> and
<A NAME="IDX6015"></A>
<CODE>tk_next_event/2</CODE>.
</DL>
<P>
Additionally, seven extra Tcl commands are defined.
<DL COMPACT>
<DT><CODE>prolog_delete_event</CODE>
<DD>
Deletes the first <EM>term</EM> of the <EM>terms</EM> queue.
<DT><CODE>prolog_list_events</CODE>
<DD>
Sends all the <EM>terms</EM> of the <EM>terms</EM> queue through the <EM>event_socket</EM>. The last element is <EM>end_of_event_list</EM>.
<DT><CODE>prolog_cmd</CODE> <EM>Command</EM>
<DD>
Receives as an argument the Tcl/Tk code, evaluates it and returns through the <EM>term_socket</EM> the term <EM>tcl_error</EM> in case of error or the term <EM>tcl_result</EM> with the result of the command executed. If the command is <EM>prolog</EM>, upon return, the goal run on the prolog side is received. In order to get the value of the variables, predicates are compared using the <EM>unify_term</EM> command. Returns 0 when the sript runs without errors, and 1 if there is an error.
<DT><CODE>prolog_one_event</CODE> <EM>Term</EM>
<DD>
Receives as an argument the <EM>term</EM> associated to one of the Tk events. Sends the <EM>term</EM> through the <EM>event_socket</EM> and waits for its unification. Then <EM>unify_term</EM> command is called to update the <EM>prolog_variables</EM> array.
<DT><CODE>prolog_thread_event</CODE> <EM>Term</EM>
<DD>
Receives as an argument the <EM>term</EM> associated to one of the Tk events. Sends the <EM>term</EM> through the <EM>event_socket</EM> and waits for its unification. Then <EM>unify_term</EM> command is called to update the <EM>prolog_variables</EM> array. In this case the <EM>term_socket</EM> is non blocking.
<DT><CODE>convert_variables</CODE> <EM>String</EM>
<DD>
Its argument is a string containing symbols that can not be sent through the sockets. This procedure deletes them from the input string and returns the new string.
<DT><CODE>unify_term</CODE> <EM>Term1</EM> <EM>Term2</EM>
<DD>
Unifies <EM>Term1</EM> and <EM>Term2</EM> and updates the the <EM>prolog_variables</EM> array.
</DL>
<P>
The predicates to use Prolog from Tcl are
<A NAME="IDX6016"></A>
<CODE>tk_event_loop/1</CODE>,
<A NAME="IDX6017"></A>
<CODE>tk_main_loop/1</CODE>,
<A NAME="IDX6018"></A>
<CODE>tk_new/2</CODE>, and
<A NAME="IDX6019"></A>
<CODE>tk_next_event/2</CODE>.
<P>
An example of use with Tcl as master and Prolog as slave, implementing the well known "Hello, world!" dummy program (more can be seen in directory examples):
<P>
Prolog side:
<P>
<PRE>
:- use_module(library(tcltk)).
:- use_package(classic).
hello('Hello, world!').
go :-
tk_new([name('Simple')], Tcl),
tcl_eval(Tcl, 'source simple.tcl', _),
tk_main_loop(Tcl),
tcl_delete(Tcl).
</PRE>
<P>
Tcl side (simple.tcl):
<P>
<PRE>
label .l -textvariable tvar
button .b -text "Go!" -command {run}
pack .l .b -side top
proc run {} {
global prolog_variables
global tvar
prolog hello(X)
set tvar $prolog_variables(X)
}
</PRE>
<UL>
<LI><A HREF="ciao_125.html#SEC539">Usage and interface (tcltk)</A>
<LI><A HREF="ciao_125.html#SEC540">Documentation on exports (tcltk)</A>
</UL>
<H2><A NAME="SEC539" HREF="ciao_toc.html#TOC539">Usage and interface (<CODE>tcltk</CODE>)</A></H2>
<div class="cartouche">
<UL>
<LI><STRONG>Library usage:</STRONG>
<CODE>:- use_module(library(tcltk)).</CODE>
<LI><STRONG>Exports:</STRONG>
<UL>
<LI><EM>Predicates:</EM>
<A NAME="IDX6020"></A>
<CODE>tcl_new/1</CODE>,
<A NAME="IDX6021"></A>
<CODE>tcl_eval/3</CODE>,
<A NAME="IDX6022"></A>
<CODE>tcl_delete/1</CODE>,
<A NAME="IDX6023"></A>
<CODE>tcl_event/3</CODE>,
<A NAME="IDX6024"></A>
<CODE>tk_event_loop/1</CODE>,
<A NAME="IDX6025"></A>
<CODE>tk_main_loop/1</CODE>,
<A NAME="IDX6026"></A>
<CODE>tk_new/2</CODE>,
<A NAME="IDX6027"></A>
<CODE>tk_next_event/2</CODE>.
<LI><EM>Regular Types:</EM>
<A NAME="IDX6028"></A>
<CODE>tclInterpreter/1</CODE>,
<A NAME="IDX6029"></A>
<CODE>tclCommand/1</CODE>.
</UL>
<LI><STRONG>Other modules used:</STRONG>
<UL>
<LI><EM>System library modules:</EM>
<A NAME="IDX6030"></A>
<CODE>tcltk/tcltk_low_level</CODE>,
<A NAME="IDX6031"></A>
<CODE>iso_misc</CODE>,
<A NAME="IDX6032"></A>
<CODE>write</CODE>,
<A NAME="IDX6033"></A>
<CODE>strings</CODE>,
<A NAME="IDX6034"></A>
<CODE>lists</CODE>.
</UL>
</UL>
</div class="cartouche">
<H2><A NAME="SEC540" HREF="ciao_toc.html#TOC540">Documentation on exports (<CODE>tcltk</CODE>)</A></H2>
<P>
<A NAME="IDX6035"></A>
<A NAME="IDX6036"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>tcl_new/1:</B>
<DD><A NAME="IDX6037"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>tcl_new(-TclInterpreter)</CODE>
<UL>
<LI><EM>Description:</EM> Creates a new interpreter, initializes it, and returns a handle to it in <CODE>TclInterpreter</CODE>.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>-TclInterpreter</CODE> is a reference to a <EM>Tcl</EM> interpreter.
(<CODE>tcltk:tclInterpreter/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX6038"></A>
<A NAME="IDX6039"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>tcl_eval/3:</B>
<DD><A NAME="IDX6040"></A>
<P>
<EM>Meta-predicate</EM> with arguments: <CODE>tcl_eval(?,?,addmodule)</CODE>.
<P>
<STRONG>Usage:</STRONG> <CODE>tcl_eval(+TclInterpreter, +Command, -Result)</CODE>
<UL>
<LI><EM>Description:</EM> Evaluates the commands given in <CODE>Command</CODE> in the Tcl interpreter <CODE>TclInterpreter</CODE>. The result will be stored as a string in <CODE>Result</CODE>. If there is an error in <EM>Command</EM> an exception is raised. The error messages will be <EM>Tcl Exception:</EM> if the error is in the syntax of the Tcl/Tk code or <EM>Prolog Exception:</EM>, if the error is in the prolog term.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+TclInterpreter</CODE> is a reference to a <EM>Tcl</EM> interpreter.
(<CODE>tcltk:tclInterpreter/1</CODE>)
<CODE>+Command</CODE> is a <EM>Tcl</EM> command.
(<CODE>tcltk:tclCommand/1</CODE>)
<CODE>-Result</CODE> is a string (a list of character codes).
(<CODE>basic_props:string/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX6041"></A>
<A NAME="IDX6042"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>tcl_delete/1:</B>
<DD><A NAME="IDX6043"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>tcl_delete(+TclInterpreter)</CODE>
<UL>
<LI><EM>Description:</EM> Given a handle to a Tcl interpreter in variable <CODE>TclInterpreter</CODE>, it deletes the interpreter from the system.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+TclInterpreter</CODE> is a reference to a <EM>Tcl</EM> interpreter.
(<CODE>tcltk:tclInterpreter/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX6044"></A>
<A NAME="IDX6045"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>tcl_event/3:</B>
<DD><A NAME="IDX6046"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>tcl_event(+TclInterpreter, +Command, -Events)</CODE>
<UL>
<LI><EM>Description:</EM> Evaluates the commands given in <CODE>Command</CODE> in the Tcl interpreter whose handle is provided in <CODE>TclInterpreter</CODE>. <CODE>Events</CODE> is a list of terms stored from Tcl by <EM>prolog_event</EM>. Blocks until there is something on the event queue
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+TclInterpreter</CODE> is a reference to a <EM>Tcl</EM> interpreter.
(<CODE>tcltk:tclInterpreter/1</CODE>)
<CODE>+Command</CODE> is a <EM>Tcl</EM> command.
(<CODE>tcltk:tclCommand/1</CODE>)
<CODE>-Events</CODE> is a list.
(<CODE>basic_props:list/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX6047"></A>
<A NAME="IDX6048"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>tclInterpreter/1:</B>
<DD><A NAME="IDX6049"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>tclInterpreter(I)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>I</CODE> is a reference to a <EM>Tcl</EM> interpreter.
</UL>
</DL>
<P>
<A NAME="IDX6050"></A>
<A NAME="IDX6051"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>tclCommand/1:</B>
<DD><A NAME="IDX6052"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>tclCommand(C)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>C</CODE> is a <EM>Tcl</EM> command.
</UL>
</DL>
<P>
<A NAME="IDX6053"></A>
<A NAME="IDX6054"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>tk_event_loop/1:</B>
<DD><A NAME="IDX6055"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>tk_event_loop(+TclInterpreter)</CODE>
<UL>
<LI><EM>Description:</EM> Waits for an event and executes the goal associated to it. Events are stored from Tcl with the <EM>prolog</EM> command. The unified term is sent to the Tcl interpreter in order to obtain the value of the tcl array of <EM>prolog_variables</EM>. If the term received does not have the form <CODE>execute(Goal)</CODE>, the predicate silently exits. If the execution of <CODE>Goal</CODE> raises a Prolog error, the interpreter is deleted and an error message is given.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+TclInterpreter</CODE> is a reference to a <EM>Tcl</EM> interpreter.
(<CODE>tcltk:tclInterpreter/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX6056"></A>
<A NAME="IDX6057"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>tk_main_loop/1:</B>
<DD><A NAME="IDX6058"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>tk_main_loop(+TclInterpreter)</CODE>
<UL>
<LI><EM>Description:</EM> Passes control to Tk until all windows are gone.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+TclInterpreter</CODE> is a reference to a <EM>Tcl</EM> interpreter.
(<CODE>tcltk:tclInterpreter/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX6059"></A>
<A NAME="IDX6060"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>tk_new/2:</B>
<DD><A NAME="IDX6061"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>tk_new(+Options, -TclInterpreter)</CODE>
<UL>
<LI><EM>Description:</EM> Performs basic Tcl and Tk initialization and creates the main window of a Tk application.<CODE>Options</CODE> is a list of optional elements according to:
<DL COMPACT>
<DT><CODE>name(+ApplicationName)</CODE>
<DD>
Sets the Tk main window title to <CODE>ApplicationName</CODE>. It is also used for communicating between Tcl/Tk applications via the Tcl <EM>send</EM> command. Default name is an empty string.
<DT><CODE>display(+Display)</CODE>
<DD>
Gives the name of the screen on which to create the main window. Default is normally determined by the <CODE>DISPLAY</CODE> environment variable.
<DT><CODE>file</CODE>
<DD>
Opens the sript <CODE>file</CODE>. Commands will not be read from standard input and the execution returns back to Prolog only after all windows (and the interpreter) have been deleted.
</DL>
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+Options</CODE> is a list.
(<CODE>basic_props:list/1</CODE>)
<CODE>-TclInterpreter</CODE> is a reference to a <EM>Tcl</EM> interpreter.
(<CODE>tcltk:tclInterpreter/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX6062"></A>
<A NAME="IDX6063"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>tk_next_event/2:</B>
<DD><A NAME="IDX6064"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>tk_next_event(+TclInterpreter, -Event)</CODE>
<UL>
<LI><EM>Description:</EM> Processes events until there is at least one Prolog event associated with <CODE>TclInterpreter</CODE>. <CODE>Event</CODE> is the term correspondig to the head of a queue of events stored from Tcl with the <EM>prolog_event</EM> command.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+TclInterpreter</CODE> is a reference to a <EM>Tcl</EM> interpreter.
(<CODE>tcltk:tclInterpreter/1</CODE>)
<CODE>-Event</CODE> is a string (a list of character codes).
(<CODE>basic_props:string/1</CODE>)
</UL>
</DL>
<P><HR><P>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_124.html">previous</A>, <A HREF="ciao_126.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
</BODY>
</HTML>
