1 files changed, 186 insertions, 0 deletions
diff --git a/uitools/README b/uitools/README
new file mode 100644
index 0000000..61471d1
--- /dev/null
+++ b/uitools/README
@@ -0,0 +1,186 @@
+________________________________________________________________________
+About UITools
+
+	There's been talk recently in comp.lang.python of the need
+	for a set of "standard" composite widget classes to complement
+	Tkinter.py.  Here's my attempt to get the ball rolling.
+
+	This library consists of several modules which implement various
+	Python composite widget ("metawidget") classes.  Most of these
+	classes are derived from code which I've been using for the past
+	year or so, but which I haven't heretofore organized.
+
+	Most modules have a "principal export".  That is, they define
+	one main class along with zero or more derived/supporting
+	classes.  The principal export is usually a class named "T". 
+	This implies that these modules should be imported using
+	"import <module>" rather than "from <module> import *".
+
+	Classes which represent dialogs do not include "Dialog" or "Dlg"
+	in the class names.  For example, Alerts.py exports several
+	alert dialog classes having names like Error, Warning, Question,
+	etc;  Shells.py exports classes Main, Toplevel, NonModal and
+	Modal.
+	
+	I omitted the "Dialog" suffix on the grounds that it was
+	redundant.  Please let me know if you think this was a mistake.
+
+	Most modules include their own unit-test code, exported as
+	function main().  If a module is imported as a program's main
+	module, its main() function is automatically invoked.  The
+	main() functions serve not only as rudimentary unit-tests, but
+	also as examples of how to use the classes defined in their
+	containing modules.  For example, Menu.main() fires up a
+	simple-minded text editor, equipped with both Pulldown and Popup
+	menus.
+	
+	Here's hoping this stuff is useful.  At the least, I hope it
+	catalyzes contributions of other Python-based composite widget
+	classes.
+
+
+	-- Mitch Chapman
+	   mchapman@erinet.com
+	   1 December 1996
+
+________________________________________________________________________
+Constituent Modules
+
+
+Alerts.py
+	Provides various error/warning/info dialogs.  This module is
+	inspired by the alerts.py module of the tkdialogs archive.
+
+	The principal exported class, T, is a generic alert dialog.
+	Exported subclasses include:
+		Error	-- for displaying error messages
+		Warning	-- for displaying warnings
+		Question	-- yes/no question presentation
+		Info		-- displays informational messages
+		Instruction	-- asks the user to perform a task and
+				   press "Continue"
+		Progress	-- shows the progress of some operation
+
+ButtonBox.py
+	Provides a frame which packs buttons horizontally.
+	Buttons can be accessed from the .buttons member dictionary,
+	using the labels by which the buttons were initially created.
+
+	(Would a simple array of buttons be easier to use?)
+
+Cursors.py
+	Provides a means of controlling cursors on an application-wide
+	basis.  (For an example of use, see Shells.py.)
+
+KWDict.py
+	Provides a way to construct dictionaries from keyword argument
+	lists.  Many thanks to "Internet Programming With Python,"
+	whence this code was stolen.
+
+LabelEntry.py
+	Provides multi-column, single-column and read-only labelled
+	entries.
+
+Menu.py
+	Provides a convenient means of constructing pulldown and popup
+	menus.  With a single method call you can construct an entire
+	pulldown menu, complete with cascaded submenus.
+
+	Exported classes include Menubar (basically just a Tk.Frame);
+	Item, representing a single item within a menu pane; Pulldown,
+	representing a Menubutton and its associated menu pane; and
+	Pane, which can serve as either the pane for a Pulldown or as a
+	Popup.
+
+	This module was inspired by, but is less capable than, the
+	menu-creation functions in XEmacs 19.14.
+
+	This module needs more work to properly support Checkbutton and
+	Radiobutton menu items.  The current version makes it hard to 
+	associate Tk variables with such menu items.
+
+ProgressBar.py
+	Provides a status bar for displaying task completion percentages.
+	For an example of the use of a progress bar in a dialog, see
+	Alerts.py.
+
+Scrolled.py
+	Provides scrollbar decorations, along with scrolled texts,
+	canvases and lists.  Exports include T, a generic
+	scrolled-window composite class into which an arbitrary "view"
+	widget may be inserted; Text, a scrolled text window; Canvas, a
+	scrolled canvas window; and List, a scrolled listbox.
+
+	This module was written using the Tk packer, rather than the
+	Tk 4.1+ grid widget.  (The 4.1 grid widget looked a little
+	unreliable to me, and apparently not many people have yet
+	installed Tk 4.2.)
+
+	The scrollbars extend only to the bottom-right edge of the
+	scrolled view, using a technique described in Welch's "Practical
+	Programming with Tcl/Tk".  (Dang!  Is that the right title?)
+
+	In this version, both vertical and horizontal scrollbars are
+	displayed fulltime.  I haven't yet found a way to dynamically
+	map and unmap the scrollbars which doesn't introduce
+	"flickering".  (The scrollbar will map and unmap two or three
+	times before settling into a visible or invisible state.)  Your
+	help is kindly requested.
+
+
+Shells.py
+	Provides various top-level, non-modal and modal dialog shells,
+	together with application-wide cursor control.  Exports include
+	Main, a subclass of Tk.Frame; Toplevel, derived from
+	Tk.Toplevel; and NonModal and Modal dialog classes.
+
+	Main and Toplevel are provided because they support
+	application-wide cursor management.  That is, when a
+	Shells.Modal dialog is mapped, all existing Main, Toplevel and
+	NonModal windows display a "do not enter" cursor.
+
+	The dialog classes are similar to those provided by the
+	tkdialogs archive.  They differ in that they can easily be
+	created and initialized without being displayed.  So, for
+	example, if you have a non-modal dialog which shows logged
+	network traffic, you can create it as soon as your application
+	starts and display it only when the user requests to see it.
+
+StdDialog.py
+	Provides "standard" modal and non-modal dialogs, as well as
+	button boxes populated with OK, Cancel and Help buttons.
+
+	Exported classes include Controls, a composite containing a
+	frame and a ButtonBox.T, stacked vertically; StdControls, a
+	subclass of Controls which populates its ButtonBox.T with "OK",
+	"Cancel" and "Help" buttons; NonModal and Modal, two dialog
+	classes whose managed contents consist of StdControl instances.
+
+	This module has a really poor design.  I was trying to build a
+	framework for "typical" dialog windows, which contain a set of
+	controls packed into a frame, below which is a row of
+	dialog buttons.  Class Controls represents the "typical" dialog
+	contents; StdControls represents typical contents along with
+	typical dialog buttons; and NonModal and Modal are dialogs whose
+	innards are StdControls.
+
+	Please help me straighten this out.
+
+TkDlgWrapper.py
+	Provides wrappers around the standard dialogs included with
+	Tk 4.2.  (NOTE:  This module _requires_ Tk 4.2 or later.)
+
+	The most significant exported classes include ChooseColor, an
+	interactive color-selection dialog, and OpenFile and SaveFile,
+	file open/save dialogs which display directory contents using
+	folder and document icons.
+
+	I originally released this module in October 1996 as "TkDialogs.py",
+	not knowing that ftp.python.org already had a tkdialogs archive.
+	Both this module module and the containing archive (UITools)
+	now have names which bear no resemblance to "tkdialogs", so
+	ending any potential name conflicts.  I hope.
+
+	The classes have been renamed to omit "Dlg" from the class
+	names, but are otherwise unchanged from the original release.
+