%
% sccsid("@(#)doc	1.4          93/12/01").
% sccscr("@(#)  Copyright 1993 ECRC GmbH ").
%


	Predicates for the Prolog interface to Tcl/Tk - ProTcl
	------------------------------------------------------

The Tcl/Tk interface is in the library tk, use
	:- use_module(library(tk))
to load it. The following predicates become available:

tk_demo
	Starts the Tcl/Tk demo program.

tk_test
	Starts the Tcl/Tk test program suite

tk_file(File, Options)
	Implements the Tcl/Tk command

		wish -f File [other options]

	Options is nil or a list of options from

		[geometry(G), display(D), name(N), sync]

	This command is to be used when there are no further Prolog goals
	to be directly executed. After Tk reads and executes the file,
	it enters its main loop that waits for events and serves them.
	This predicate exits after all Tk windows have been destroyed,
	i.e. using the Tcl command 'exit'. It is not possible to
	use it for directly interpreting Tcl, use tk/1 for that purpose
	(if available).


tk(Options)
	Implements the Tcl/Tk command

		wish [options]

	Options is the same as in tk_file/2. This predicate is used
	for interactive work with Tk. It succeeds after creating
	the top-level Tk window. Then it is possible to execute
	Tcl/Tk commands in it. This predicate changes the Prolog
	top-level loop so that while waiting for the user query
	it also checks if there are any X events pending and if so,
	it executes them. When a Prolog program is active,
	it has to poll the events itself, e.g. using tk_do_one_event/1.


tk_main_loop
	Starts the Tk main loop which polls the events and serves them.
	It succeeds after all windows have been destroyed.


tk_do_one_event(Mask)
	This is an interface to the Tk function Tk_DoOneEvent(). It waits
	for a single event, invokes the handler(s) for it and
	succeeds. If Mask is not zero, it is taken as a bitfields
	of the following flags and the event processing is restricted
	to the specified flags:

	    TK_DONT_WAIT         16'1	don't wait for the events, process
					only those that are ready
	    TK_X_EVENTS          16'2	process X events
	    TK_FILE_EVENTS       16'4	process Tk's file events
	    TK_TIMER_EVENTS      16'8	process timer events
	    TK_IDLE_EVENTS       16'10	process Tk_DoWhenIdle callbacks
	    TK_ALL_EVENTS	 16'1e  process all event types

	Thus e.g. 3 can be used to poll X events.


tcl_eval(Cmd)
	Execute the Tcl/Tk command Cmd. Cmd can be an (Eclipse) string or an
	atom and it is assumed to contain a valid Tcl/Tk command or
	a series of commands separated by newlines or semicolons.

The Tcl command 'exit' is different from Tcl/Tk because it exits
only Tcl but the Prolog process is still running. Use exit_prolog
to exit back to Unix.
There is also a new Tcl command 'prolog' to call Prolog goals from Tcl:

	prolog {pred arg1 arg2 ...} module

The module argument is optional, only constant arguments are supported.
The ECLiPSe version supports atom and number arguments, the SICStus one
only atoms.
Examples:

	prolog true			# call true/0
	prolog {write a}		# call write(a)
	prolog {p a b c} mod1		# call p(a, b, c)

All initialization is done in Prolog, Tcl_AppInit is not called
and .wishrc is not sourced. You can add this to tk_common.pl
if needed. If you don't use info library but use the variable
tcl_library instead, you can also mode the tcl installation
to another directory than where it was compiled, and should still work.
In that case the TK variable should point to the changed
location.
---------------------------------------------------------------------
ECLiPSe only:

wish
	A wish-like interface, it reads commands from the input
	stream and executes them.

ECLiPSe has the means to execute Prolog event handlers in a more
flexible way. The command

	prolog_event [args]

can be used as a callback procedure for Tk events and in this
case Tk does not process them, but it returns the event data
to Prolog which can then call the appropriate Prolog predicate
to handle it. The main difference to the 'prolog' command
being a callback procedure is that the Prolog predicate
is executed at the same level as the main program, whereas
with 'prolog' the callback is executed from inside Tk, which
may cause problems if it is deeply nested.

The following predicates can be used to process these Prolog events:

tk_next_event(List)
	Wait for the next Prolog event. List is a list of arguments
	of the 'prolog_event' command. If no Prolog event
	occurs by the time the application exits, List is 0.

tk_next_event(Mask, List)
	Wait for the next Prolog event, but handle only those Tk events
	that correspond to Mask (see tk_do_one_event/1 above).

tk_get_event(List)
	Return the next Prolog event, if there is any. This predicate
	does not block for events, it returns 0 if no Prolog event
	is currently in the queue. All Tk events encountered in the queue
	are also processed.

tk_get_event(Mask, List)
	Return the next Prolog event, but handle only those Tk events
	currently in the queue that correspond to Mask.

tk_do_one_event(Mask, List)
	Similar to tk_do_one_event/1, but if a Prolog event is encountered,
	List is bound to the command data, otherwise it is 0.

Prolog events which are not processed explicitly by tk_next_event/1,2,
tk_get_event/1,2 or tk_do_one_event/2 raise the event 333.
The handler for this event receives in the second argument the list
of prolog_event arguments.

