The jrichtext.tcl library is distributed as part of the jstools package. It consists of a number of procedures for working with multi¡font text. At present, it only supports putting rich text in text widgets; I hope to extend it in the future to generate rich text in other formats, such as PostScript or TeX. (Once you have rich text in a text widget, though, you can use the jtagconvert.tcl library to convert it to other formats.)
This document describes jrichtext.tcl version 3.6/3.0.
Usage
Accessing the Library
In order to use the jrichtext.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.
Using Rich Text
The general paradigm for using rich text is as follows:
1. Specify a rich¡text type and destination with the j:rt command.
2. Optionally, configure visual attributes associated with text styles
3. Issue rich¡text generation commands, which can also be thought of as a text format
4. Issue j:rt:done to perform any necessary cleanup
In theory, a type is any kind of object, like a text widget, a file, or a kind of printer or terminal, which can display or store rich text. Currently, only type text (a Tk text widget) is supported. A destination is a particular instance of a type - currently a particular text widget, in theory also a particular file or printer.
It's often convenient to group rich¡text generation commands together so they can be treated as a unit, or passed as arguments. (Some of the procedures in the jabout.tcl library do this.)
Here's a short example of using rich text:
set richtext_example {
j:rt:rm {This is a }
j:rt:it {very}
j:rt:rm { simple example of using the }
j:rt:bf {jrichtext.tcl}
j:rt:rm { library.}
}
toplevel .foo
text .foo.t
pack .foo.t -in .foo
j:rt text .foo.t
eval $richtext_example
j:rt:done
Credits and Copyright
Author
Jay Sekora
js@bu.edu
http://shore.net/~js/
Also, some of the code is modified from code in the standard Tk library from the Tk distribution.
Copyright
The library is copyright ⌐ 1992-1994 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.)
Overview
General Convenience Procedures
j:tagged_insert - insert tagged text into a text widget
rm - dummy do¡nothing procedure
Rich¡Text Management Procedures
These procedures deal with possible destinations - objects (currently only Tk text widgets) that you want to put rich text into. The most important are j:rt, which identifies a destination, and j:rt:done, which you use when you've finished writing the rich text.
j:rt text - prepare to write rich text to a text widget
j:rt:type - return type of current rich text destination (text, TeX)
j:rt:destination - return current rich text destination (widget, file)
j:rt:textfonts - set fonts for text widget
j:rt:done - finish writing rich text (clear vars, close files)
j:rt:mkabbrevs - make shorter convenience procs, for text¡intensive apps
Procedures for Generating Rich Text
These procedures all put rich text into the current destination. It is an error for there not to be a valid destination - you must already have issued j:rt to set a destination.
j:rt:rm - write rich text (roman)
j:rt:it - write rich text (italic)
j:rt:bf - write rich text (bold face)
j:rt:bi - write rich text (bold italic)
j:rt:tt - write rich text (typewriter - monospaced)
j:rt:h0 - write rich text (level 0 heading, appropriate for document titles)
j:rt:h1 - write rich text (level 1 heading)
j:rt:h2 - write rich text (level 2 heading)
j:rt:h3 - write rich text (level 3 heading)
j:rt:h4 - write rich text (level 4 heading)
j:rt:h5 - write rich text (level 5 heading)
j:rt:hl - an obsolete alias for j:rt:h1
j:rt:tab - tab in rich text
j:rt:cr - line break in rich text
j:rt:par - paragraph break in rich text
See Also
jtexttags.tcl
jtagconvert.tcl
j:tagged_insert
Usage
j:tagged_insert w text taglist
Arguments
w is the text widget to insert into
text is the text to insert
taglist is a list of tags to apply to text
Description
This procedure is lifted from the mkStyles.tcl demo, included in the Tk distribution. There it was called insertWithTags; I've changed the name for consistency.
This procedure inserts text into w at w's insert point. It then applies all the tags in taglist, which must be a valid Tcl list, to text, removing any other tags that text might have inherited from it's left neighbor. If taglist is empty, text will end up without any tags.
rm
Description
This procedure doesn't do anything at all. It's defined in case you try to use the rm abbreviation for j:rt:rm without first calling j:rt:mkabbrevs. Depending on your Tcl configuration, the Tcl unknown(n) procedure might then try to execute the Unix rm(1) command, with potentially dangerous results.
j:rt
Usage
j:rt text w
Arguments
text tells j:rt that you want to work with a text widget
w is the text widget you want to start displaying rich text in
Description
This procedure must be used to specify the text widget you want to use before you start using rich¡text generation commands. (Text widget w must already exist.)
j:rt:type
Usage
j:rt:type
Description
Currently, this procedure just returns the string text. When the jrichtext.tcl library supports multiple rich¡text destination types, this command will return a string specifying what the type of the current destination is.
If there is no current destination, this procedure returns {}.
j:rt:destination
Usage
j:rt:destination
Description
If the current destination is a text widget (currently the only possible kind of destination), this procedure will return its pathname.
If there is no current destination, this procedure returns {}.
j:rt:textfonts
Usage
j:rt:textfonts {style font}...
Argument components
style is a rich¡text style (see below)
font is the X font to use for displaying text in that style
Description
This procedure is only valid if the current destination is a text widget. It takes one or more two¡element {style font} lists as arguments. For each style, a tag in the current destination widget is set to font; the rich¡text generation procedures use those tags. (The actual tags are named richtext:font:style.)
The style argument must be one of roman, italic, bold, bolditalic, typewriter, or heading0 through heading5, corresponding to j:rt:rm, j:rt:it, j:rt:bf, j:rt:bi, j:rt:tt, or j:rt:h0 through j:rt:h5. (These tags are used by the jtexttags.tcl library, on top of which the procedures in jrichtext.tcl are built.)
j:rt:done
Usage
j:rt:done
Description
This procedure is used to signal that you are done, at least for the time being, with the current rich¡text destination. It does any necessary cleanup, such as closing open files. (Actually, with text widgets, this isn't strictly necessary, but I suggest that you use it so that your rich¡text sequences will work with other formats in the future.)
j:rt:mkabbrevs
Usage
j:rt:mkabbrevs
Description
This procedure is useful when you want to allow your users to type stretches of rich text, or when it's important for rich text to be concise. It simply makes aliases for the rich¡text generation procedures without the `j:rt:' prefix. If you've called j:rt:mkabbrevs, you can then issue, for instance, `rm {Roman nose}' instead of `j:rt:rm {Roman nose}'
Procedures for Inserting Rich Text
Usage
j:rt:style text
Styles
rm - roman (ordinary) type
it - italic or oblique type
bf - bold face type
bi - bold italic (or bold oblique) type
tt - a fixed¡pitch font, useful for code examples
h0 - level 0 heading, appropriate for document titles
h1 - level 1 heading, appropriate for main section headings
h2 - level 2 heading
h3 - level 3 heading
h4 - level 4 heading
h5 - level 5 heading
hl - an obsolete alias for h1
Argument
text is the text to be inserted in the specified style
Description
These procedures insert the text text in the current destination widget in the given style. (Strictly speaking, they insert text tagged with specific tags, and you can configure the correspondence of fonts to styles arbitrarily with j:rt:textfonts.)
j:rt:tab
Usage
j:rt:tab
Description
This procedure inserts a tab into the current destination (in the roman font).
j:rt:cr
Usage
j:rt:cr
Description
This procedure inserts a line break into the current destination (in the roman font).
j:rt:par
Usage
j:rt:par
Description
This procedure inserts a paragraph break into the current destination (in the roman font).
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.
Bugs and Misfeatures
* j:rt:textfonts probably really belongs in jtexttags.tcl, unless I generalise it to be useful for other kinds of destination than text widgets.
* Since I'm imposing so many constraints based on generalising to other kinds of destinations than text widgets, I really ought to support some.
* It would be nice to have some way of handling tags other than font tags, so that (say) hypertext or colours could be expressed with the library. Currently the only way to do that is with the format supported by j:tag:archive_text_widget and j:tag:restore_text_widget in jtexttags.tcl, which isn't really suited for the kinds of uses the jrichtext.tcl library supports.
* In general, jrichtext.tcl and jtexttags.tcl seem to be working at cross purposes to some extent; I wish they were better integrated. (And when I support multiple types of `destination', jrichtext.tcl and jtagconvert.tcl will be working at cross purposes. :-)
Changes Since Version 3.6/2.0
* These procedures have been rewritten slightly to use the new jtexttags.tcl library procedures.
* The styles for j:rt:textfonts have changed to be compatible with the tags used by jtexttags.tcl. Unfortunately that means they're no longer based on the actual commands used to insert rich text.
Changes from Earlier Versions
* These procedures used to be in a file called jlibrary.tcl. Starting with version 3.6/2.0, they're in their own independent library.
Future Directions
* Obviously, I'd like to support other types of `destination' besides text widgets.
* If I can think of a good way to generalise this library to handle other kinds of tags, without sacrificing ease of use, I will.
