{jabout.tcl

Introduction
The jabout.tcl library is distributed as part of the jstools package.  It consists of one main procedure and a number of subsidiary procedures used by the jstools applications.  It contains procedures to manage an `about' panel, with information about your application.  (Actually, it can be used as a general­purpose richtext display mechanism.)

This document describes jabout.tcl version 1998.11.04.

Usage
Accessing the Library
In order to use the jabout.tcl library, it (and any other libraries it depends on) must be in your Tcl auto_path, described in tclvars(n).  Information about how to arrange that, and other conventions common to the jstools libraries, is in the Usage section of The jstools Libraries.

Specifying Text
The Tcl­syntax format for specifying richtext is defined by the jrichtext.tcl library, which jabout.tcl uses.

Credits and Copyright
Author
Jay Sekora 
js@aq.org
http://www.aq.org/~js/

Copyright
The library is copyright © 1992-1998 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

Overview
Procedures
j:about - create an about box
j:about:button - add a button to an about box
j:about_jay - return rich­text describing me
j:about_tktcl - return rich­text describing Tk and Tcl

j:about
Usage
	j:about name [options] richtext
Options
	-title title  (localisable, default About)
Arguments
	name is the name of the about­box window
	richtext is the rich­text content of the about box
	title is the window­manager title for the about box
Example
	j:about .telephones -title "About Telephones" {
	  j:rt:hl "Telephones"
	  j:rt:cr
	  j:rt:rm "Telephones are extremely useful, "
	  j:rt:rm "but also sometimes extremely "
	  j:rt:it "annoying"
	  j:rt:rm " devices for communicating "
	  j:rt:rm "over long distances."
	}

Description
This procedure creates and displays a new about panel containing richtext.  The about panel's toplevel widget will be named name.  (It's window­manager title will be title, if specified.)  The about box will have a button labelled `OK' in the lower right which will destroy the panel.  (The OK button is the default button, so the user can invoke it by pressing Return.)

Note that richtext is not looked up in the database; if you want it to be localisable you'll need to call j:ldb yourself.

j:about:button
Usage
	j:about:button aboutbox label richtext
Arguments
	aboutbox is the name of the about panel to add the button to
	label is the text to display on the button (localisable)
	richtext is the richtext the button should display in the about box
Example
	j:about:button .about "Copyright" {
	  j:rt:rm "Copyright \251 1776 by George Washington"
	  j:rt:cr
	  j:rt:rm "All Rights Reserved."
	}

Description
This procedure is used to add buttons to an existing about panel, so your users can choose among several topics for the about panel.  If you only want your about panel to display one piece of text, you don't need to call this procedure, but if you have several topics - for instance, general information about your program, a copyright notice, and a list of contributing authors - you can add buttons to the about panel for each topic.

The button will be packed to the left of the `OK' button (or any previously­added buttons), and will be labelled with label.  When invoked, it will display richtext in the about panel, replacing any text that was displayed before.  (For this reason, if you add buttons to an about panel, one of the buttons should typically redisplay the initial contents of the panel.

Note that richtext is not looked up in the database; if you want it to be localisable you'll need to call j:ldb yourself.

j:about_jay
Usage
	j:about_jay

Description
This procedure returns richtext (as defined by the jrichtext.tcl library) describing me.  It's in the library as a convenience, so I can call it from all the jstools applications.

The text will be looked up in the natural­language string database as described in jldb.tcl with the key about:about_jay.

j:about_tktcl
Usage
	j:about_tktcl
Example
	j:about:button .about "Tk and Tcl" [j:about_tktcl]

Description
This procedure returns richtext describing Tk and Tcl.  In English, the text is currently:

    Tk and Tcl
    
    This application is written in wish, a scripting shell for X Windows
    applications based on the Tk toolkit, which in turn is based on
    the Tcl language and scripting library, all amazingly useful tools
    by John Ousterhout of Sun Microsystems.
    
    The Internet newsgroup comp.lang.tcl is devoted to Tcl and related
    tools, and a Tk/Tcl FAQ (`Frequently Asked Questions') is periodically
    posted.  The latest distributions are available on the FTP site
    ftp.smli.com, and ftp.aud.alcatel.com has the FAQ and 
    user­contributed scripts.

If the user has selected a different language, the text will be looked up in the natural­language string database as described in jldb.tcl with the key about:about_tktcl.

A longer example
This is a simplified version of the code that generates the about panel for the jedit application:

	set about_editor {
	  j:rt:hl "jedit"
	  j:rt:cr
	  j:rt:rm "by Jay Sekora, "
	  j:rt:tt "js@aq.org"
	  j:rt:par
	  j:rt:rm "A customisable text editor for X Windows."
	  j:rt:cr
	  j:rt:rm "Version 1998.11.04."
	}
	j:about .about $about_editor
	j:about:button .about {About jedit} $about_editor
	j:about:button .about {About The Author} [j:about_jay]
	j:about:button .about {About Tk and Tcl} [j:about_tktcl]

Bugs and Limitations
· Having to add a button for each topic is clumsy.  It would be better if the argument to j:about were a list of topics and corresponding richtext, and there were a one­of­many selector of some kind to view different topics.

} {{{list:level:1 {129.0 130.0}} {display:foreground:Red {10.283 11.0}} {jdoc:anchor:anchorname {3.0 4.0 8.0 9.0 15.0 16.0 24.0 25.0 31.0 32.0 56.0 57.0 77.0 78.0 86.0 87.0 110.0 111.0}} {sel {121.20 121.30}} {jdoc:xref:link {4.53 4.60 4.155 4.162 10.211 10.232 10.240 10.257 10.261 10.282 13.64 13.77 26.0 26.7 27.0 27.14 28.0 28.11 29.0 29.13 35.16 35.27 54.106 54.111 61.45 61.56 75.74 75.85 75.106 75.111 82.51 82.64 82.158 82.165 84.83 84.91 108.130 108.138}} {jdoc:xref:manpage {10.127 10.134}} {richtext:font:roman {2.0 3.0 4.0 4.4 4.14 4.53 4.60 4.155 4.162 6.24 6.34 8.0 9.21 10.20 10.30 10.103 10.112 10.127 10.134 10.215 10.222 10.244 10.249 10.261 10.282 10.283 11.0 12.0 12.15 13.64 13.77 13.93 13.103 15.0 17.0 18.0 18.9 19.0 19.22 21.0 22.0 24.0 26.7 27.0 27.14 28.0 28.11 29.0 29.13 31.0 33.14 33.15 33.22 33.23 33.32 34.0 35.15 35.37 35.42 36.0 37.5 38.0 38.9 39.0 39.6 40.0 52.0 52.65 52.73 52.124 52.128 52.166 52.171 52.362 52.368 54.10 54.18 54.22 54.25 54.106 54.111 56.0 58.39 59.0 60.0 60.1 60.9 61.1 61.6 62.1 62.9 63.0 70.11 73.118 73.123 73.156 73.164 75.10 75.18 75.22 75.25 75.106 75.111 77.0 79.12 80.0 82.0 82.51 82.64 82.158 82.165 84.26 84.27 84.83 84.91 84.105 84.120 86.0 88.14 89.0 91.0 92.0 93.0 95.0 95.14 96.0 96.4 97.0 97.4 97.35 97.39 98.0 98.4 99.0 99.4 100.0 100.4 101.0 101.4 102.0 102.4 102.27 102.40 103.0 103.4 104.0 104.4 105.0 105.16 105.22 105.41 106.0 106.4 108.73 108.74 108.130 108.138 108.152 108.169 110.0 111.0 111.80 111.85 113.0 127.0 128.0 129.0 129.90 129.97 130.0}} {richtext:font:italic {33.9 33.13 33.15 33.22 33.24 33.32 35.8 35.13 37.1 37.5 38.1 38.9 39.1 39.6 52.65 52.73 52.124 52.128 52.166 52.171 54.10 54.18 54.22 54.25 58.16 58.24 58.25 58.30 58.31 58.39 60.1 60.9 61.1 61.6 62.1 62.9 73.118 73.123 73.156 73.164 75.10 75.18 75.22 75.25 80.0 81.0}} {richtext:font:bold {4.4 4.14 4.53 4.60 4.155 4.162 6.24 6.34 10.20 10.30 10.215 10.222 13.64 13.77 13.93 13.103 50.0 51.0 52.362 52.368 82.51 82.64 82.158 82.165 84.26 84.27 84.83 84.91 108.73 108.74 108.130 108.138}} {richtext:font:bolditalic {10.244 10.249 10.261 10.282 95.4 95.14}} {richtext:font:typewriter {10.103 10.112 10.127 10.134 18.0 18.9 19.0 19.22 26.0 26.7 27.0 27.14 28.0 28.11 29.0 29.13 33.0 33.9 33.13 33.14 33.23 33.24 35.0 35.8 35.13 35.15 35.37 35.42 37.0 37.1 38.0 38.1 39.0 39.1 41.0 50.0 54.106 54.111 58.0 58.16 58.24 58.25 58.30 58.31 64.0 69.0 75.106 75.111 79.0 79.12 84.105 84.120 88.0 88.14 90.0 91.0 95.0 95.4 96.0 96.4 97.0 97.4 97.35 97.39 98.0 98.4 99.0 99.4 100.0 100.4 101.0 101.4 102.0 102.4 102.27 102.40 103.0 103.4 104.0 104.4 105.0 105.16 105.22 105.41 106.0 106.4 108.152 108.169 111.80 111.85 113.0 127.0 129.90 129.97}} {richtext:font:heading0 {1.0 2.0}} {richtext:font:heading1 {3.0 4.0 8.0 9.0 15.0 16.0 24.0 25.0 31.0 32.0 56.0 57.0 77.0 78.0 86.0 87.0 110.0 111.0 128.0 129.0}} {richtext:font:heading2 {9.0 9.21 10.283 11.0 12.0 12.15 16.0 17.0 21.0 22.0 25.0 26.0 32.0 33.0 34.0 35.0 36.0 37.0 40.0 41.0 51.0 52.0 57.0 58.0 59.0 60.0 63.0 64.0 69.0 70.11 78.0 79.0 81.0 82.0 87.0 88.0 89.0 90.0 92.0 93.0}} {{} {10.244 10.257 14.0 22.0 23.0 35.16 35.29 53.0 55.0 61.43 61.57 73.368 76.0 83.0 85.0 93.56 93.69 105.8 105.16 105.54 105.58 106.8 106.9 107.0 109.0 121.20 121.30 127.0}} {jdoc:link:jstools.jdoc {4.53 4.60 4.155 4.162 82.158 82.165}} {jdoc:manpage:tclvars {10.127 10.134}} {jdoc:link:jslibraries.jdoc#Usage {10.240 10.257}} {jdoc:link:jslibraries.jdoc {10.261 10.282}} {jdoc:anchorname:Credits_and_Copyright {15.0 16.0}} {jdoc:anchorname:Introduction {3.0 4.0}} {jdoc:anchorname:Usage {8.0 9.0}} {jdoc:link:jrichtext.tcl.jdoc {13.64 13.77 82.51 82.64}} {jdoc:topic:jstools {4.53 4.60 4.155 4.162 82.158 82.165}} {jdoc:topic:jrichtext.tcl {82.51 82.64}} {jdoc:section:j:about {26.0 26.7}} {jdoc:section:j:about:button {27.0 27.14}} {jdoc:section:j:about_jay {28.0 28.11}} {jdoc:section:j:about_tktcl {29.0 29.13}} {jdoc:anchorname:j:about {31.0 32.0}} {jdoc:anchorname:j:about:button {56.0 57.0}} {jdoc:anchorname:j:about_jay {77.0 78.0}} {jdoc:anchorname:j:about_tktcl {86.0 87.0}} {jdoc:link:#j:about {26.0 26.7}} {jdoc:link:#j:about:button {27.0 27.14}} {jdoc:link:#j:about_jay {28.0 28.11}} {jdoc:link:#j:about_tktcl {29.0 29.13}} {jdoc:link:jslibraries.tcl {10.211 10.232}} {jdoc:anchorname:Overview {24.0 25.0}} {jdoc:anchorname:A_longer_example {110.0 111.0}} {jdoc:link:localisable.jdoc {35.16 35.27 61.45 61.56 75.74 75.85}} {jdoc:link:jldb.tcl.jdoc#j:ldb {54.106 54.111 75.106 75.111}} {jdoc:link:jldb.tcl.jdoc {84.83 84.91 108.130 108.138}} {list:1:ul {129.0 130.0}} {special:list_item:1 {129.0 129.1}}} {{abbrevstart 6.53} {del_from 130.0} {emacs_mark 130.0} {anchor 129.25} {matchstart 130.0} {insert_save 129.3} {richptr 55.0} {insert 121.30} {del_to 4.344} {abbrevend 6.54} {current 112.0} {matchend 130.0}}} {}