term::interact::pager(n)       Terminal control       term::interact::pager(n)



______________________________________________________________________________

NAME
       term::interact::pager - Terminal widget, paging

SYNOPSIS
       package require Tcl  8.4

       package require term::interact::pager  ?0.1?

       term::interact::pager object text ?options...?

       object interact

       object done

       object clear

       object text text

       object configure

       object configure option

       object configure option value...

       object cget option

_________________________________________________________________

DESCRIPTION
       This package provides a class for the creation of a simple paging text
       display.

CLASS API
       The package exports a single command, the class command, enabling the
       creation of pager instances. Its API is:

       term::interact::pager object text ?options...?
              This command creates a new pager object with the name object,
              initializes it, and returns the fully qualified name of the
              object command as its result.

              The argument is the text to show, possibly followed by
              configuration options and their values. The options are
              explained in the section Configuration.

OBJECT API
       The objects created by the class command provide the methods listed
       below:

       object interact
              Show the pager in the screen at the configured location and
              start interacting with it. This opens its own event loop for the
              processing of incoming characters. The method returns when the
              interaction has completed. See section Interaction for a
              description of the possible interaction.

       object done
              This method can be used by user supplied actions to terminate
              the interaction with the object.

       object clear
              This method can be used by user supplied actions to remove the
              pager from the terminal.

       object text text
              This method can be used to change the text shown by the pager.
              The pager will reset the dispay to show the first line of the
              text at the top.

       object configure

       object configure option

       object configure option value...

       object cget option
              Standard methods to retrieve and configure the options of the
              pager.

CONFIGURATION
       A pager instance recognizes the following options:

       -in chan
              Specifies the channel to read character sequences from. Defaults
              to stdin.

       -out chan
              Specifies the channel to write the pager contents to. Defaults
              to stdout.

       -column int
              Specifies the column of the terminal where the left margin of
              the pager display should appear. Defaults to 0, i.e. the left-
              most column.

       -line int
              Specifies the line of the terminal where the top margin of the
              pager display should appear. Defaults to 0, i.e. the top-most
              line.

       -height int
              Specifies the number of lines of text to show at most in the
              display. Defaults to 25.

       -actions dict
              Specifies a dictionary containing additional actions, using
              character sequences as keys. Note that these sequences cannot
              override the hardwired sequences described in section
              Interaction.

INTERACTION
       A pager object recognizes the control sequences listed below and acts
       as described. The user can supply more control sequences to act on via
       the configuration, but is not able to overide these defaults.

       Cursor Up
              The text is scrolled down a single line, making one more line
              visible at the top. The pager will not react if the first line
              of the text is already shown.

       Cursor Down
              The text is scrolled up a single line, making one more line
              visible at the bottom. The pager will not react if the last line
              of the text is already shown.

       Page Up
              The text is scrolled down a page. The pager will not react if
              the first line of the text is already shown.

       Page Down
              The text is scrolled up a page. The pager will not react if the
              last line of the text is already shown.

       Enter/Return
              The interaction with the object is terminated.

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the category term of
       the Tcllib SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].  Please also report
       any ideas for enhancements you may have for either package and/or
       documentation.

KEYWORDS
       control, pager, terminal, text display

CATEGORY
       Terminal control

COPYRIGHT
       Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>




term                                  0.1             term::interact::pager(n)
