NAME

       TextDisplay - unstructured text display

SYNOPSIS

       #include <InterViews/textdisplay.h>

DESCRIPTION

       A  TextDisplay manages and displays an array of lines of text.  Operations are provided to
       insert and delete lines, to insert and delete text  within  a  line,  and  to  scroll  the
       display.   TextDisplays  are  typically  used  to  implement interactors that require non-
       trivial display of unstructured text.

       The array is addressed by a line number and an index into the line.  Text can be  inserted
       or deleted at arbitrary positions.  By default, the first character in line number zero is
       positioned with its top left corner at the  top  left  corner  of  the  TextDisplay.   The
       display  is  automatically  updated following modifications to the text or when scrolling.
       Each character in the array has an associated text  style.   Operations  are  provided  to
       apply,  add,  or  remove font styles to a range of the text.  TextDisplay can be used with
       both  constant-width  and  proportionally-spaced  fonts  and  with   arbitrary   geometric
       transformations.

PUBLIC OPERATIONS

       TextDisplay()
       ~TextDisplay(boolean autosized = false)
              Create  or  destroy  a  TextDisplay.   If  autosized  is true, the TextDisplay will
              automatically grow its size as text is added.  The default  is  to  keep  the  size
              constant.

       void LineHeight(Coord lineheight)
       void TabWidth(Coord tabwidth)
              Lines  of  text  will  be  positioned  with baselines separated by lineheight.  Tab
              characters in the text will cause the  following  character  to  be  positioned  an
              integral multiple of tabwidth from the beginning of the line.

       void Resize(Coord xmin, Coord ymin, Coord xmax, Coord ymax)
       void Bounds(Coord& xmin, Coord& ymin, Coord& xmax, Coord& ymax)
              Specify  or query the size of the display.  Only lines of text that fall completely
              inside the specified region will be displayed.  TextDisplay will not  draw  on  any
              part  of  the canvas outside the specified bounds.  Conversely, TextDisplay is free
              to draw on any part of the canvas within the specified bounds.

       void Draw(Painter*, Canvas*)
              Specify the painter and canvas to use for drawing operations; the painter specifies
              the  font,  colors,  and  geometric  transformation.   Draw should be called before
              performing any operation on the  TextDisplay  which  produces  output  or  requires
              graphical  information,  or  when there is a possibility that the painter or canvas
              has changed since the function was last called.

       void Redraw(Coord left, Coord bottom, Coord right, Coord top)
              Redraw a specified region of the display.

       void Scroll(int line, Coord x, Coord y)
              Scroll the display so that line line is positioned with its  upper-left  corner  at
              (x,  y).   There are no restrictions on the arguments: it is possible to scroll the
              display so that no lines are visible.

       void InsertLinesAfter(int line, int count)
       void InsertLinesBefore(int line, int count)
       void DeleteLinesAfter(int line, int count)
       void DeleteLinesBefore(int line, int count)
              Insert or delete whole lines of text.  Line line is not affected by the  operation.
              Other  lines will move up or down to accommodate the changes.  Newly inserted lines
              are blank.  The specified line need not refer to an existing line.

       void InsertText(int line, int index, const char*, int count)
       void DeleteText(int line, int index, int count)
       void ReplaceText(int line, const char*, int count)
              Modify the text within  line  line.   InsertText  and  DeleteText  will  cause  the
              following  characters  on the line to move to accommodate the changes.  ReplaceText
              replaces the entire text of the line.  If the specified line is non-existent, a new
              line will be created.

       void Style(int line1, int index1, int line2, int index2, int style)
       void AddStyle(int line1, int index1, int line2, int index2, int style)
       void RemoveStyle(int line1, int index1, int line2, int index2, int style)
              Modify  the styling of a range of text. Style replaces any existing style; AddStyle
              adds style style in addition to any  existing  styles;  RemoveStyle  removes  style
              style  without  affecting  other  existing  styles.   Styles  are  specified as any
              combination of the constants Plain, Boldface, Underlined, and Reversed.

       void CaretStyle(int style)
       void Caret(int line, int index)
              Control the shape and position of  a  caret.   Valid  caret  styles  are  currently
              NoCaret,   BarCaret,   UnderscoreCaret  and  OutlineCaret.   TextDisplay  does  not
              automatically adjust the position of the caret following insertions and deletions.

       int LineNumber(Coord y)
       int LineIndex(int line, Coord x)
              Map x and y display coordinates into line and index text  coordinates.   LineNumber
              returns  the  number  of  the line that contains the specified vertical position y.
              LineIndex returns the index into line line that best corresponds to  the  specified
              horizontal position x.

       Coord Width()
       Coord Height()
              Return  the width or the height of the text currently displayed by the TextDisplay.
              Width returns the width of the longest line in the  display.   Height  returns  the
              distance  from  the  top  of the topmost line to the bottom of the bottommost line.
              Note that these dimensions do  not  necessarily  correspond  to  the  TextDisplay's
              bounds as returned by Bounds.

       Coord Base(int line)
       Coord Top(int line)
       Coord Left(int line, int index)
       Coord Right(int line, int index)
              Map  line  and index text coordinates into x and y display coordinates.  The return
              values define a bounding box for the character specified by line and index.

SEE ALSO

       Painter(2I), Canvas(2I)