{jmore.tcl

Introduction
The jmore.tcl library provides procedures for displaying (potentially long) text, such as the contents of a file or the output of a command.  (For short notices, j:alert from the jalert.tcl library may be more appropriate.)

The jmore.tcl library is distributed as part of the jstools package.

This document describes jmore.tcl version 4.0/4.0.

Usage
Accessing the Library
In order to use the jmore.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.

Credits and Copyright
Author
Jay Sekora 
js@calumet.org
http://shore.net/~js/

Thanks
The code to scroll up and down a page at a time under Tk3.6 is based on code by Paul Raines <raines@bohr.physics.upenn.edu>.

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
Procedures
j:more - display text in window
j:more:pagedown - scroll j:more window down
j:more:pageup - scroll j:more window up
j:more:print - prompt to print the content of a j:more window
j:more:save - prompt to save the content of a j:more window

j:more
Usage
	j:more [options]
Options
	-title title  (localisable, default {})
	-text text  (default {} - not really optional)
	-annotation annotation  (default {})
	-height h  (default 24)
	-width w  (default 80)
	-wrap wrap  (default `char')
	-font font  (default `default')
	-class class  (default `More')

Example
	set helpFile [open "help.doc"]
	j:more -title "Application Help" -text [read $helpFile]
	close $helpFile
	
Description
This procedure creates a new non­modal toplevel window with a text widget containing text, a scrollbar, and a set of buttons.  The toplevel will have the title title, and the window class class, which can be used for specifying X resources or window­manager behaviour.  The text widget will be h lines tall and w characters wide, and its contents will be displayed in the font font.  (If font is `default', then the X Windows default font for the j:more text widget will be used.)  Its lines will be wrapped according to wrap, which can be line, char, or none.

If annotation is specified (and is non­null), it is annotation (tags and marks) to be applied to text, in the format implemented by the jtexttags.tcl library and created by jedit's richtext mode, and it will be displayed with appropriate formatting.  (Note that you may want wrap to be word in this case.)

The text widget will be disabled, so the user can't alter its contents.  (Unfortunately, this also means that an insertion point won't be displayed, which can make navigating and using the Find panel a little confusing.)

Pressing Space, Next or PageDown, or Control-v will scroll the text down, and pressing b, Prior or PageUp, or Escape-v will scroll the text up.

Four buttons will appear at the bottom of the window, labelled `Find...', `Print', `Save', and `Done'.

Done
`Done' is the default button (i.e., Return will invoke it), and it destroys the window.

Save
`Save' lets the user save the contents of the window into a file.

Print
`Print' displays a confirmation panel, and, if the user clicks OK, prints the contents of the j:more window to the printer named by the global variable J_PREFS(printer) (or lp if J_PREFS(printer) is not set), using the lpr command.

Find...
`Find...' brings up a Find panel that lets you search for a string in the text.

The j:more procedure returns the pathname of the text widget, in case the caller wants to further configure it or manipulate its contents.

The text argument is not looked up in the natural­language database; if you want to localise text, you must do so explicitly.

j:more:pagedown
Usage
	j:more:pagedown t

This procedure scrolls the j:more text widget t down one windowful.  It's used internally by the j:more procedure and isn't likely to be otherwise useful.  It's based on code by Paul Raines <raines@bohr.physics.upenn.edu>.

j:more:pageup
Usage
	j:more:pagedown t

Description
This procedure scrolls the j:more text widget t up one windowful.  It's used internally by the j:more procedure and isn't likely to be otherwise useful.  It's based on code by Paul Raines <raines@bohr.physics.upenn.edu>.

j:more:print
Usage
	j:more:print t

Description
This procedure lets the user print the contents of a j:more panel.  It always asks for confirmation before printing, and uses the printer specified by the global variable J_PREFS(printer), or lp if J_PREFS(printer) is not specified.  It's used internally by the j:more procedure and isn't likely to be otherwise useful.

j:more:save
Usage:
	j:more:save t

Description
This procedure prompts the user for a filename and saves the contents of the j:more text widget t to the specified file.  It's used internally by the j:more procedure and isn't likely to be otherwise useful.

Bugs and Limitations
* Handling of the focus is clumsy; because I wanted the j:more window to be able to to take the focus (so you can use the Next and Prior keys and hit Return to close the window), but I didn't want it to be modal.  This should be much smoother when I'm writing for Tk 4.0.

* Using the Find Panel is clumsy under Tk 3, because the insert point isn't visible.

Future Directions
* There should be a way to specify which buttons you want on a j:more panel, and to add application­specific buttons.

* There should be independent global preferences for the size, font, and colour of j:more text widgets.

* Interaction with the find panel should be made more intuitive.

* There needs to be error checking in j:more:print and j:more:save.
} {{{display:foreground:Red {12.282 13.0}} {jdoc:xref:link {4.162 4.169 4.179 4.189 6.52 6.59 12.210 12.231 12.239 12.256 12.260 12.281 28.0 28.6 29.0 29.15 30.0 30.13 31.0 31.12 32.0 32.11 38.16 38.27 55.136 55.149 55.173 55.178 55.181 55.194}} {jdoc:xref:manpage {12.126 12.133}} {jdoc:anchor:anchorname {3.0 4.0 10.0 11.0 14.0 15.0 26.0 27.0 34.0 35.0 79.0 80.0 85.0 86.0 92.0 93.0 99.0 100.0}} {richtext:font:roman {2.0 3.0 4.0 4.4 4.13 4.162 4.169 4.179 4.189 6.4 6.13 6.52 6.59 8.24 8.33 10.0 11.21 12.20 12.29 12.102 12.111 12.126 12.133 12.214 12.221 12.243 12.248 12.260 12.281 12.282 13.0 14.0 16.0 17.0 17.14 18.0 18.21 20.0 21.0 21.92 21.123 23.0 24.0 26.0 28.6 29.0 29.15 29.25 29.31 30.0 30.13 30.23 30.29 31.0 31.12 31.48 31.54 32.0 32.11 32.46 32.52 34.0 36.8 36.9 36.16 37.0 38.15 38.37 38.39 39.0 39.13 39.22 39.24 40.0 40.25 40.34 40.36 41.0 41.12 41.21 41.23 42.0 42.11 42.20 42.22 43.0 43.13 43.23 43.27 44.0 44.13 44.23 44.30 45.0 45.15 45.25 45.29 47.0 51.0 52.0 53.0 53.85 53.89 53.160 53.165 53.188 53.193 53.294 53.295 53.311 53.312 53.377 53.381 53.397 53.404 53.447 53.453 53.521 53.525 53.540 53.544 53.546 53.550 53.555 53.559 55.3 55.13 55.97 55.101 55.136 55.149 55.173 55.178 55.181 55.189 55.275 55.279 55.286 55.290 59.9 59.14 59.16 59.20 59.24 59.32 59.37 59.46 59.87 59.88 59.90 59.95 59.99 59.105 59.110 59.118 63.0 64.0 64.36 64.42 66.0 67.0 69.0 70.0 70.94 70.100 70.152 70.168 70.173 70.175 70.179 70.195 70.219 70.222 72.0 73.0 75.4 75.10 77.4 77.8 77.93 77.97 79.0 81.18 83.27 83.33 83.46 83.47 83.97 83.103 83.190 83.221 85.0 87.18 89.0 90.0 90.27 90.33 90.46 90.47 90.95 90.101 90.188 90.218 92.0 94.15 96.0 97.0 97.53 97.59 97.171 97.187 97.192 97.194 97.198 97.214 97.262 97.268 99.0 101.14 103.0 104.0 104.77 104.83 104.150 104.156 106.0 107.0 107.56 107.62 107.122 107.126 107.131 107.136 107.150 107.156 111.0 112.0 112.63 112.69 114.83 114.89 118.38 118.50 118.55 118.66 119.0}} {richtext:font:italic {36.9 36.16 38.8 38.13 39.7 39.11 40.13 40.23 41.9 41.10 42.8 42.9 43.7 43.11 44.7 44.11 45.8 45.13 53.85 53.89 53.160 53.165 53.188 53.193 53.294 53.295 53.311 53.312 53.377 53.381 53.521 53.525 55.3 55.13 55.97 55.101 55.275 55.279 77.4 77.8 77.93 77.97 81.17 81.18 83.46 83.47 87.17 87.18 90.46 90.47 94.14 94.15 101.13 101.14}} {richtext:font:bold {4.4 4.13 4.179 4.189 6.4 6.13 6.52 6.59 8.24 8.33 12.20 12.29 12.214 12.221 55.136 55.149 59.9 59.14 59.16 59.20 59.24 59.32 59.37 59.46 59.87 59.88 59.90 59.95 59.99 59.105 59.110 59.118 64.36 64.42 107.122 107.126 107.131 107.136 107.150 107.156}} {richtext:font:bolditalic {12.243 12.248 12.260 12.281}} {richtext:font:typewriter {4.162 4.169 12.102 12.111 12.126 12.133 17.0 17.14 18.0 18.21 21.92 21.123 28.0 28.6 29.0 29.15 29.25 29.31 30.0 30.13 30.23 30.29 31.0 31.12 31.48 31.54 32.0 32.11 32.46 32.52 36.0 36.8 38.0 38.8 38.13 38.15 38.37 38.39 39.0 39.7 39.11 39.13 39.22 39.24 40.0 40.13 40.23 40.25 40.34 40.36 41.0 41.9 41.10 41.12 41.21 41.23 42.0 42.8 42.9 42.11 42.20 42.22 43.0 43.7 43.11 43.13 43.23 43.27 44.0 44.7 44.11 44.13 44.23 44.30 45.0 45.8 45.13 45.15 45.25 45.29 48.0 51.0 53.397 53.404 53.447 53.453 53.540 53.544 53.546 53.550 53.555 53.559 55.173 55.178 55.181 55.189 55.286 55.290 70.94 70.100 70.152 70.168 70.173 70.175 70.179 70.195 70.219 70.222 75.4 75.10 81.0 81.17 83.27 83.33 83.97 83.103 83.190 83.221 87.0 87.17 90.27 90.33 90.95 90.101 90.188 90.218 94.0 94.14 97.53 97.59 97.171 97.187 97.192 97.194 97.198 97.214 97.262 97.268 101.0 101.13 104.77 104.83 104.150 104.156 107.56 107.62 112.63 112.69 114.83 114.89 118.38 118.50 118.55 118.66}} {richtext:font:heading0 {1.0 2.0}} {richtext:font:heading1 {3.0 4.0 10.0 11.0 14.0 15.0 26.0 27.0 34.0 35.0 79.0 80.0 85.0 86.0 92.0 93.0 99.0 100.0 106.0 107.0 111.0 112.0}} {richtext:font:heading2 {11.0 11.21 12.282 13.0 15.0 16.0 20.0 21.0 23.0 24.0 27.0 28.0 35.0 36.0 37.0 38.0 47.0 48.0 52.0 53.0 80.0 81.0 86.0 87.0 89.0 90.0 93.0 94.0 96.0 97.0 100.0 101.0 103.0 104.0}} {richtext:font:heading3 {63.0 64.0 66.0 67.0 69.0 70.0 72.0 73.0}} {{} {12.243 12.256 14.0 19.0 22.0 24.0 25.0 28.0 34.0 38.16 38.29 39.47 40.37 47.0 53.0 54.0 56.0 63.0 64.1 64.5 64.6 66.0 67.1 67.5 67.6 69.0 70.1 70.6 70.7 72.0 73.1 73.8 73.9 76.0 78.0 89.0 90.0 92.0}} {jdoc:link:jstools.jdoc {6.52 6.59}} {jdoc:manpage:tclvars {12.126 12.133}} {jdoc:link:jslibraries.jdoc#Usage {12.239 12.256}} {jdoc:link:jslibraries.jdoc {12.260 12.281}} {jdoc:anchorname:Credits_and_Copyright {14.0 15.0}} {jdoc:anchorname:Introduction {3.0 4.0}} {jdoc:anchorname:Usage {10.0 11.0}} {jdoc:link:jslibraries.tcl {12.210 12.231}} {jdoc:anchorname:Overview {26.0 27.0}} {jdoc:link:jalert.tcl.jdoc#j:alert {4.162 4.169}} {jdoc:link:jalert.tcl.jdoc {4.179 4.189}} {jdoc:link:#j:more {28.0 28.6}} {jdoc:link:#j:more:pagedown {29.0 29.15}} {jdoc:link:#j:more:pageup {30.0 30.13}} {jdoc:link:#j:more:print {31.0 31.12}} {jdoc:link:#j:more:save {32.0 32.11}} {jdoc:anchorname:j:more {34.0 35.0}} {jdoc:anchorname:j:more:pagedown {79.0 80.0}} {jdoc:anchorname:j:more:pageup {85.0 86.0}} {jdoc:anchorname:j:more:print {92.0 93.0}} {jdoc:anchorname:j:more:save {99.0 100.0}} {jdoc:link:jtexttags.tcl.jdoc {55.136 55.149}} {jdoc:link:jedit.jdoc {55.173 55.178}} {jdoc:link:jeditmodes/richtext-mode.jdoc {55.181 55.194}} {jdoc:link:localisable.jdoc {38.16 38.27}}} {{abbrevstart 21.54} {matchend 119.0} {del_from 119.0} {richptr 13.0} {abbrevend 21.59} {insert 1.0} {emacs_mark 119.0} {anchor 1.0} {matchstart 119.0} {del_to 119.0} {current 4.127}}}