zTerminal
=============================================================================

	Summary  A display class for interpreting escape sequences.

	Remarks  This is a fairly involved class that can automatically handle
	         various types of escape sequences. It currently supports
	         ANSi, Avatar/0+ (basic), PCBoard (@Xbf), Wildcat! (@bf@),
	         hex pipes (|bf), ProBoard language codes (\bf, \Hc, \Lc),
	         and RemoteAccess text file color change codes (^K[xx). Note
	         that you must install the appropriate handlers for any of
	         the above sequences. The zTerminal object does not handle
	         anything on its own. You can also install your own handler
	         that will be invoked when its SOS (Start-Of-Sequence) character
	         is found in the input stream. Also, there are currently three
	         forms of output control. Color change and cursor positioning
	         (clearing the screen and to the end of the line too) are
	         handled by the so-called terminal control objects. There are
	         three built-in controls (ANSi, which uses ANSi escape sequences,
	         Avatar/0+ and console, which is the one you would normally use).
	         You can also install your own terminal control should you decide
	         to handle output differently.

	         The typical sequence of creating a usable terminal would be
	         to instantiate several handlers from the list below, then
	         use the RegisterHandler() function to install them in the
	         terminal object. Note that the precedence when choosing the
	         interpreter to use goes from last to first in the order of
	         installation. You can use any of these predefined interpreters:

	             ansi_interp         - ANSI interpreter
	             avatar_interp       - Avatar/0 and AVT/0+ (basic only)
	             pcboard_interp      - PCBoard and Wildcat! @Xcc and @cc@
	             hexpipe_interp      - hex pipe colors, |cc, codes
	             proboard_interp     - ProBoard language file color codes
	             remoteaccess_interp - RemoteAccess ^K[cc color codes
	             textcode_interp     - ^F and ^K sequences (PB/RA/special)
	             macro_interp        - ProBoard @<macro>@ text macros

	         As you see, you already have plenty of choices! Depending on
	         your needs, add one or more from the above list. You can also
	         create your own installable interpreters.


	ZTERMINAL::ZTERMINAL
	-------------------------------------------------------------------------

		Summary  Constructs the terminal object.

		Syntax   zTerminal();

		Remarks  This constructor does not register any terminal interpreters
		         but only sets the default output control type to the one
		         most commonly used (local video which also works with SDK).
		         It also retrieves the current cursor position so that the
		         subsequent output would start from there. If you want to
		         start at the beginning of the screen, you need to reset the
		         cursor position to the home location before the constructor
		         (or use the cursor positioning after you construct it).

		Return   n/a

		Example  zTerminal terminal;  // used in all examples below


	ZTERMINAL::~ZTERMINAL
	-------------------------------------------------------------------------

		Summary  Destructor for the terminal.

		Syntax   ~zTerminal();

		Remarks  The only function of the destructor is to flush the current
		         handler (if any) to ensure that all characters are shown.

		Return   n/a

		Example  n/a


	ZTERMINAL::BUSY
	-------------------------------------------------------------------------

		Summary   Returns the status of the terminal interpreter.

		Syntax    Boolean busy() const;

		Remarks   This routine returns the status of the interpeters (if
		          any). A False value means that no handler is currently
		          active. This is mainly for instances when you might want
		          to pre-process the input and you wish to find out if a
		          particular character is a part of a sequence or not (for
		          example, 0x01 may be a valid character in some instances,
		          but you might want to use it as a standalone). Note that
		          a busy status does not really mean that the character will
		          get interpreted, it simply means that a handler is
		          currently trying to parse the sequence. Generally, this
		          would be sufficient.

		Return    True if a handler is active, False otherwise.

		Example   if( 1 == inputChar && !terminal.busy() )
		              terminal.clr_scr(); // clear screen on 0x01 code


	ZTERMINAL::FLUSH
	-------------------------------------------------------------------------

		Summary   Flushes the contents of the current handler.

		Syntax    void flush(Boolean display = True);

		Remarks   This flushes the current handler's buffer (if any). It
		          is automatically called by the destructor of the object,
		          but you may need to call it in between different input
		          because some handler might be holding characters expecting
		          more to complete the sequence. This will write the buffer
		          to output before any further processing is attempted. Note
		          that if the 'display' variable is False, the buffers are
		          flushed without any actual screen output. This is useful
		          if you want to abort a display prematurely (e.g. hotkey
		          detected during a display of a menu).

		Return    Nothing.

		See also  zTerminal::empty

		Example   terminal.flush();


	ZTERMINAL::HANDLE
	-------------------------------------------------------------------------

		Summary   These routines handle the input stream.

		Syntax    void handle(uchar aChar);
		          void handle(uchar *aString);
		          void handle(char *aString);

		Remarks   These are the three main functions which handle the input
		          stream passed by the application to the object. Basically
		          you need to call the appropriate function to get the input
		          interpreted.

		Return    Nothing.

		Example   FILE      *fp;

                  if( 0 != (fp = fopen("DISPLAY.ANS", "rb")) )
                  {
                      int ch = fgetc(fp);
                      while( !feof(fp) && 0x1a != ch )
                      {
                          terminal.handle( ch );
                          ch = fgetc(fp);
                      }
                      fclose(fp);
                  }


	ZTERMINAL::CLRSCR, ZTERMINAL::CLREOL
	-------------------------------------------------------------------------

		Summary   Clear the screen and to the end of the line.

		Syntax    void clrScr();
		          void clrEol();

		Remarks   These are the same as the standard clrscr() and clreol()
		          routines except they take into account the current terminal
		          and use its functions to perform the task. The first one
		          will clear the screen (in Avatar/0+ this also resets the
		          attribute to Cyan on Black) and home the cursor at (1;1).
		          The second one will clear the current line from the cursor
		          position to the end using the current attribute.

		Return    Nothing.

		Example   n/a


	ZTERMINAL::SETROWS, SETCOLS, GETROWS, GETCOLS
	-------------------------------------------------------------------------

		Summary   Set the dimensions of the display.

		Syntax    void setRows(int nRows);
		          void setCols(int nColumns);
		          int  getRows() const;
		          int  getCols() const;

		Remarks   The default screen dimensions are 80x25. You can change
		          this using these two functions (usually, for people with
		          more display rows calling the BBS). The only place the
		          screen dimensions are used is when validating cursor
		          relocations. Note that when initializing the terminal,
		          the values for the screen dimensions are read from the
		          current user's record. The get??() methods return the
		          respective values.

		Return    getRows() returns the number of display rows;
		          getCols() returns the number of display columns

		Example   // set dimensions to 80x50
		          terminal.setRows(50);


	ZTERMINAL::SETBG, ZTERMINAL::SETFG, ZTERMINAL::SETCOLOR
	-------------------------------------------------------------------------

		Summary   Set the current display attribute.

		Syntax    void setBg(int bgColor);
		          void setFg(int fgColor);
		          void setColor(int attrib);

		Remarks   These routines are used to change the current display color
		          attribute. For the format of the attribute, refer to the
		          getColor() function documentation. Note that setBg() is
		          also used to change the blinking (if the 4th bit is set,
		          blinking will be enabled).

		Return    Nothing.

		See also  zTerminal::getBg, zTerminal::getFg, zTerminal::getColor

		Example   (see the zTerminal::getColor for an example)


	ZTERMINAL::GOTOXY
	-------------------------------------------------------------------------

		Summary   Sets the current cursor position.

		Syntax    void gotoXY(int xColumn, int yRow);

		Remarks   This routine performs like the standard gotoxy() except
		          it will use the current terminal's version to do the actual
		          cursor repositioning. Columns are numbered from 1 to max
		          (where the default maximum is 80, but it can be adjusted).
		          Rows are numbered from 1 to max (where the default maximum
		          is 25, but can be adjusted also).

		Return    Nothing.

		See also  zTerminal::setCols, zTerminal::setRows

		Example   n/a


	ZTERMINAL::GETX, ZTERMINAL::GETY, ZTERMINAL::GET_LINES
	-------------------------------------------------------------------------

		Summary   Return the current display row and column.

		          int getX() const;
		          int getY() const;
		          int getLines() const;

		Remarks   getY() returns the current display row (1..maxRows).
		          The default maximum row is 25, but it can be adjusted. The
		          getX() function returns the current display column
		          (1..maxColumn). The default maximum column is 80, but it
		          can be adjusted also. getLines() is a peculiar function:
		          it returns the difference (in number of lines) between the
		          last output operation and the previous one. This is mainly
		          used to determine when to do screen pausing. Note that
		          this does not really take into account cursor relocations,
		          just when output wraps to new lines or scrolls the screen.

		Return    getY() returns the row
		          getX() - the column
		          get_lines() - the row difference (0 if none)

		See also  zTerminal::setRows, zTerminal::setCols

		Example   int x = terminal.getX();
		          terminal.gotoXY(x - 1, terminal.getY());


	ZTERMINAL::GETBG, ZTERMINAL::GETFG, ZTERMINAL::GETCOLOR
	-------------------------------------------------------------------------

		Summary   Return the current display attribute.

		Syntax    int getBg() const;
		          int getFg() const;
		          int getColor() const;

		Remarks   These routines return the various parts of the current
		          display attribute. Note that is getBg()'s return value
		          has the 4th bit set, the attribute is blinking (i.e. if
                  get_bg() & 8, the text is blinking). The bitmapped return
                  value of get_attrib() is the same as the standard PC
                  attribute specification:

                            7 6 5 4 3 2 1 0
                            | |   | | +---+---- foreground color
                            | |   | +---------- high intensity bit
                            | +---+------------ background color
                            +------------------ blink enable bit

                  Note that getFg() returns the low 4-bytes and getBg()
                  returns the high 4 bytes of this attribute.

		Return    getBg() returns the background color,
		          getFg() returns the foreground color,
		          getColor() returns the bitmapped attribute

		See also  zTerminal::setBg, zTerminal::setFg, zTerminal::setColor

		Example   // this example toggles the blinking bit
		          int bgColor = terminal.getBg();
		          if( bgColor & 8 ) terminal.setBg(bgColor & 7);
		          else terminal.setBg(bgColor | 8);


	ZTERMINAL::REGISTERHANDLER
	-------------------------------------------------------------------------

		Summary   Registers a handler for the input sequences.

		Syntax    void RegisterHandler(term_interp* handler);

		Remarks   This routine installs a user-defined handler. The handler
		          must be derived from the 'term_interp' class. There are
		          several handlers provided for your convenience; all you
		          need to do is create the appropriate objects and then
		          pass pointers to them to this method. Note that when the
		          terminal object is destroyed, the registered handlers are
		          _not_ destroyed with it. You need to do this yourself. Also
		          note that since the terminal only stores pointers, if you
		          invalidate an interpreter and then try to use the terminal,
		          you will certainly run into a lot of problems. Note that
		          this function is the heart of the terminal. Nothing will
		          be interpreted unless you install handler(s). You can
		          currently install 20 of these interpreters. Attempts to
		          exceed this number will be ignored.

		Return    Nothing.

		See also  term_interp class.

		Example   ansi_interp ansi;
		          zTerminal   terminal;

		          terminal.RegisterHandler(&ansi);


    ZTERMINAL::ENABLEHANDLER
    -------------------------------------------------------------------------

        Summary   Enables or disables a currently installed handler.

        Syntax    void EnableHandler(term_interp *handler, Boolean enable);

        Remarks   This function must be called if you want to suspend or
                  resume the operation of a handler. When you call the
                  registration method, the handler's default state will be
                  enabled. If you want to temporarily disable the operation
                  of the handler, call this method with a pointer to the
                  interpreter you want to disable (the same pointer used
                  with RegisterHandler), and 'enable = False'. If you want
                  to resume the operation of a previously suspended handler,
                  simply use the pointer, but this time enable will be True.

        Return    Nothing.

        See also  zTerminal::UnloadHandler

        Example   avatar_interp handler;
                  zTerminal     terminal;

                  terminal.RegisterHandler(&handler);
                  terminal.EnableHandler(&handler, False);


    ZTERMINAL::UNLOADHANDLER
    -------------------------------------------------------------------------

        Summary   Permanently removes a handler.

        Syntax    void UnloadHandler(term_interp *handler);

        Remarks   Unlike EnableHandler() which only temporarily disables the
                  particular handler, this function will remove the handler
                  from the terminal object altogether. It will not free the
                  memory allocated to it, this is your responsibility.

        Return    Nothing.

        See also  zTerminal::EnableHandler

        Example   pcboard_interp  pcb;
                  proboard_interp pb;
                  zTerminal       terminal;

                  terminal.RegisterHandler(&pcb);
                  terminal.RegisterHandler(&pb);
                  terminal.UnloadHandler(&pcb);
                  // now only ProBoard sequences will be interpreted


	ZTERMINAL::REGISTERCTRLHANDLER
	-------------------------------------------------------------------------

		Summary   Registers a new terminal control emulation for output.

		Syntax    void RegisterCtrlHandler(term_ctrl *aContrl);

		Remarks   This is a rarely used routine. You should call it when
		          you implement an alternative color and cursor control
		          terminal. It has to be derived from term_ctrl class and
		          provide all necessary functions. Then you would pass a
		          pointer to the object of the new class to this function.
		          Several controls are already available 'console_ctrl'
		          which does direct video I/O and modem when SDK is used,
		          (this is the default), ansi_ctrl which uses ANSI escape
		          sequences for the output, and avatar_ctrl which uses the
		          Avatar/O+ sequences.

		Return    Nothing.

		See also  term_ctrl class.

		Example   (see the source code notes)
