
MwCONIO 1.0
============

MwConio is a 32-bit console I/O library for the Metaware HighC 3.x
C/C++ compiler and the Pharlap 386|DosX (or TNT) DOS-extender. It
tries to be as similar to the Borland version as possible. If you
feel familar with Borland's conio you should know how to use this
library. For description of using the individual functions, goto
the "Functions Reference" section.

This library replaces all conio functions prototyped in Metaware's
CONIO.H. I somewhat feel that it should have been Metaware's job
to provide a decent console interface that fully emulates Borland's.
But here it is free of charge...

All sources are provided as-is without any waranties of any kind.
This package is postcardware/freeware. If you like it and use, you
must send me a nice postcard.

This package is Copyright (c) 1997 Gisle Vanem. Some code (as stated
in the source file) is Copyright (c) 1995 DJ Delorie.


Installation
-------------

A single header file CONIO.H needs to be copied to a location
searched by your compiler. It is not adviceable to overwrite the
original conio.h Therefore, I suggest you make a sub-directory `MW'
in your normal INCLUDE directory and copy CONIO.H into it. E.g:

  MD \HC386\INCLUDE\MW
  COPY CONIO.H \HC386\INCLUDE\MW
                              
Compiling using MwConio (instead of the default CONIO.H) simply needs
the statement:
    #include <mw/conio.h>
in you source file.

This library is compiled using standard C prefix; i.e. `_' is prepended
to all functions. This is contrary to normal Metaware C-functions (they
have no `_' prefix). This could cause trouble if a standard header file
is included after <mw/conio.h>. Therefore, try to include <mw/conio.h>
last.

When linking your program with MwConio, make sure CONIO.LIB is linked
ahead of the standard libraries (HC386,HC387,HCNA etc.). In this way
the standard Metware conio functions will not be used.

CONIO.LIB must be put in a directory searched by the PharLap linker
386LINK. The environment variable LIB is used for this purpose. E.g:

  SET LIB=C:\HC\SMALL;C:\PHARLAP\LIB;C:\PROG\MWCONIO

will search along the LIB-path for all libraries specified on the link
command line. See the MAKEFILE and the LNK variable for usage with the
PharLap linker (386LINK).


Testing
-------

There is a simple test program included; TEST.EXP will not test all conio
functions, but I'm pretty confident the library is complete and operates
as a Borland compiled version would do. If you experience otherwise, please
contact me at the address below.

There is also a speed test program (SPEED.EXP) which shows that MwCONIO
is fast! In-fact approx 40% faster than djgpp 2.01 and 120% faster than
Borland 4.5 (small-model).

The test programs are made as .exp (stubless exe's) in order to keep both
the PharLap and Borland real-mode / djgpp version available for testing at
the same time. To run the .exp file is easy, e.g.:

run386 test.exp

If you have the 4DOS shell (the COMMAND.COM replacement) installed, it's
even easier: Define an environment variable in you autoexec.bat, e.g.:

set .exp=c:\dosx\bin\run386.exe

Now, all .exp files are run with "c:\dosx\bin\run386.exe" prepended to the
commandline. Replace "run386.exe" with "tnt.exe" if you have the PharLap
SDK version 6.0 or higher.



Recompiling
-----------

If you'll like to recompile the library, these are the required tools:

  hc386  C compiler,  Metaware High C/C++ 3.0 or later
  tasm   Assembler,   Borland Turbo Assembler 3.0 or later
  386lib Librarian,   Included in the Pharlap SDK
  make   Make tool,   Any Borland compatible make tool will do.
                      MWMAKE will _not_ work.

The distributed CONIO.LIB has been optimized for Intel 80486. Change
the MAKEFILE if you want to optimise for another processor. Look at the
entries in CONIO.CFG. HighC can optimise for 80386 (option -386), for
80486 (option -486) or Pentium (option -586). I doubt changing this
would have any noticable effect.


History
--------
ver 0.5  10-Apr-1997   Created

ver 1.0  25-Jun-1997   First release


Feedback
--------

I would be happy to receive feedback if you find this package useful
or have any comments or bug reports. Please contact me at one of the
following e-mail addresses:

   giva@bgnett.no  (preferred)
   gv@nera.no





Functions Reference
===================

Variables
----------

Prototype :   int _directvideo;
              int  directvideo;

Description:  Default value is 1. Setting either of these to 0 will use
              BIOS calls for all text printed. A non-zero value will
              print using direct access to video-memory. You may get
              better performance under a multitasking environment if
              setting directvideo to 0. Under plain DOS, leave it default.


Prototype :   int _wscroll;

Description:  Default value is 1. This variable is only used to control
              scrolling. Default behaviour is to scroll-up the window-text
              when the bottom line wraps. To prevent scrolling set to 0.


Prototype :   int _directcursor;
              int  directcursor;

Description:  Default value is 1. This variable is used to control cursor
              positioning. Default behaviour is to move the cursor by
              direct manipulation of the CRT I/O registers. This is a lot
              faster in plain DOS, but can be slower in a multi-tasking
              environment which doesn't virtualise the CRT registers very
              well.


Port I/O
---------

Both Microsoft-style and Borland-style port I/O function are provided.

Prototypes :  int outp (unsigned int port, int value);
              int outportb (unsigned int port, int value);

Description:  Write a byte (8-bit) value to a port register.


Prototypes :  unsigned outpw (unsigned int port, unsigned int value);
              unsigned outport (unsigned int port, unsigned int value);

Description:  Write a word (16-bit) value to a port register.


Prototypes :  int inp (unsigned int port);
              int inportb (unsigned int port);

Description:  Read a byte (8-bit) value from a port register.


Prototypes :  unsigned inpw (unsigned int port);
              unsigned inport (unsigned int port);

Description:  Read a word (16-bit) value from a port register.



String I/O
----------

Prototype:    char *cgets (char *buf);

Description:  Get a string from the console. Before use, you must
              pre-fill the first character of the buffer.  The first
              character is the size of the buffer.  On return, the second
              character is the number of characters read.  The third
              character is the first character read from keyboard.
              Only backspace can be used for editing.
              The return value is a pointer to the first character read.


Prototype:    int cprintf (char *format, ...);

Description:  Like `printf' this function takes a format and a variable
              number of arguments and prints the result to the console.
              Note that no translation is done, `\n' is _not_ translated
              to `\r\n'. Only the control-charcters `\a' (BELL), `\n',
              `\r' and `\b' (Backspace) are handled. The limit of the
              outbuffer is currently 2048 bytes (defined by CBUF_SIZE in
              mwutil.h).
              The return value is the length of buffer printed.

Prototype:    int cputs (char *buf);

Description:  Like `puts' this function prints buf to the console.
              Translation of control-characters are as for cprintf().
              The return value is the last character printed.


Prototype:    int cscanf (char *format, ...);

Description:  Like `scanf' this function takes a format and a variable
              number of storage pointers and reads from the keyboard.
              Each matching variable read is stored at the argument
              specified. Look at test.c for an example.
              The return value is the number of arguments matched.

Prototype:    int putch (int c);

Description:  Writes the character `c' at the cursor location. The cursor
              is advanced after character is written. Translation of
              control-charcters is as in cputs() and cprintf().



Screen clearing
----------------

Prototype:    void clreol (void);

Description:  Clears from cursor to end-of-line. End-of-line is limited
              by right side of the current window.


Prototype:    void clrscr (void);

Description:  Clears the screen using current colour defined by textattr().
              Screen is limited by coordinates of the currently defined
              window.


Prototype:    void delline (void);

Description:  Deletes the current line (which the cursor is on). Text
              underneath current line is scrolled up to fill the void.


Prototype:    void insline (void);

Description:  Insert an empty line at the current line (which the cursor
              is on). Text on current line is scrolled down to make room
              for the new line.



Keyboard input
--------------

Prototype:    int kbhit (void);

Description:  Returns TRUE if a key has been pressed and is waiting to
              be read. Also returns TRUE if a character has been put
              back using ungetch().


Prototype:    int getch (void);

Description:  Read a key-press from keyboard. Waits if necessary.
              No echoing of the key-press is done. Extended keypresses
              (function-keys) will return a 16-bit value; Two succesive
              calls to getch() is needed. The first call returns 0, the
              second call return the scan-code. Any characters put back
              by ungetch() will be returned before a `real' key.

Prototype:    int getche (void);

Description:  As getch(), but with echoing. Any characters put back
              by ungetch() will not be echoed.


Prototype:    int ungetch (int);

Description:  Puts a character back into the key-stream. Only one
              value can be put back at atime. The function return
              EOF (-1) if there's already a value put back.


Screen attributes
-----------------

Prototype:    void highvideo (void);

Description:  Enables the high-intensity foreground colours. E.g. if
              current colour is LIGHTGRAY (colour 7), highvideo() will
              set WHITE (colour 15) as the default text colour.


Prototype:    void lowvideo (void);

Description:  Enables the low-intensity foreground colours. E.g. if
              current colour is YELLOW (colour 14), lowvideo() will
              set BROWN (colour 6) as the default text colour.


Prototype:    void normvideo (void);

Description:  Enables the colour that was active when the program was
              started. Or more presicely, when the first conio function
              was called.


Prototype:    void textattr (int attr);

Description:  Enables the foreground/background colour defined in attr.
              The attr consists of 4-bits for forground colour, 3-bit
              for the background colour and 1-bit for the blinking
              attribute. E.g. to get blinking lightred forground on a
              blue background call: textattr (LIGHTRED+16*BLUE+BLINK);


Prototype:    void textcolor (int colour);

Description:  Enables the foreground colour defined in colour.
              Colours are defined in the enumeration COLORS in <conio.h>.
              Only values 0 - 15 are legal.


Prototype:    void textbackground (int colour);

Description:  Enables the background colour defined in colour.
              Colours are defined in the enumeration COLORS in <conio.h>.
              Only values 0 - 7 are legal.


Prototype:    void textmode (int mode);

Description:  Sets the screen textmode to one of the following
              modes; LASTMODE=-1, BW40=0, C40, BW80, C80, MONO=7, C4350=64


Prototype:    void gettextinfo (struct text_info *ti);

Description:  This function fills the text_info structure with values
              currently in use. Look at struct text_info in <conio.h>.



Window functions
----------------

Prototype:    void window (int x1, int y1, int x2, int y2);

Description:  Defines a screen region for all conio functions.
              Window is defined by upper-left corner <x1,y1> and
              diagonal lower-right corner <x2,y2>. Window content
              will scroll-up if trying to write past window.


Prototype:    int gettext (int x1, int y1, int x2, int y2, void *dest);

Description:  Copies a raw screen region into a user supplied buffer at
              dest. User must ensure the buffer is large enough.
              Region defined by window() is ignored. Return value is
              always TRUE.

Prototype:    int puttext (int x1, int y1, int x2, int y2, void *src);

Description:  Copies a user supplied buffer to the screen region
              confined by corners <x1,y1> and <x2,y2>. Region defined
              by window() is ignored. Return value is always TRUE.


Prototype:    int movetext (int x1, int y1, int x2, int y2, int to_x, int to_y);

Description:  This routine is a combination of gettext() and puttext().
              Screen region confined by corners <x1,y1> and <x2,y2> is
              copied to new upper-left corner <to_x,to_y>. Region defined
              by window() is ignored. Return value is always TRUE.


Cursor functions
-----------------

Prototype:    void gotoxy (int x, int y);

Description:  Moves the cursor to position defined by column `x'
              and row `y'. The position is relative to the currently
              active window. Position are 1-based, e.g. "gotoxy(1,1);"
              puts the cursor in the upper-left corner of the window.
              Note: If _directcursor is non-zero, the cursor if moved by
              manipulating the CRT I/O registers.

Prototype:    int wherex (void);

Description:  Returns the cursor column position relative to the
              currently active window.


Prototype:    int wherey (void);

Description:  Returns the cursor row position relative to the currently
              active window. Range is (1 - maxy).


Prototype:    void _setcursortype (int type);

Description:  Changes the appearance of the cursor. The type is 1 of
              these 3 values:
                _NOCURSOR      0
                _SOLIDCURSOR   1
                _NORMALCURSOR  2



Various functions
-----------------

The following functions are normally defined in <dos.h>, but are
repeated here:

Prototype:    void delay (unsigned int milli_sec);

Description:  Delayes the program for the specified number of
              milli-seconds.


Prototype:    void sound (unsigned int freq);

Description:  Turns on the PC speaker with tone of frequency freq Hz.


Prototype:    void nosound (void);   /* is in fact a macro */

Description:  Turns off the PC speaker.



Contacting me
-------------

I will accept bug reports, comment or suggestions. Please contact
me at one of these addresses:

Home:     Gisle Vanem
          Nordaas brotet 103,    For TeX'pert that is "Nord{\a}s brotet 103,"
          5046 Raadal,                                "5046 R{\a}dal"
          Norway

email:    giva@bgnett.no
          gv@nera.no
