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