.Dd January 13, 2008
.Dt sml_tk 1
.Os
.Sh NAME
.Nm sml_tk
.Nd Typed and abstract Standard ML interface to Tcl/Tk
.Sh DESCRIPTION
.Nm
is a Standard ML package providing a portable, typed and abstract
interface to the user interface description and command language Tcl/Tk.
It allows the implementation of graphical user interfaces in a structured
and reusable way, supported by the powerful module system of Standard ML.
.Pp
SML programs construct windows as sml_tk datatypes, which are then
transformed into Tcl/Tk commands and sent over a pipe to a child wish
process.
Programs register event handlers with sml_tk, and then execute an event
loop function which receives and dispatches events from the child process.
.Pp
The FreeBSD port supports working versions of SML/NJ (110.65 or greater).
Poly/ML 5.1 is supported, but there appears to be a problem with long
communications to the child process as evidenced in the BigEx example,
possibly because the SysDep structure is largely unimplemented.
Likewise for MLton.
Further investigation is required.
.Pp
Moscow/ML and the blessed version of SML/NJ are not supported by the FreeBSD
port, although they are in the standard distribution.
These compilers use a deprecated version of the SML Basis Library: patches
for the newer compilers cause errors.
.Pp
.\"
.Ss Using the library
The sml_tk library can be used in several different ways:
.Bl -tag -width "MMM"
.It Sy SML/NJ Executable
The SML/NJ build installs an executable
.Nm sml_tk ,
which gives an interactive loop with the sml_tk bindings.
One could type, for example:
.Dl BigEx.go ();
.\"
.It Sy SML/NJ Library
The library may be imported into an interactive session:
.Bd -literal -compact -offset indent
CM.make "%%PREFIX%%/lib/sml_tk/sources.cm";
.Ed
or included in another
.Li .cm
file.
Possibly by adding a line to
.Pa $HOME/.smlnj-pathconfig :
.Dl sml_tk.cm  %%PREFIX%%/lib/sml_tk
and then including the library with
.Dl $/sml_tk.cm .
.\"
.It Sy Poly/ML Saved State
The Poly/ML build saves the compiled bindings, they can be loaded with the
command:
.Bd -literal -compact -offset indent
PolyML.SaveState.loadState "%%PREFIX%%/lib/sml_tk/sml_tk.poly";
.Ed
One could then type, for example:
.Dl CanvasEx.go ();
.It Sy Poly/ML Compile
To compile the bindings into Poly/ML, run:
.Bd -literal -compact -offset indent
use "%%PREFIX%%/lib/sml_tk/root_poly.sml";
.Ed
.\"
.It Sy MLton Compile
Include one or both of the basis files
.Pa %%PREFIX%%/lib/sml_tk/sml_tk.mlb ,
.Pa %%PREFIX%%/lib/sml_tk/toolkit/toolkit.mlb .
.Pp
For example, to run the ScaleEx example, create a file
.Pa scaleex.sml :
.Bd  -literal -offset indent
val _ = ScaleEx.go ();
.Ed
.Pp
and a file
.Pa scaleex.mlb :
.Bd  -literal -offset indent
$(SML_LIB)/basis/basis.mlb
%%PREFIX%%/lib/sml_tk/sml_tk.mlb
"%%%PREFIX%%/lib/sml_tk/tests+examples/scale_ex.sml"
scaleex.sml
.Ed
.Pp
Then build
.Pa scalex
by typing:
.Li mlton scaleex.mlb
.El
.\"
.Sh ENVIRONMENT
Three sml_tk environment variables can be used to override the installed
defaults:
.Bl -column -compact .Ev SMLTK_LOGFILE
.It Ev SMLTK_TCL Ta Path to the wish executable
.It Ev SMLTK_LIB Ta Path to the sml_tk library files (default: %%PREFIX%%/share/sml_tk)
.It Ev SMLTK_LOGFILE Ta Set to log communications between the library and
wish.
.El
.Sh EXAMPLES
The main library comes with several example structures, each contains a
.Li go
function of type
.Li unit -> string :
.Bl -column -offset indent "ListBoxEx" "ListBoxEx" "ListBoxEx"
.It ListBoxEx Ta GridEx Ta BigEx
.It CanvasEx Ta PopUpEx Ta ScaleEx
.It TagEx Ta WBindEx
.El
.Pp
The toolbox library also comes with several example structures, each with a
.Li go
function:
.Bl -column -offset indent "SimpleInst" "FilerEx" "LittleTreeList"
.It WeeBoxes Ta FilerEx Ta MarkupEx
.It TableEx Ta TabsEx Ta LittleTreeList
.It SimpleInst Ta UW_Ex Ta StdMarkEx
.El
.Sh COMPATIBILITY
The port adds two non-standard features:
.Bl -tag
.It Li Config.showColor
Exposes a function mapping colors to their names.
.It Li WidgetTree.addLItemConf, WidgetTree.clearLItemConf
Allow formatting of list items.
.El
.Sh SEE ALSO
The website:
.Pa http://www.informatik.uni-bremen.de/~cxl/sml_tk/
.Pp
Local documentation: %%PREFIX%%/share/doc/sml_tk/manual.html
.Pp
.Xr wish 1 ,
and the rest of the Tcl/Tk documentation.
.\"
.Sh AUTHORS
.An Christoph L\[:u]th and Burkhart Wolff
wrote
.Nm
and the first paragraph of this man page.
.Pp
.An Timothy Bourke Aq timbob@bigpond.com
wrote the rest of the man page and some of the patches for the FreeBSD port.
.Sh BUGS
More work is required for Poly/ML and MLton.
The Filer example crashes.
.\"