%
% STk Reference manual (Appendix: Using the Tk toolkit)
%
%           Author: Erick Gallesio [eg@unice.fr]
%    Creation date: ??-Nov-1993 ??:??
% Last file update: 10-Feb-1995 14:15
%

When {\stk} detects that a \var{tk-command} must be called, parameters are
processed to be recognized by the corresponding toolkit function. Since the Tk
toolkit is left (nearly) unmodified, all its primitives ``think'' there is a
running Tcl interpreter behind the scene. Consequently, to work with the Tk
toolkit, a little set of rewriting rules must be known. These rules are
described hereafter.

\begin{note}
This appendix is placed here to permit an {\stk} user to make programs with
the original Tcl/Tk documentation by hand. In no case will it substitute to
the abundant Tcl/Tk manual pages nor to the excellent book by
J.~Ousterhout\cite{Ouster-book}
\end{note}

\section{Calling a tk-command}

Since Tcl uses strings to communicate with the Tk toolkit, parameters to a
\var{tk-command} must be translated to strings before calling the C function
which implement it. The following conversions are done, depending on the type
of the parameter that {\stk} must give to the toolkit:
\begin{quote}
\begin{description}
\item[symbol:] the print name of the symbol;
\item[number:] the external representation of the number expressed in radix 10;
\item[string:] no conversion;
\item[keyword:] the print name of the keyword where the initial semicolon has
been replaced by a dash (``-'');
\item[boolean:] the string "0" if {\schfalse} and "1" if \schtrue
\item[tk-command:] the name of the \var{tk-command}
\item[otherwise:] the external ``slashified'' version of the object.
\end{description}
\end{quote}
As an example, let us make a button with a label containing the
string {\tt "Hello, word"}. According the original Tk/Tcl documentation,
this can be done in Tcl with
\begin{scheme}
button .hello -text "Hello, world"
\end{scheme}
Following the rewriting rules expressed above, this can be done in {\stk} with
\begin{scheme}
(button '.hello '-text "Hello, world")
\end{scheme}
This call defines a new widget object which is stored in the {\stk} variable {\tt
.hello}. This object can be used as a procedure to customize our button.
For instance, setting the border of this button to 5 pixels wide and its
background to gray would be done in Tcl with
\begin{scheme}
.hello configure -border 5 -background gray
\end{scheme}
In {\stk} this would be expressed as
\begin{scheme}
(.hello 'configure '-border 5 '-background "gray")
\end{scheme}
Since keyword colon is replaced by a dash when a \var{tk-obj} is called, this
expression could also have been written as:
\begin{scheme}
(.hello 'configure{\bf :border} 5{\bf :background} "gray")
\end{scheme}

Suppose now, that we want to associate a command with the previous button; the
command is supposed to writes a message before quitting the application on
mouse click. In Tcl, this can be expressed by
\begin{scheme}
.hello configure -command \{puts stdout "Hello, world"; destroy .\}
\end{scheme}
In {\stk}, we'll have
\begin{scheme}
(.hello 'configure{\bf :command} '(begin
                                   (display "Hello, world\backwhack{}n")
                                   (destroy *root*)))
\end{scheme}

When the user will press the mouse left button, the \ide{begin}
form will be evaluated in the global environment. Evaluation of this form will
display the message and call the {\tt destroy} \ide{Tk-command}.

\begin{note}
\label{root window}
The root widget is denoted ``.'' in Tcl. This convention is ambiguous with the
dotted pair convention and the dot must be quoted to avoid problems. Since
this problem arises so often, the variable {\tt *root*} has been introduced in
{\stk} to denote the Tk main window.
\end{note}

\section{Result of a tk-command}

When an entry of the Tk toolkit finishes its work, it returns its result as a
string. As it is not convenient in the Scheme world, the {\stk}
interpreter tries to give a result with the most appropriate type. Here also, a
little set of rules must be known:
\begin{enumerate}
\item 
If the result ``looks'' like a {\stk} basic type it is converted into it.
\item
If the Tcl/Tk original documentation states that the result is a list, it is
converted into a list (i.e. if the toolkit yields a null string the result is 
the empty list, otherwise the result is a list whose length is the number of
items yielded by the toolkit)
\item
If the result contains several values, they are put into a list.
\end{enumerate}

For instance, with our previous button we'll have
\begin{scheme}
(.hello 'configure{\bf :border})  \lev (-borderwidth borderWidth BorderWidth "2" 5)
(.hello 'configure{\bf :text})    \lev (-text text Text " " "Hello, world")
\end{scheme}

\begin{note}
Since accessing an option value is a current operation, a reader and a 
writer function have been defined: \ide{tk-get} and \ide{tk-set!}.
\begin{scheme}
(tk-set! .hello{\bf :text} "Bye")
(tk-get .hello{\bf :text})      \lev "Bye"
(tk-get .hello{\bf :border})    \lev 5
\end{scheme}
\end{note}

Some \var{tk-command}s don't behave as described before (i.e. they always yield
their result as a string and don't try to give a ``clever'' value). These 
\var{tk-command}s are:
\begin{itemize}
{\tt
\item option
\item selection
\item tk
\item wm
}
\end{itemize}
