# 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 nonmodal 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 windowmanager 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 nonnull), 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 naturallanguage 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 applicationspecific 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`.

``