The TkSteal extension

Copyright (c) 1993 by Sven Delmas
All rights reserved.
See the file COPYRIGHT for the copyright notes.

Changes:
--------
	- Some minor bug fixes.


What is TkSteal ?
-----------------
This small extension to Tk allows the embedding of external
programs like emacs and ghostscript. This widget gives you
COMPLETE access to emacs and ghostscript, which means that
these programs are completely integrated into your Tk
interface.

To embed emacs, you can use the "tkemacs" command. The
"tkgs" command can be used to embed ghostscript, and the
command "tksteal" is a general interface to embed other
applications (like xclock etc.). Take a look at the demos in
the demo.TkSteal directory to see how to work with these
commands. The files "./demo.TkSteal/tkEmacs3.tcl",
"./demo.TkSteal/tkGS1.tcl", "./demo.TkSteal/tkSteal1.tcl"
and "./demo.TkSteal/tkSteal2.tcl" are most interesting.

The file "./demo.TkSteal/windowTree.tcl" is an application
which displays the complete X window tree and allows you to
select windows for mapping, unmapping or reparenting. If you
have problems with reparenting, please play a little with
this program to see which window hierarchy contains the
window that has to be reparented. Please be careful with
this program as you can kill your X server with it.

The file "./demo.TkSteal/xtermwish.sh" is a small demo that
embeds an xterm with the running wish into the wish's
widget hierarchy. This demo requires Tk 3.6, as you have to
install (append) the code in the file "./demo.TkSteal/wishrc" 
to the file "~/.wishrc". Once you have done this, you can
activate the wish with "xtermwish.sh".

In the subdirectory "./xfemacs", you can find an application
that uses the TkEmacs widget. It is an emacs with
scrollbars, menus, fileselector boxes, etc.. The library
file named xfemacs.tcl is installed to the directory that
is specified with the variable XF_EMACS_LIBRARY in the
Makefile.

This distribution contains the code required to build a new
wish (3.2 or 3.6). It should not be necessary to change any
existing applications to embed it into the widget. If you
want to use emacs 18.59, please read the installation guide
carefully, as the emacs 18.59 distribution seems to have a
bug that must be fixed first before you can use emacs 18.59
as a Tk widget.


WARNING!
--------
If you use this widget (program), be aware of the fact that
it can cause trouble. It was tested, but as emacs is a
complex system and Tk is a complex system, too, there may
still be some problems.

If you encounter any problems, please let us know. If you
are able to locate the bug, please send problems, bug fixes
and ideas to:

	tkemacs@cs.tu-berlin.de

Feel free to modify/adapt the sources and to write new lisp
functions for improved functionality. If you do so, please
let us know, so that we can improve the widget for us and
the other users (if there are any).


Requirements:
-------------
	- The Tk-3.2 or the Tk-3.6 package.

	- Emacs 18.57 or a later version or Lucid emacs 19.6
	  (other versions should work as well; the patch
	  doesn't do anything really fancy).

	- The tclRawTCP package from Tim MacKenzie
          (this package is part of the distribution), or the
          Tcl-DP package from Lawrence A. Rowe, Brian Smith,
          and Steve Yen (this package is not part of the
          distribution). The Tcl-DP package is available at:
	    harbor.ecn.purdue.edu


Building a patched wish:
------------------------
	- Please first take a look into the "Portability"
	  section at the bottom. The installation may
	  require a special handling for your system.

        - Unpack the TkSteal distribution, and change into
	  the TkSteal directory.

	- Type "./configure" in this directory. This runs a
	  configuration script created by GNU autoconf,
	  which configures TkSteal for your system and
	  creates a Makefile.

	- You should check the generated Makefile and adapt
	  it to your needs. TCL_DIR and TK_DIR have to point
	  at the directories containing the built libraries
	  and headers. It is also possible to select
	  additional packages to be included into the wish.

	- If you have built the Tk library with TkPixmap
	  support, you have to uncomment the corresponding
	  statements in the Makefile.

	- Choose if you want to build the wish with
	  tclRawTCP or Tcl-DP. Set the correct flag for
	  TKSTEAL_CFLAGS and the correct library name (only
	  required for Tcl-DP).

	- Type "make" to build the Tk3.6 wish. To build a
	  Tk3.2 wish, type "make wish3.2". In both cases,
	  you will get an executable named "wish".

	- To build dynamically loadable libraries, uncomment
	  the corresponding variable in the Makefile and
	  type "make dynload". This will build a file named
	  "libtkXAccess.so". Install this file to a
	  directory where your dynamic loading command can
	  find it. As this dynamic loading for Tcl is
	  currently under development and as it is machine
	  dependent, this may not work for your machine.

	- Type "make install" will install the executable,
	  the docs and the library files. To only install
	  the extension files "make install-extensions" can
	  be used. By default, the library files are placed
	  in the TK_LIBRARY directory. The original Tk
	  tclIndex has to be changed. It must contain the
	  new commands "tkemacs", "tkgs" and "tksteal".
	  Please take care to keep the tclIndex file up to
	  date when you install other packages. For Tk 3.2,
	  the tclIndex must contain the following lines:
		tkemacs tkEmacs.tcl
		tksteal tkSteal.tcl
		tkgs tkGS.tcl

	  For Tk 3.6, the following lines have to be
	  included:
		set auto_index(tkemacs) "source [set dir]/tkEmacs.tcl"
		set auto_index(tksteal) "source [set dir]/tkSteal.tcl"
		set auto_index(tkgs) "source [set dir]/tkGS.tcl"

	  You can add these lines by hand (as described
	  above), you can use the Makefile target
	  "make-tclIndex", or you can use auto_mkindex.

	- To see what the widgets can do for you, change to
	  the directory named demo.TkSteal and type
	  "../steal-wish -f tkEmacs1.tcl" (do this for all
	  tcl files in the directory).


Preparing emacs:
----------------
	- Make a symbolic link (or a small shellscript or
	  a link/copy of emacs) from your emacs to an
	  executable named TkEmacs. This means that you can
	  call your favorite emacs by typing TkEmacs. This
	  is required to make the selection of the correct
	  emacs easier (TkEmacs is the default emacs used by
	  the emacs widget).

	- Install all .el files from the TkSteal
	  distribution in an emacs lisp directory. TkEmacs
	  must be enabled to find these lisp files
	  automatically. The file advice.el is part of
          this distribution for the emacs 18.59 users. The
	  installation of this file is only required under
	  emacs 18.59 (or previous versions).

	- The file cl.elc from the standard distribution of
	  emacs 18.59 seems to have problems. Please replace
	  it with a (local) new byte compiled version. If you
          have problems with compiling cl.el, simply remove
	  the compiled version. This way you are using the
	  uncompiled version. This has no negative effects.


Problems ?!:
------------
The only major problem is that sometimes, you only get an
empty toplevel, and/or hear a beep. In this case, one of the
following points might help you:

	1) Did you remove cl.elc (emacs 18.59) ?
		- in the shell, you type:
			emacs
		- in emacs, you type:
			M-x describe-variable
			load-path
		- then, you get the current contents of the
		  load path. Now look if you can find cl.elc
		  in one of these directories. If you do,
		  one of the previous directories must
		  contain "cl.el".

	2) Did you install the new wish under the name steal-wish ?
		- in the shell, you type:
			steal-wish
		- you get a running wish.

	3) Did you install the new wish library files in the
	   Tk library directory ?
		- in the shell, you type:
			steal-wish
		- in wish, you type:
			tkemacs .t
		- if that command fails with an:

			  invalid command name "tkemacs"
		  
		  you have probably forgotten to install the
		  library file, or you have not adapted the
		  tclIndex file in the Tk library directory.

	4) Did you provide a emacs named TKEmacs ?
		- in the shell, you type:
			TkEmacs
		- you get a running emacs.

	5) Did you install the emacs lisp files where emacs can find
	   them ?
		- in the shell, you type:
			emacs
		- in emacs, you type:
			M-x load-library
			tk-comm
		- Then, you get the emacs message:
			Loading tk-comm done
		- Then, you should repeat this procedure with:
			advice, tk-funcs, tkemacs and tk-app-hooks

	6) Did you really build an "X" emacs ?
		- probably, you did not uncomment
		  HAVE_X_WINDOWS, so your emacs shows up in
		  the xterm where you started xfemacs.

	7) Did you really build an emacs with socket support ?
		- probably, you did not define HAVE_SOCKETS,
		  so your emacs does not know the lisp
		  command "open-network-stream". 

	8) Did you apply/install all changes to wish correctly ?
		- in the shell, you type:
			steal-wish
		- in wish, you type:
			wm geometry . 500x500
			tkemacs .t
			pack append . .t top
		- the command returns .t, and the toplevel
		  window contains an emacs.

	9) A non-working wish can be caused by not including
	   a communication package into Tk, when building
	   the patched wish.

       10) A non-working xfemacs can be caused by a not
	   correctly adapted XF_LOAD_PATH or WISH_CMD
	   variable in the xfemacs.sh file.

       11) When terminating emacs from inside of emacs it
	   can happen that you get the message:

	     "Active processes exist; kill them and exit anyway? (yes or no)"

	   this is because the function 'save-buffers-kill-emacs' is
	   called before the tk-kill-emacs-hook is called. So the
	   communication is still open. I see no way to work around
	   this problem (without changing the emacs lisp code). Maybe
	   someone knows a simple solution ?!


Compatibility notes:
--------------------
We tried to keep the changes to Tk and emacs as small as
possible (smaller than for the old version of TkEmacs). The
changes to Tk only add a new command to Tk (xaccess(n)). If
you don't use the new command, you will not notice any
changes compared to the standard wish. You no longer have to
apply any changes to emacs or other programs that should be
embedded.

The basic concept of this widget is that the main window of
the embedded application is reparent to a Tk widget. Certain
events passed to the Tk window are passed to the reparented
window (like configure events etc.).

Apart from these mechanisms for passing X11 events, there
are additional features to pass informations (like access to
X properties, TCP connections). 


Portability:
------------
Esix:
	- On my (new) System V Rel 4 system, tclRawTCP does
	  not work correctly. I had to make a minor (ugly)
	  change that is activated in the file ./main3.2.c
	  with the define MY_SYSVR4_FIX.
	- On my (old) System V Rel 3 system, no UNIX domain
	  sockets are available. So I just removed the
	  inclusion of the file <sys/un.h>, as well as the
	  call and the definition of the procedure
	  "unix_connect". I also inserted a warning in case
	  the user tries to open a UNIX domain socket. These
	  changes are not part of the distribution. 


Availability:
-------------
The TkSteal distribution file is named TkSteal3.6?.tar.gz
or TkSteal3.6?.tar.Z. The ? represents the current version.
TkSteal is available via anonymous ftp at:
	harbor.ecn.purdue.edu:	pub/tcl/extensions/
	ftp.ibp.fr:		pub/tcl/contrib/extensions/
	nic.funet.fi:		pub/languages/tcl/extensions/
        syd.dit.csiro.au:       pub/tk/contrib/extensions/
	ftp.cs.tu-berlin.de:	pub/tcl/contrib/extensions/

To get a copy of it, just type the following:

	ftp ftp.cs.tu-berlin.de
        bin
	cd pub/tcl/contrib/extensions
	get TkSteal3.6?.tar.gz

To get a copy via ftpmail, just send the following mail to:

      	mail-server@cs.tu-berlin.de

To get a help message, send the following body:

	send HELP
	end

To retrieve TkSteal, send the following body:

	send pub/tcl/contrib/extensions/TkSteal3.6?.tar.gz
	end


Feedback (Authors):
------------------
General address:
TU Berlin, Germany
tkemacs@cs.tu-berlin.de

Sven Delmas
TU Berlin, Germany
garfield@cs.tu-berlin.de

Juergen Nickelsen
TU Berlin, Germany
nickel@cs.tu-berlin.de

