The TkSteal extension

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

Changes:
--------
	- Tk 3.2 support hes been removed. Use
	  the previous TkSteal release for Tk 3.2.
	- Enhanced configuration
	- Support for shared libs
	- 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. 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:

	garfield@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.6 package (or newer ?).

	- 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 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


Calling configure:
------------------
When you call configure in the temporary TkSteal
build directory (see below, several additional
parameters allow the selection of new packages etc..
Several packages allow the setting of additional 
subparameters. Setting one of these subparameters
means that all default settings for the subparameters
are ignored. So you have to list all required
subparameters by hand. Most parameters are directly
mapped to compiler options, so the configuration can
also be adapted by changing the Makefile directly. The
configuration reads the file "config.init", where the
several default settings are defined. The current
parameters are stored in the file "config.local". This
file can be used by calling configure with
-with-config-local.

IMPORTANT!!!!
If you call configure with new parameters (compared to
a previous call of configure), you should call "make
clean" before you build the new wish.

	-with-config-local
		Call configure with the parameters
		of the last configure call.

	-with-tkpixmap
		This adds the TkPixmap extension to
		the wish. There are several 
		subparameters for this parameter:

		-with-tkpixmap-pinfo
			adds the pinfo(n) command to the
			interpreter
		-with-tkpixmap-uxpm
			adds the uxpm(n) command to the
			interpreter
		-with-tkpixmap-pixmaps
			includes the predefined pixmaps
			into the code
		-with-tkpixmap-xpm
			adds support of Xpm3 pixmaps. This
			requires the Xpm3 library.
		-with-tkpixmap-localxpm
		        causes the use of the local Xpm3
			library. Otherwise, a globally 
			installed Xpm3 library is used, if
			there is any.
		-with-tkpixmap-gif
			adds support of gif pictures. This
			support is restricted to the reading
			of gif pictures. Saving and the
			other commands available for Xpm3 are
			not supported for gif pictures. If
			someone has the required routines,
			please send them to me.
		-with-tkpixmap-raw256
			adds support of raw 256x256 pixmaps
		-with-tkpixmap-dps
                        adds support for dps on a server that
			supports display postscript

	-with-tksteal (default)
		This adds the TkSteal extension to
		the wish.

	-with-tkmegawidget
		This adds the TkMegaWidget extension to
		the wish. There are several 
		subparameters for this parameter:

		-with-tkmegawidget-des
			adds the DES encryption library
			to the TkMegaWidget.
		-with-tkmegawidget-localdes
			causes the use of the local des
			library. Otherwise, a globally 
			installed des library is used, if
			there is any.

	-with-kanji
		This allows the building of a Kanji
		wish. You have to provide the already
		patched Tk source tree under the name
		../tk3.6-jp (or ../tk3.6jp) and the
		patched Tcl source tree under the name
		../tcl7.3-jp (or ../tcl7.3jp).

	-with-tkicon
		This adds the TkIcon extension to
		the wish.

	-with-tkmobal
		This adds the TkMobal extension to
		the wish.

	-with-blt
		This adds the BLT extension to the
		wish. Adding this feature makes it
		necessary to build and install the
		BLT package before you build this
		package.

	-with-itcl
		This adds the itcl extension to the
		wish. Adding this feature makes it
		necessary to build and install the
		itcl package before you build this
		package.

	-with-expect
		This adds the expect extension to the
		wish. Adding this feature makes it
		necessary to build and install the
		expect package before you build this
		package.

	-with-tclX
		This adds the TclX extension to the
		wish. Adding this feature makes it
		necessary to build and install the
		extended Tcl package before you build
		this package.

	-with-tcldp
		This adds the Tcl-DP package to the
		wish. Adding this feature makes it
		necessary to build and install the
		tcl-dp package before you build this
		package.

	-with-tclload
		This adds the dynamic loading package to
		the wish. Adding this feature makes it
		necessary to build the shells package
		before you build this package. The shells
		package must be located in the same
		directory as the other extension packages
		under the name "shells".

	-with-noshlib
		Even if the system supports shared
		libraries, don't build them.


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

	 2) Unpack the Tk distribution. Build the Tk
	    distribution as described in the Tk README. If
	    your system supports shared libraries, and
	    you want to use them, you should build the
	    Tcl and the Tk distribution with the
	    tcltk_shlib package published by Xiaokun Zhu.

         3) Unpack the TkSteal distribution in the same
	    directory where you have unpacked the Tk
	    distribution.

	 4) The resulting directory structure will look
	    about like that:

	    .../
               |
	       +-- tcl7.3
               |
	       +-- tk3.6
               |
               +-- TkSteal
               |
	       +-- TkPixmap
               |
               ....

	    Now change into the new TkSteal directory.

	 5) Configure the distribution by running configure.
	    And do all the things you usually do to get a
	    working Tk. To select certain additional 
	    packages and perform other changes of the new
	    wish, you can call configure with several
	    parameters. Take a look into the configure
	    section above for a detailed list. You should
	    take care that the TK_LIBRARY path is valid.
	    This means that you either use the path from
	    a previous Tk installation, or you create the
	    new path, and copy all Tk library files to that
	    directory.

	 6) If you want to change the toplevel Makefile
	    manually, you have to call:

		make prepare

	    before you can adapt the Makefile. To build the
	    new wish (see 8)) don't call "make", but call:

		make wish
	
	 7) A new libtk will be built, as there are some
	    minor problems with certain packages (especially
	    with tcl-DP). This libtk is totally compatible with
	    the previous libtk (the static and the shared
	    version). So, I decided to install the library
	    under the same name. If you do not want this,
	    change the TK_LIB_NAME in the toplevel Makefile
	    (but remember to read point 6)).
	
	 8) Build the new wish. This will copy the required
	    files to the local directory. Then these files
	    are patched (the protocol can be found in the
	    files *.patch.out). The new local libtk and the
            required local extension libraries are built.
	    Finally the new wish is linked. If your system
	    supports shared libraries, they will be generated
	    automatically. As the position of shared libraries
	    is usually very critical, the libraries are
	    automatically installed in the final library
	    directory when they are built. This makes it
	    necessary that you have write permission for that
	    directory. To build the new wish, type:

		make

	 9) You can now install everything by typing this:

		make install

	    This will install the new wish, the new library
	    files and the new doc. By default, the library
	    files are placed in the TK_LIBRARY directory.
	    The original Tk tclIndex file in the directory 
	    where the new Tk library files are installed
	    (this is usually the Tk library directory... e.g.
	    /usr/local/lib/tk3.6) has to be changed. It must
	    contain the autoload code for the new Tcl commands
	    ("tkemacs", "tksteal", "tkgs"). If you do not add
	    the autoload code, you have to load the files
	    "tkEmacs.tcl", "tkSteal.tcl" or "tkGS.tcl" 
	    explicitly in your code. Please take care to keep 
	    the tclIndex file up to date when you install other
	    packages. The tclIndex file must contain the
	    following lines:

		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"

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

	11) After that, you should test the new installed
	    wish. If everything works fine, you can remove
	    the temporary build directories.


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.

	- If you run Lucid emacs, you cannot use the default
	  executable name TkEmacs for this emacs. You have
	  to specify "-command lemacs" as the tkemacs widget
	  option. So if you want to use lemacs with xfemacs
	  (although I don't see why you should :-), you have
	  to change the string manually:

		if {[catch "tkemacs .frame.text -command TkEmacs -lispfile...

	  to

		if {[catch "tkemacs .frame.text -command lemacs -lispfile...

	  in the file xfemacs.tcl.


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 ?!

	12) Embedding an xterm window with tkSteal.tcl does not
	    work. When you call xterm with the -e parameter to
	    run a command in xterm, you have to call xterm with
	    the -T option to give xterm the "correct" name.


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:
------------
General:
	- If you get an error message about an undefined
	  symbol ___main, you have built your Tk libraries
	  with gcc and the TkSteal code with cc. Please
	  use the same compiler for both packages.

	- If the widgets do not work as expected under the
	  new wish, maybe you have forgotten to adapt the
	  TK_LIBRARY path in the Makefile, or you have not
	  created the new TK_LIBRARY path with all Tk
	  library files.

Extended Tcl:
	- If you build the wish with extended Tcl, you have
          to set the TCL_LIBRARY path to the extended Tcl
	  library path before you call the new wish.


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):
------------------
Sven Delmas
TU Berlin, Germany
garfield@cs.tu-berlin.de

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

