# The jstools Libraries

## Introduction

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 higherlevel facilities for constructing Tk and Tclbased applications, and provide consistency of appearance and behaviour across applications.

This document describes version 4.1/4.4 of the jstools libraries.

### Compatibility

Version 2001.02.10 of the jstools libraries is at least somewhat compatible with Tcl/Tk 8.0 and later, but has been tested most extensively with Tcl/Tk 8.1. It is entirely possible that there are things that will break under Tcl/Tk 8.0.

### Changes

See jstools changes since 4.0/4.0 for a change log (including pointers to earlier changes).

## Current status and forthcoming changes

At present, the jstools libraries are in a state of flux. Some of them are loaded using the old (pre-Tcl 8.0) auto-loading mechanism, and do not use a separate namespace. Many of them, though, have been converted to use the `package require` mechanism and use the `::jstools` namespace.

To use the libraries that have not yet been converted over to the package mechanism, you simply need to ensure that they (and the tclIndex file that lists them) are in your global Tcl `auto_path` variable, and you can call them.

To use the libraries that have been packagized, you again need to make sure that the directory containing them and the pkgIndex.tcl file that lists them is in your `auto_path` variable, and then you can use ``package require jstools`' to arrange for them to be loaded as needed.

Many of the jstools libraries also use the `jldb` package (distributed along with them), and I'm not sure they all properly `require` it. So you probably should also ``package require jldb`'.

If this sounds complicated, don't worry. Assuming you used the jinstall.tcl script to install the jstools package, you can simply use the code listed below under Usage at the top of your script to make the libraries available. The only thing you should need to change is the line
`set jstools_library /usr/lib/jstools
` replacing /usr/lib/jstools with whatever directory you told jinstall.tcl to put the libraries into.

### Forthcoming name change

I expect to change the name of this package to `aq` or `aqtools`, and its top-level namespace to `::aq`, as soon as I get all the files packagized, since I'm finding `::jstools::foo` just too long.

## 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

    if {[info exists env(JSTOOLS_LIB)]} {
      set jstools_library $env(JSTOOLS_LIB)
      set jstools_pkg [file join $env(JSTOOLS_LIB) pkg]
    } else {
      set jstools_library /usr/lib/jstools
      set jstools_pkg [file join $jstools_library pkg]
    }

    # add the jstools library to the library search path:

    set auto_path  [concat  [list $jstools_pkg]  [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

    # the import IS A BIG PROBLEM until this whole file gets wrapped in its own
    # namespace:

    catch {
      package require jldb
      # following likely to fail, because done by other libraries too
      namespace import ::jldb::shortcuts::*
    }

    catch {
      package require jstools
      namespace eval ::jstools { }                  ;# so namespace is defined
    }

    ######################################################################

You should also call `::jstools::jstools_init` early in your code; this reads in global (crossapplication) 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.

## Libraries

The libraries in the jstools package can be divided up by function as follows:

### Natural Language Database Support

This library lets your application look up strings it wants to display and present them in the user's preferred language. It's designed to be independent from the other jstools libraries, so it can be used alone. It's also fairly small.

jldb.tcl - localisation support for naturallanguage strings

### Utility Libraries

These libraries don't provide significant functionality that the enduser 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
jparseargs.tcl - procedures for parsing procedure and application arguments
jprefixmatch.tcl - filename expansion and abbreviation matching procedures
jhistory.tcl - procedures to use persistent (ondisk) history lists
jprefs.tcl - general routines for loading, saving, and using preferences
(see also jprefpanel.tcl)
jstools.tcl - miscellaneous procedures shared by jstools applications
[documentation missing]
jtkutils.tcl - convenience procedures and userinterface layout support
jtclutils.tcl - convenience procedures that don't require Tk
jtkversion.tcl - procedures for writing code compatible with both Tk 3 and Tk 4
jviewers.tcl - show manual pages or URLs with the user's preferred tools

### Compound Widgets and Widget Wrappers

These libraries enhance the functionality of an existing Tk widget by providing a wrapper around it, or provide new widgetlike 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
jtextcmds.tcl - uservisible command procedures for working with text

### 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 searchandreplace panel for the text widget
jfs.tcl - a fileselector panel
jmore.tcl - a textdisplay 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 Managing UserVisible Commands

The procedures in jcommand.tcl make managing uservisible commands (i.e., commands the user would give to your application, e.g. by clicking on a button or choosing a menu entry) easier. Those in jmenu.tcl let you construct menus of those commands, as well as other kinds of menus, without a lot of typing.

jcommand.tcl - procedures to manage user-invokable commands
jmenu.tcl - procedures to manage menus
(see also jprompts.tcl, jinit.tcl, and jtextcmds.tcl)

### 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 richtext 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 and jtextcmds.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. However, the others are not intended to be called directly; they're called by the libraries mentioned above.

jbindentry.tcl - several userselected styles of entry bindings
jbindtext.tcl - several userselected styles of text bindings
(see also jtext.tcl)
jcompose.tcl - support for the Compose key
jentrybasic.tcl - support for minimalist bindings
jentryedt.tcl - rudimentary support for EDT bindings
jentryemacs.tcl - support for Emacsstyle entry bindings
jentrykeys.tcl - general support for entry keyboard bindings
jentrymouse.tcl - support for entry mouse bindings
jentryvi.tcl - support for vistyle entry bindings
jlatin1.tcl - additional support for the Compose key
jtextbasic.tcl - support for minimalist text bindings
jtextedt.tcl - rudimentary support for EDT bindings
jtextemacs.tcl - support for Emacsstyle text bindings
jtextkeys.tcl - support for text keyboard bindings
jtextmouse.tcl - support for text mouse bindings
jtextvi.tcl - support for vistyle text bindings

## Credits and Copyright

### Author

Jay Sekora
`js@aq.org`
`http://www.aq.org/~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 noncommercial 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.

## Future Directions

Feel free to report bugs (and feature requests) to me, `<js@aq.org>`, 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.

- I'd like to write a library for working with the contents of canvases (e.g. archiving and restoring them).
- I'd like to write a library for interapplication communication, to help tie the various applications more closely together. See the jstools documentation for more about this.

`

`