
        --------------------------------------------------------------


                             CWRITE.LIBRARY v1.31

                        Programmed by   :  Per Hansen
                        Original code by:  Lars Dam & Per Hansen

             (C)opyright 1992 by Tribune Channel Software Team.
                            All rights reserved.

       --------------------------------------------------------------

                               Cwrite.library

A  library that makes it possible to make terminal programs without having to
bother   about   opening  console.device,  IOrequests  etc.   for  outputting
characters to the screen.
It  can write text to a more specific window, and is capable of handling ANSI
escape  sequences,  although this sequence might be interruptet in the middle
of it, and resumed later on..! - Now, THIS is something!
It has faster output than the console.device, even if console.device has been
opened  on  a  2-bitplane  screen and cwrite.library uses a screen with THREE
bitplanes!
It  has  lightning  fast scrolling routines, which only is slowed down if you
use  the  library  on  a screen with 4 bitplanes..  - Much faster ANSI escape
sequence handling, than anything else seen on the Amiga!!
A  little  note:  Actually Lars Dam hasn't seen the source codes since a very
long time ago (don't even remember when), and he would possibly not recognize
it,  but  he  was  the  one  that  made  it possible to make this library, so
therefore i have put his name in top of this file.

       --------------------------------------------------------------

                                INTRODUCTION

The cwrite.library is released to the public as FREEWARE.
It  may not be included in any commercial package without the authors written
permission,  and  if  it goes into any PD library anywhere over the world, no
charge, except from reasonable media costs, may be taken!

Cwrite.library  has  made it possible to make very fast terminal programs, as
it supports most of the standard VT100 escape sequences (also known as ANSI),
including the ones the standard console.device doesn't support.
The only ones not supported by this library, is the 'feedback' stuff, used
on some bulletin boards, that reports the terminal equipment status.

It  is  capable  of  showing  characters  that  are not normally visible on a
standard  console.device  opened  window.  (I.e.  Danish, Norwegian, Swedish,
German, etc. characters.)

       --------------------------------------------------------------

                                  CONTENTS

This archive, "CwrLib31.LHA" contains the following sixteen files:

 Filename            Bytes     Description
------------------- ------- -----------------------------------------------
 Changes_V131.txt     1055  -- Changes from prior release.
 cwrite.doc           9034  -- The Autodocs for cwrite.library
 cwrite.library       4992  -- The cwrite.library. Put it in your LIBS: drawer
 CWrite.fd             261  -- FD file for the library.
 cwritelib.h          2473  -- C-include file for the library routines.
 cwritelib.i          2404  -- ASM-include file.
 cwritelibbase.h       807  -- C-include file for the library base definition
 cwritelibbase.i      1305  -- ASM-include file.
 README              12652  -- The documentation file (you're reading it!).
 Testlib              2972  -- Program, showing how to program the library.
 Testlib.c            3808  -- Sources for the program.
 EAGLE.ANS            3166  -- Example file containing ANSI escape sequences.
 SAGA.ANS            10598  --  do.
 ANSITEST.ANS         2415  --  do.

 CWTerm/CWTerm        7536  -- Sample communications program using cwrite.
 CWTerm/CWTerm.c     10625  -- Sources for the above..
 CWTerm/CWTermwin.c   3939  --  do.
 CWTerm/comserial.c   5904  --  do.

*PLEASE* don't remove ANY of these files from the archive if you intend to
redistribute this file to other BBS's. I have spent a lot of time creating
all of these files, and I would like them to be kept together in the
*original* archive that I originally distributed! Thanks!

The  library  itself, however, may be distributed together with programs that
use  this  library.   - I would, however, prefere that the cwrite.doc and the
include files always follows the library.

       --------------------------------------------------------------

                           INSTALLATION AND USAGE

Before using the library routines, you have to move the library to your
LIBS: drawer on your system disk.

Within  this  package,  is  a  test  program with sources, that shows how the
library may be programmed..

Any  font  size  should  work together with this library, although fonts with
proportional  sizes  will not show off in the right way, and should therefore
be avoided when using this library.

Please read the 'cwrite.doc' for further information on the available library
commands for your applications/programs.

       --------------------------------------------------------------

                            VT100 MODE SUPPORTED

In  order  to  be  able to use cwrite.library in more communication programs,
many VT100 escape sequences are supported by the library.

An escape sequence is a sequence of one or more ASCII graphic characters
preceded by the character ESC($1B). For example,

ESCc

is an escape sequence that causes all setup parameters to be replaced with
the default startup values, and emulates the VT100 hard terminal reset(RIS).
Escape sequences use only 7-bit characters, and can be used in 7-bit or 8-bit
environments.

The following escape sequences are supported by cwrite.library:

    ESC c       Emulates hard terminal reset.
                Resets all parameters (except cursortype) to default values.

    ESC D       Index (IND). See under control codes below.

    ESC E       Next line (NEL). See under control codes below.

    ESC M       Reverse index (RI). See under control codes below.

    ESC [       Control sequence introducer (CSI).


A control sequence is a sequence of one or more ASCII graphic characters
preceded by ESC[ or CSI($9B).
So you can express all control sequences as escape sequences whose second
character code is [. For example, the following sequence cause the current
line of text to be erased.

ESC[2K

The CSI character has been omitted to make room for more compatibility with
foreign character sets like the danish, norwegian, swedish etc.
CSI, however, can also only be used in an 8-bit environment.

The following VT100 control sequences are supported by cwrite.library:

    ESC[xA      Cursor up by x lines in the same column. Default 1.

    ESC[xB      Cursor down x lines in the same column. Default 1.

    ESC[xC      Cursor right by x columns. Default 1.

    ESC[xD      Cursor left by x columns. Default 1.

    ESC[x;yH    Moves cursor to line x column y. One or both of the
                arguments can be omitted, e.g. to move to column 0
                line 10, ESC[10;H will do.

    ESC[x;yf    Moves cursor to line x column y. One or both of the
                arguments can be omitted, e.g. to move to column 0
                line 10, ESC[10;f will do.

    ESC[x;..;ym Select Graphic Rendition (SGR)

                You can select one or more character renditions at a time
                using the following format:

                ESC[Ps;...Psm

                When you use multiple parameters they are executed in
                sequence. The effects are cumulative. For example, to change
                from increased intensity (or bold) to italic-underlined, you
                can use:

                ESC[0;4;5m

                When you select a single parameter, no delimiter (';') is
                used.

                Ps      Action

                0       All attributes off.
                1       Display bold, or at increased intensity if 4 bitplanes
                3       Display italic
                4       Display underscored
                5       Display italic  (Amiga-ized "blinking")
                7       Display negative (reverse) image.
                2   1   Display normal intensity
                2   3   Display not italic
                2   4   Display not underlined
                2   5   Display not italic
                2   7   Display positive image

                The same sequence is used to change the color of
                the current pen. Colors used by the library are:

                30/40   Black (Standard background)
                31/41   Red
                32/42   Green
                33/43   Yellow
                34/44   Blue
                35/45   Purple
                36/46   Cyan
                37/47   White (Standard foreground)

                To write the words 'Hello world' in green on cyan background
                you can use:

                ESC[32;46mHello worldESC[0m

                The color codes can also be used in combination with the
                graphic rendition, so that you can get 'Hello world' printed
                in cyan on green background by using the display negative
                image:

                ESC[7;32;46mHello worldESC[0m

    ESC[xL      Inserts x lines at the cursor. Default 1.

    ESC[xM      Deletes x lines starting at the lines with the cursor.
                Default 1.

    ESC[xP      Deletes x characters starting with the character at the
                cursor position. Default 1.

    ESC[K       Erases from the cursor to the end of the line, including
                the cursor position.

    ESC[0K      Same as the above.

    ESC[1K      Erases from the beginning of the line to the cursor,
                including the cursor position.

    ESC[2K      Erases the complete line.

    ESC[J       Erases from the cursor to the end of the screen, including
                the cursor position.

    ESC[0J      Same as the above.

    ESC[1J      Erases from the beginning of the screen to the cursor,
                including the cursor position.

    ESC[2J      Erases the complete display.

    ESC[s       Saves in memory the current cursor position.

    ESC[u       Restores the current cursor position from memory.
                If cursor has not been previously saved, the cursor
                will be put at the upper left corner of the screen.


The following control codes are supported by the cwrite.library:

    ASCII       Action

    7           Bell (BEL)
                Calls DisplayBeep to flash the screen.

    8           BackSpace (BS).
                Moves cursor to the left one character position, if cursor
                is at left magin it continues at the right border at the
                line above.

    9           Tabulator (TAB).
                Moves cursor to the next tab stop. Currently tab stops are
                every 8 characters. Does not cause autowrap.

    10          LineFeed (LF).
                Causes a linefeed operation.

    11          Vertical tabulation (VT)
                Processed as LF.

    12          Form Feed (FF).
                Clears the screen.

    13          Carriage Return (CR).
                Moves cursor to left margin on current line.

    132         Index (IND).
                Moves cursor down one line in the same column.
                If cursor is at bottom margin, screen performs a
                scroll up.

    133         Next line (NEL).
                Moves cursor to first position on next line.
                If cursor is at bottom margin, screen performs a
                scroll up.

    140         Reverse index (RI).
                Moves cursor up one line in same column.
                If cursor is at top margin, screen performs a
                scroll down.

       --------------------------------------------------------------

                                 KNOWN BUGS

I  have  discovered,  that the CURSORTYPE_FAST may not work properly together
with  an  interlaced  screen,  and  should therefore only be used on a normal
display (non-interlaced) screen.
-  This  bug will _not_ be fixed, and therefore the CURSORTYPE_FAST should be
avoided, using the CURSORTYPE_SLOW instead.
-  The CURSORTYPE_SLOW routines has been heavily improved until this release,
and there is only very little difference in the speed, so why worry?

       --------------------------------------------------------------

                             WHERE TO CONTACT ME

You can contact me on the following Bulletin Board or FidoNet Address

Per Hansen, SAGA AmigaBBS +45 3116 3217  (2:231/84.0) (Denmark)
