


term::interact::pager(n) Terminal controlterm::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 configu-
              ration 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



term                           0.1                              1





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


              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.




term                           0.1                              2





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


       -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  Interac-
              tion.


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 vis-
              ible 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://source-
       forge.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                              3


