--  file  : text.txt
--  author: jiri babor
--  email : jbabor@paradise.net.nz
--  date  : 98-11-27


This is a simple, *text mode only* library of direct screen writes.
People keep asking for them, but I noticed some of the offerings to
the list were only marginally faster than the built-in bios based
routines.

I have assembled this library from bits of code that I used for many
years, originally in Turbo Pascal. It is quite fast, because as a rule
whole sequences, not just individual characters, are poked into the
video memory. But it is by no means safe: no boundary checks are
performed. - So, please, be carefull...

The style, the vocabulary (and all the other idiosyncrasies) mirror
those used in my graphics font library.


Main features:

    Scope: text mode only. And only the first active/display page is
        considered.

    Text pointer: the system maintains its own text pointer,
        automatically updated by every write operation.

    Colors: the system mantains its own *current* color attribute,
        which is used for all screen displays.

    'On-the-fly' change of color attributes: absolute values of
        inbedded *negative* 'characters' are interpreted as new color
        attributes. Code example:

            set_foreground(YELLOW)
            set_background(BLUE)
            write("viva "&-#4F&"euphoria")

        The first word, 'viva' will be displayed in yellow on a blue
        background, but 'euphoria' will appear in bright white (#F) on
        a red (4) background.

    Prompt: screen input of a string with primitive editing.

    Line justification: the default is LEFT, but CENTRE and RIGHT can
        also be specified. Multi-line strings (with inbedded newline
        characters) are displayed correctly.


Global constants:

    ON    =1
    OFF   =0
    LEFT  =0
    CENTRE=1
    RIGHT =2


Global routines (look at individual definitions in text.e for more
details and lists of required arguments) :

    background      -- return current background color
    blink           -- toggle: blink or high intensity background colors
    cls             -- clear screen using space & current color attribute
    column          -- return current horizontal position of text pointer
    fill_screen     -- fill screen using specified char and current colors
    fill_block      -- fill block using specified char and current colors
    foreground      -- return current foreground (text) color
    justification   -- return current line justification
    justify         -- set line justification
    lengths         -- return sequence of lengths for multi-line strings
    prompt          -- prompted screen input of with primitive editing
    raw_write       -- display only ascii chars between 0 and 255, inclusive
    reset           -- reset to dos defaults (cursor, blink, 25 rows)
    row             -- return current vertical position of text pointer
    scroll_block    -- simultaneous vertical and horizontal block scroll
    scroll_screen   -- simultaneous vertical and horizontal scroll
    set_background  -- set text background color
    set_column      -- set horizontal position of text pointer
    set_foreground  -- set text foreground (text) color
    set_row         -- set vertical position of text pointer
    set_text_rows   -- attempt to reset number of rows per screen
    write           -- display text using current colors and justification
