Title

jrichtext.tcl

Introduction

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 4.0/4.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@calumet.org

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-1995 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

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).

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.

Future Directions

* I think this format is a dead­end; I doubt I'll be doing further work on it.