The jrichtext.tcl library is distributed as part of the jstools package. It consists of a number of procedures for working with multifont 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 4.0/4.0.
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.
The general paradigm for using rich text is as follows:
1. Specify a richtext type and destination with the j:rt command.
2. Optionally, configure visual attributes associated with text styles
3. Issue richtext 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 richtext 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
Jay Sekora
js@calumet.org
http://shore.net/~js/
Also, some of the code is modified from code in the standard Tk library from the Tk distribution.
The library is copyright © 1992-1995 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.
j:tagged_insert - insert tagged text into a text widget
rm - dummy donothing procedure
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 textintensive apps
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
j:tagged_insert w text taglist
w is the text widget to insert into
text is the text to insert
taglist is a list of tags to apply to text
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.
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 text w
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
This procedure must be used to specify the text widget you want to use before you start using richtext generation commands. (Text widget w must already exist.)
j:rt:type
Currently, this procedure just returns the string text. When the jrichtext.tcl library supports multiple richtext 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
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 {style font}...
style is a richtext style (see below)
font is the X font to use for displaying text in that style
This procedure is only valid if the current destination is a text widget. It takes one or more twoelement {style font} lists as arguments. For each style, a tag in the current destination widget is set to font; the richtext 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
This procedure is used to signal that you are done, at least for the time being, with the current richtext 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 richtext sequences will work with other formats in the future.)
j:rt:mkabbrevs
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 richtext 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}'
j:rt:style text
rm - roman (ordinary) type
it - italic or oblique type
bf - bold face type
bi - bold italic (or bold oblique) type
tt - a fixedpitch 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
text is the text to be inserted in the specified style
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
This procedure inserts a tab into the current destination (in the roman font).
j:rt:cr
This procedure inserts a line break into the current destination (in the roman font).
j:rt:par
This procedure inserts a paragraph break into the current destination (in the roman font).
* 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.
* I think this format is a deadend; I doubt I'll be doing further work on it.