The jstools libraries are a collection of Tk/Tcl libraries used by the jstools applications, and distributed with the jstools package. They provide a variety of higher¡level facilities for constructing Tk¡ and Tcl¡based applications, and provide consistency of appearance and behaviour across applications.
This document describes version 3.6/3.0 of the jstools libraries.
Compatibility
Version 3.6/3.0 of the libraries is compatible with Tk 3.6p1 and Tcl 7.3; it may work properly with other versions, but then again, it might not.
There's a bug in unpatched Tk 3.6 that causes wish(1) to die with a core dump under certain circumstances; you should apply the official patch to Tk, which is available with the Tk sources on the official Tk distribution sites.
There were focus¡related bugs in Tk 4.0b2 (the second beta release) which caused the jstools applications (and some others) to crash frequently; iflater versions of Tk probably will not suffer from this problem. I think j:dialogue in particular tends to trigger this.
Libraries
The libraries in the jstools package can be divided up by function as follows:
Utility Libraries
These libraries don't provide significant functionality that the end¡user can see, but they are used by the other libraries, or provide convenience proedures to save a few lines of code in applications.
jdebug.tcl - debugging support
jfileio.tcl - convenience procedures for reading from and writing to files
jinit.tcl - the common jstools initialisation sequence
jlistlib.tcl - undocumented, not¡ready¡for¡prime¡time tools for working with lists
jparseargs.tcl - procedures for parsing procedure and application arguments
jprefixmatch.tcl - filename expansion and abbreviation matching procedures
jprefs.tcl - general routines for loading, saving, and using preferences
(see also jprefpanel.tcl)
jtkutils.tcl - convenience procedures and user¡interface layout support
jtkversion.tcl - procedures for writing code compatible with both Tk 3 and Tk 4
Compound Widgets and Widget Wrappers
These libraries enhance the functionality of an existing Tk widget by providing a wrapper around it, or provide new widget¡like entities with new functionality.
jmetawidgets.tcl - compound widgets including a colour chooser
joptionbutton.tcl - a button that lets the user choose one of several options
jtext.tcl - wrappers around the text widget's widget command
Popup Panels
These libraries provide popup panels or dialogue boxes of various kinds. Except for the find panel provided by jfindpanel.tcl and the text display panel provided by jmore.tcl, these panels are modal.
jabout.tcl - richtext about panels
(see also jrichtext.tcl)
jalert.tcl - popup notification panels
jconfirm.tcl - a panel asking the user to confirm actions
jfindpanel.tcl - a search¡and¡replace panel for the text widget
jfs.tcl - a file¡selector panel
jmore.tcl - a text¡display panel
jprefpanel.tcl - a preference panel for setting shared jstools preferences
jprompts.tcl - procedures to ask the user for various kinds of information
Procedures for Using Tagged Text
These procedures let you and your users use, type, load, and save tagged text, which may display multiple fonts or colours or include hypertext. The jtagconvert.tcl library provides a way of converting multifont text in a text widget into other rich¡text formats.
jrichtext.tcl - procedures to embed rich text in Tk applications
jtagconvert.tcl - procedures for saving multifont text in various formats
jtexttags.tcl - extensive support for working with tagged text
(see also jtext.tcl)
Bindings Libraries
These libraries manage keyboard (and mouse) bindings for text and entry widgets. Together with the preferences libraries, they let the user choose among `basic' bindings (more complete than the standard Tk 3.6 bindings), Emacs bindings, and vi bindings. They depend on jtext.tcl, and support jtexttags.tcl if you're using it.
Currently, only jbindentry.tcl, jbindtext.tcl, jcompose.tcl, and jlatin1.tcl are documented at all, and they aren't documented very thoroughly.
jbindentry.tcl - several user¡selected styles of entry bindings
jbindtext.tcl - several user¡selected styles of text bindings
(see also jtext.tcl)
jcompose.tcl - support for the Compose key
jentryemacs.tcl - support for Emacs¡style entry bindings
jentrykeys.tcl - support for entry keyboard bindings
jentrymouse.tcl - support for entry mouse bindings
jentryvi.tcl - support for vi¡style entry bindings
jlatin1.tcl - additional support for the Compose key
jtextemacs.tcl - support for Emacs¡style text bindings
jtextkeys.tcl - support for text keyboard bindings
jtextmouse.tcl - support for text mouse bindings
jtextvi.tcl - support for vi¡style text bindings
Usage
If the jstools libraries have been installed normally at your site, you should be able to use them by making sure they're in your auto_path Tcl variable. The jstools applications also all support the convention of letting you override the default location of the jstools libraries by setting the environment variable JSTOOLS_LIB, and also let you override individual jstools libraries by copying them to your ~/.tk directory and modifying them. To accomplish all this, you should put the following code at or near the top of your wish(1) scripts:
## begin boiler_header
global VERSION
set VERSION {3.6/2.0+}
if {[info exists env(JSTOOLS_LIB)]} {
set jstools_library $env(JSTOOLS_LIB)
} else {
set jstools_library /usr/local/lib/jstools
}
# add the jstools library to the library search path:
set auto_path [concat [list $jstools_library] $auto_path]
# check for ~/.tk and prepend it to the auto_path
# if it exists. that way the user can override
# and customise the jstools libraries.
if {[file isdirectory ~/.tk]} then {
set auto_path [concat [list [glob ~/.tk]] $auto_path]
}
## end boiler_header
You should also call j:jstools_init early in your code; this reads in global (cross¡application) preferences, which are used by some of the other libraries, and automatically sets up bindings for entry and text widgets based on the user's preferences.
Credits and Copyright
Author
Jay Sekora
js@bu.edu
http://shore.net/~js/
Copyright
The jstools distribution (applications, libraries, and support files) is copyright ⌐ 1992-1995 by Jay Sekora, but may be freely copied and modified for non¡commercial purposes. (Please contact me if you want to use it for a commercial purpose, this may be OK under some circumstances.)
Thanks
Most importantly, I'd like to thank John Ousterhout <ouster@tcl.eng.sun.com>, the author of Tk and Tcl, for providing such a wonderful, robust, simple language for writing X Windows applications, and the Tcl community which has helped extend Tk and Tcl without forcing them to succumb to feature bloat.
In many places in the libraries, I've borrowed code from other people (with permission); they're mentioned in the documentation files for the individual libraries and in comments in the code itself.
Evolution
Feel free to report bugs (and feature requests) to me, <js@bu.edu>, and I will try to deal with them. Also, feel free to fix bugs or add features on your own and let me know how you did it.
Changes
The jstools libraries have changed extensively since version 3.6/2.0. The biggest change (aside from the addition of new libraries) is that the procedures have been broken down into much smaller libraries, according to function; in version 3.6/2.0 there were only four libraries, but one of them (jlibrary.tcl) was huge and monolithic. They are also now all autoloaded, rather than being explicitly sourced.
Future Directions
* I'd like to write a library for working with the contents of canvases (e.g. archiving and restoring them).
* I hope to overhaul the Preferences mechanism, which will probably involve new preferences libraries. See the jstools documentation for more about this.
* I'd like to add libraries for popup menus and/or gesture commands. (Actually, popup menu support is provided with Tk 4.0, but gesture commands would still be nice, and they could be combined - drag¡right could pop up a menu, and drag¡up could delete text, for instance.)
* I'd like to write a library for inter¡application communication, to help tie the various applications more closely together. See the jstools documentation for more about this.
