
                                                          1996/05/02


1. Disclaimer
-------------  
 
   Copyright (c) 1996 Dipl.-Ing.,Dipl.-Ing.(FH)  Jurgen Eidt
   All rights reserved.
   GPL-Copying-policy
  
   Redistribution and use in source and binary forms are permitted
   provided that the above copyright notice and this paragraph are
   duplicated in all such forms and that any documentation,
   advertising materials, and other materials related to such
   distribution and use acknowledge that the software was developed
   by Jurgen Eidt.  The name may not be used to endorse or promote 
   products derived from this software without specific prior written 
   permission.
   THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
   IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
   WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.



2. Compile example and Install 
------------------------------

   I'am glad to see, that you have unpacked this package!
   
   in:
     constream-0.4/
   type: 
     make
     
   to compile the example. 
   An executable "example" will be build (NCurses installed, 
    compiler and libs Ok ?? ).

   To use the interface, just copy constream.[cc,h] to your
   project directory and add constream.[cc,h,o] to your Makefile.



3. constream - what is it ?
---------------------------

   an interface based on ostream to redirect an outputstream to the 
   textscreen.

   With the constream interface that comes with the Borland C++ package
   for DOS, you have an easy to use interface to the textscreen.
   Now you can use these functionalities on a Linux (UNIX) platform!
   I have designed the interface to be fully compatible (I hope! ) with the 
   DOS platform.

   When no colors are available, all manipulators for changing colors
   are ignored, i.e. in a xterm or a simple non color shell, however,
   non color attributes (like "reverse") will work.
   
   
   example:
   

    #include"constream.h"
    #include<istream.h>         // for the cin-operator

    int main()
    {
      constream con;
      con.window(9, 4, 29, 8);
      con << "Hello World!, press a key!" << endl;
 
      char c; cin >> c;
    }


   results in:
   
     +-----------------------------------------...----+  
     |                                                |
     |                                                |   
     |       +--------------------+                   |
     |       |Hello World!, press |                   |
     |       |a key!_             |                   |
     |       |                    |                   |
     |       |                    |                   |
     |       +--------------------+                   |
     |                                                |
     :                                                :
     :                                                :
     |                                                |
     +-----------------------------------------...----+  



   

   **************************************
   Could someone test it on other UNIXs ?
   **************************************
   

   maybe there are some inconsistency ...
   please do not flame, I would prefer E-Mail, or even better, send me 
   a postcard of your village or hometown !!

   

4. Programmers reference
------------------------

class constream 

 redirects the outputstream to the screen using the iostream interface.
 (It's compatible with the constream interface of Borlands C++ DOS package)

 The include file "constream.h" consists of declarations, file "constream.cc"
 contains the definitions.
 Now, there is no need for any NCurses initialization, except some terminal-
 specific things (i.e. keyboard settings)

 For performance reason, the refresh-function of ncurses is not called
 for every character in the output string.
 i.e. con << "Hello World";
 is only visible with the next flush. And this is done by endl, flush or
 a manipulator.
 Updating every character would slow down the system too much!

 
 Reference:
 ----------

 The instance "con" is used as an example and has no other meaning.
 COLS and LINES are NCurses specific and represent the max Columns 
 and Lines of the screen.



 Constructor:

   constream    defines an constream object with a default window 
                of max. size (1, 1, COLS, LINES)
                i.e. constream con;
                Normaly, a later window-call to resize the object
                is done (see section <window> ).


 Members:

   clrscr()     clears the Screen
                i.e. con << setclr(BLUE) << setbk(WHITE);
                     con.clrscr(); 
                The first clrscr() makes the current colorattributes
                permanent to the object.
                The next time when a clrscr() is done, BLUE and
                WHITE will be used as the foreground and back-
                ground-color.
                clrscr can have an additional argument <chtype> to
                specify the fill char for the background. See
                section <clrscr(ch)>.
                 
                 
   window(int x1, int y1, int x2, int y2)
                specify a screenarea for the associated object
                i.e. con.window(4, 5, 10, LINES-2); 

                For invalid arguments, nothing is changed
                (the default window of max. size is used
                 with setbk(...), it's an easy way of a
                 clear-screen with a backgroundcolor).
                
                The upper-left corner is (1, 1) and 
                the lower-right corner is (COLS, LINES).
                i.e. for a standard screen (1, 1), (80, 25)
                note that COLS and LINES are NCurses specific.


   int wherex()         returns the x-cursor postion

   int wherey()         returns the y-cursor postion             
   


 Attributes:

   buf          returns the assigned (streambuf)class
   

   
 Manipulators assigned to the contream-class:

   clreol       deletes from current cursor position to 
                the end of the line
   
   delline      delete Line :-)
   
   insline      ???, ok, inserts (empty) line
   
   highvideo    the next output is highlighted (bright)
   
   normvideo    the next output is normal, used to reverse highvideo
   
   lowvideo     like normvideo
   
   setclr(COLOR)        sets foreground color:
                        DOS conio-Colors can be used: 
                          BLACK, RED, GREEN, YELLOW, BLUE, 
                          MAGENTA, CYAN, WHITE
                        i.e. con << setclr(BLUE)
                        The colors represents a number between 0 and 7.
                        (BLACK=0, RED=1, ..., WHITE=7)
                        (Arguments exceeding that range will be resized
                         with the AND-mask 0x07)
                         
                        
   setbk(COLOR)         sets background color
   
   setattr(COLORPAIR)   sets fore- and background color at once
                        i.e. con << setattr(BLUE<<4 | WHITE);
                        Sets WHITE as foreground and BLUE as background
                        with the high nibble representing the background 
                        and the lower 4 bits with the foregroundcolor.
                        
                        
   setcrsrtype(i)       set the cursor type 
                        0:invisible
                        1:normal
                        2:visible
                        
                        Results in a call to "curs_set(int)" from
                        ncurses.
                        
                        
   setxy(x, y)          moves the cursor to (x, y)
                        The upper-left position of a window is (1, 1)
                        invalid values result in nothing :-)
                


Funcionalities exceeding Borlands Library:

 Constructor:

   constream(int x1, int y1, int x2, int y2)
                defines an constream object bound to a window
                i.e. constream con(2, 5, 20, LINES-4);
                replaces constream con;
                         con.window(...);


 Members:
   clrscr(ch)   clears screen with charcter ch
                i.e. con.clrscr(ACS_CKBOARD);
                Fills the window (or background, when no window
                is specified) with the squareboard character.
                
                clrscr expects a chtype as an argument. You can
                use the predefined ACS_XXXXX constants that
                come with NCurses. 
                
                ACS_ULCORNER	/* upper left corner */
                ACS_LLCORNER	/* lower left corner */
                ACS_URCORNER	/* upper right corner */
                ACS_LRCORNER	/* lower right corner */
                ACS_LTEE	/* tee pointing right */
                ACS_RTEE	/* tee pointing left */
                ACS_BTEE	/* tee pointing up */
                ACS_TTEE	/* tee pointing down */
                ACS_HLINE	/* horizontal line */
                ACS_VLINE	/* vertical line */
                ACS_PLUS	/* large plus or crossover */
                ACS_S1		/* scan line 1 */
                ACS_S9		/* scan line 9 */
                ACS_DIAMOND	/* diamond */
                ACS_CKBOARD	/* checker board (stipple) */
                ACS_DEGREE	/* degree symbol */
                ACS_PLMINUS	/* plus/minus */
                ACS_BULLET	/* bullet */
                /* Teletype 5410v1 symbols begin here */
                ACS_LARROW	/* arrow pointing left */
                ACS_RARROW	/* arrow pointing right */
                ACS_DARROW	/* arrow pointing down */
                ACS_UARROW	/* arrow pointing up */
                ACS_BOARD	/* board of squares */
                ACS_LANTERN	/* lantern symbol */
                ACS_BLOCK	/* solid square block */
                /*
                 * These aren't documented, but a lot of System Vs have them anyway
                 * (you can spot pprryyzz{{||}} in a lot of AT&T terminfo strings).
                 * The ACS_names may not match AT&T's, our source didn't know them.
                 */
                ACS_S3		/* scan line 3 */
                ACS_S7		/* scan line 7 */
                ACS_LEQUAL	/* less/equal */
                ACS_GEQUAL	/* greater/equal */
                ACS_PI		/* Pi */
                ACS_NEQUAL	/* not equal */
                ACS_STERLING	/* UK pound sign */
        
               
   reset        restore the color and resets the attributes
                i.e. con.reset();
                The same operation is implemented as a manipulator.
   

   
 Manipulators:

   blinkon      following Output has the blinking attribute  
   
   blinkoff     undo blinkon
   (In DOS you use the color BLINK and OR it to the COLOR)     
   
   reverseon    exchange background and foregroundcolor
   
   reverseoff   undo reverseon

   reset        restore the color and resets the attributes
                i.e. con << reset;
                same functionality as the member <reset>


                
5. How to contact me
--------------------
   
   
    Jurgen Eidt
    Dromersheimer Str. 2
    D-55411 Bingen am Rhein
    Germany

    That's me :-)
    


    and that's my mail-adress:
       
    E-Mail: jurgen@tap.de 
    FidoNet: 2:2455/240.25
   
