Beth Embedding Information
--------------------------

Beth has the capability to be easily embedded with other programs. This
directory contains a few examples, each of which contain instructions on
configuring them to be run under your system.


rmth
----

A combination of a shell emulator, wish tutorial, and remote interpreter that
uses Beth. For more information, see the README file in the rmth directory.


tkcolors
--------

Brings up a Beth window on an rgb.txt file, and colors each line with its
appropriate color. Takes a starting color as command-line argument, if none
given, starts with first color in file. To avoid limited colormap problems,
re-allocates colors during scrolling, this sometimes requires user to press
button-1 after scrolling to update the colors being displayed.


tkfonts
-------

Brings up a Beth window on a list of fonts (by default provided by the xlsfonts
command), using each font on the line that gives its name. Takes a starting
font as command-line argument, if none given, starts with first. Warning, this
program takes some time to start up.


thinfo
------

Adds Beth functionality to tkinfo.


thinspect
---------

Adds Beth functionality to tkinspect.


tknews.patch
------------

Adds Beth functionality to tknews. This is a patch file, not an executable.


How to embed Beth
-----------------

Assimilating Beth with a Tk program is a snap. Beth's global variables are
documented in the HELP file under the beth.config.tcl section. The global
variables of Beth that control startup behavior are designed to take their
default values only if they have not been set before beth was started. Thus to
alter Beth's startup behavior, you set the variables before sourcing Beth.

You will need to know the name of your program's text widget, and a frame widget
for Beth to use. (If none exists then Beth will make its own.) Be aware that the
window resizing functions will only work if the window is gridded to the text
widget, and the grid may not always show up where you expect. Rmth is useful for
finding these things out, so is HierQuery. You should also find out what your
program does upon exiting, and tie Beth's quitting routines in. This should be
fairly straightforward, as Beth provides a quit_hook variable that gets executed
when it exits. Generally, you'll want to configure any means your program has to
quit to call quit_beth, which is Beth's quit procedure. Then bind quit_hook to
your program's quitting procedure.

As an example to see the ease in merging programs, let's examine thinfo. It's
about 20 lines long.

	#!/afs/ece/usr/tcl/bin/wish -f

To run this program, you should make sure the top line reflects the location of
wish on your system, and the following variables represent the locations of
tkinfo and beth:

	set info_src "/afs/ece/usr/svoboda/src/tkinfo-0.6/tkinfo.tcl"
	set beth_dir "/afs/ece/usr/svoboda/src/beth"

Load up tkinfo

	source $info_src

Let Beth know what tkinfo's important widgets are.

	set text .tki1.main.text
	set frame .tki1.s
	set dont_make_quit 1
	set dont_make_menubar 1

Beth doesn't need to load anything, and should only browse.

	set option ""
	set configs "-b"

Beth is embedded in tkinfo.

	set embedded 1

Now load up Beth.

	source $beth_dir/beth.tcl

Tell tkinfo to call quit_beth instead of its own quitting routine.

	.tki1.buts.quit configure -command quit_beth

Tell beth to call tkinfo's quitting routine when Beth quits.

	set quit_hook {_tkiDpyWinAction .tki1 quit}

Finally focus on the text widget (where Beth's bindings apply)

	focus default $text ; focus $text



If you assimilate Beth with any major Tcl programs, I would be interested in
hearing about it; it might get included with this small library.


RCS Change Log
--------------

	$Log: README,v $


Maintainer
----------

Send bugs and suggestions to:
David Svoboda	svoboda@ece.cmu.edu
