Tkwm - The Tk Window Manager Patches
	------------------------------------

WHAT IS TKWM?
-------------

The tkwm patches are patches and additions for John Ousterhout's Tk
windowing toolkit. They add facilities that make it possible to write
window managers for the X Window System. (These patches are only
useful if you are running Tk under a true X implementation; they
will not work on Windows or on the Macintosh.)

WHAT DOES IT ADD TO TK?
-----------------------

The tkwm patches add three new commands to Tk, and add several new event
types and binding substitutions. The three commands are:

	rootwin - creates a "rootwin" widget. A rootwin widget is
		a Tk widget whose associated window is the display's
		root window. The widget itself doesn't do much, but
		you can create other widgets inside it, e.g. frames
		that you put around window manager clients.

	foreignwin - creates a "foreignwin" widget. A foreignwin
		widget is a widget whose window comes from another
		application. These are used to "encapsulate" other
		applications within a Tk application. (This is good
		for encapsulating a window inside a window-manager
		frame.)

	Xop - gives Tk access to a whole host of X Window System
		operations. This command can retrieve window properties,
		remap the keyboard, control keyboard and pointer
		settings (just like the "xset" command), install
		colormaps, and much more.

The new event types are:

	CirculateRequest - generated when an application wants its
		windows raised/lowered

	ConfigureRequest - generated when an application wants its
		toplevel window moved or resized

	Create - generated when a new window is created

	MapRequest - generated when an application wants its
		main window mapped to the screen

	ResizeRequest - generated when an application wants to have
		its main window resized

In addition, the "bind" command will do the following substitutions:

	%i	substitutes the "window" field from an event,
		represented as a hexadecimal X Window ID.

	%P	substitutes the property name for "Property" events

Also, the Tkwm patches add one more option to the wish executable:
the "-root" option. If invoked with the -root option, wish's root
window will be a rootwin widget instead of a toplevel, i.e. "."
will be the display's root window. (If you wish to write a window
manager, this is the option you want to use when you invoke your
window manager script.)

HOW DO I APPLY THE PATCHES?
---------------------------

The current version of the tkwm patches is a set of diffs against
Tk version 8.2.3. To apply the patches:

	$ tar xf tk8.2.3.tar
	$ cp tkwmpatch8.2.3 tk8.2.3
	$ cd tk8.2.3
	$ mkdir tkwmdemos
	$ patch < tkwmpatch8.2.3
	$ find . -name '*.orig' -exec rm {} \;

Then follow the directions for Tk.

KNOWN BUGS/DEFICIENCIES
-----------------------

Tkwm has a number of bugs, including (but almost certainly not limited
to) the following:

	-Certain bindings on rootwin widgets will not work if you're
	 running another process as window manager. (Only a single
	 application can select ButtonPress events (and some others)
	 on a given window; hence if there's a window manager running,
	 tkwm will be competing with it.)

	-Foreignwin widgets don't always resize themselves correctly.
	 They also always destroy the foreign window, though they
	 should (optionally) be able to "give the window back" to the
	 root window.

	-The Xop command has a bunch of unimplemented subcommands;
	 see the man page to find out which ones.

HOW IS THIS LICENSED?
---------------------

Basicly, you may use these patches for anything you like, in any way
you like. (There's probably not much you can do with them other than
apply them to Tk anyway.) When they have been applied to Tk, Tk's
license terms apply; you do not even need to acknowledge that the tkwm
patches have been applied, although the author of the patches would
appreciate it if you did :-).

DISCLAIMER
----------

As is usual for free software, the author makes NO CLAIMS as to the
merchantability or fitness of this software for any purpose; it is
provided on an as-is basis, and the author takes NO RESPONSIBILITY
for the consequences of running it or using it. In laymans terms,
if the Tkwm patches somehow trash your computer (or anything else),
then IT AIN'T MY PROBLEM, it's YOURS. You've got the source, you
can check it for safety if you like.

COMMNTS/FIXES/SUGGESTIONS
-------------------------

You may send comments, bug reports, bug fixes, and suggestions to:

	Neil McKay
	mckay@eecs.umich.edu

NOTE: While I'm open to constructive suggestions, and will give serious
consideration to anything that's not too off-the-wall (including major
syntax changes), there are a few things that will be routed to /dev/null:

	-pure flames without any technical content

	-requests to port Tkwm to Windows (I don't have a Windows
	 box to do the port, and even if I did, it probably can't
	 be done)

	-requests to port it to another language (e.g. Python or Perl)
	 If *you* want this, then *you* do the port.