diff options
author | Lars Wirzenius <liw@liw.fi> | 2019-11-02 10:54:13 +0200 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2019-11-02 10:54:13 +0200 |
commit | 2828885db093be86ef5b2c58f5c05ac3c4ed3664 (patch) | |
tree | 8185b82968b220aa543936e45be34fc239a5c8ea /uitools/README | |
download | slime-2828885db093be86ef5b2c58f5c05ac3c4ed3664.tar.gz |
Diffstat (limited to 'uitools/README')
-rw-r--r-- | uitools/README | 186 |
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. + |