


             TCCONIO library for LCC-Win32 documentation



Daniel Guerrero Miralles
(daguer@geocities.com)
September 1999.



ABSTRACT
--------

Do you like retro-computing? Do you remember the old good days of Borland
compilers under MS-DOS? Then you will love this one.

Recently I have been working in a complex project, and wanted to do some 
experimentation. To do the experiments I chosed to write several small 
console programs, mainly because they are simpler to code than GUI programs.
Then I realized that I needed to change the cursor position on the console, 
so I looked arround in the LCC-Win32 header files for a suitable function. 
To my surprise, there was not such a funtion!

When I started to learn C, a couple of years ago, my old Turbo-C 2.0 came
with a function in the CONIO.H header file called "gotoxy()" for this 
purpose, but Win32 compilers usually lack such functions. Instead of this,
you must use some Win32 API functions, but they are complex, and all I 
wanted to do was move the cursor!.

So I decided to write a library with all the functions not found in 
LCC-Win32 CONIO.H, and I almost succeed (with certain limitations). For 
example, I didn't managed to make the "window()" function to work, but 
if you want to create windows, there is a GUI API you can use, right?

Please, be aware that these functions must pass several software 
layers (mainly inside Windows itself) before reaching the hardware, 
so don't expect them to be "blazing fast".


FUNCTIONS
---------

This is the list of functions found in the library:


Port I/O functions:
-------------------

WORD inport (int port_num);
	Reads a WORD value from the hardware port 'port_num'.
	
BYTE inportb (int port_num);
	Reads a BYTE value from the hardware port 'port_num'.
	
void outport (int port_num);
	Writes a WORD value to the hardware port 'port_num'.

void outportb (int port_num);
	Writes a WORD value to the hardware port 'port_num'.

[NOTE: I haven't tested these functions. I don't know what to do with
them. Anyway, I suspect that they may be only useful to crash programs
(in and out opcodes shouldn't be available for programs in 32-bit 
Protected Mode).]


Console control functions:
--------------------------

void textmode (int newmode);
	This function allowed to change the hardware screen mode. This is not
	possible in Windows, so the function only resets the console to the
	default state: clears the screen, sets the default text colors and shows
	the normal cursor shape.
	
void window (int left, int top, int right, int bottom);
	Used to allow you to redefine the screen output window, resticting the 
	output to certain rectangle. This function does nothing in this 
	implementation, but was kept for compatibility (with my old programs, 
	at least).
	
void gettextinfo (struct text_info * pTI);
	Retrieves information about the status of the console. Certain fields 
	are useless because their values are fixed, for example the output 
	window origin. The text_info struct is defined as follows:
	
	struct text_info
	{
		unsigned char winleft;
		unsigned char wintop;
		unsigned char winright;
		unsigned char winbottom;
		unsigned char attribute;
		unsigned char normattr;
		unsigned char currmode;
		unsigned char screenheight;
		unsigned char screenwidth;
		unsigned char curx;
		unsigned char cury;
	};
	
	the fields values mean:
	- winleft, winright, wintop, winbottom: coordinates of the output 
	window. Since they cannot be changed, their value is meaningless.
	- attribute: current attribute (foreground and background colors) used 
	for text output.
	- normattr: default text attribute (set when normvideo() is called).
	- currmode: current video mode. This value is fixed to C80 (80 columns 
	color display).
	- screenheight, screenwidth: width and height of the screen, in 
	characters. This values ARE meaningful, because the console size can 
	be changed by the user.
	- curx, cury: current cursor possition.


Cursor functions:
-----------------

int wherex (void);
	Retrieve the current horizontal position of the cursor, in characters.
	
int wherey (void);
	Retrieve the current vertical position of the cursor, in characters.
	
void gotoxy (int x, int y);
	Change the current cursor position. Valid values ranges are 
	(1..sceenwidth, 1..screenheight), beeing (1,1) the coordinates of the 
	upper left corner of the display.

void _setcursortype (int cur_t);
	change the cursor shape. Valid values for the cur_t parameter are:
	_NOCURSOR: makes the cursor invisible.
	_SOLIDCURSOR: makes the cursor look like an full block.
	_NORMALCURSOR: makes the cursor look like an underscore. This is the 
	default shape for the cursor.


Text color functions:
---------------------

void highvideo (void);
	Makes subsequent output text to apperar brighter. If the text is 
	already in high video, the function does nothing.
	
void lowvideo (void);
	Makes subsequent output text to apperar darker. If the text is already 
	in low video (the default), the function does nothing.

void normvideo (void);
	Sets the default colors for the text (gray characters over a black 
	background).
	
void textcolor (int color);
	Sets a new color for text. Color can be any of the following:
	BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY, 
	DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED, LIGHTMAGENTA, 
	YELLOW, WHITE.
	The first 8 colors are in low video, while the last 8 are in high video.
	This means that if you have set the text color to BLUE and call 
	highvideo(), subsequent text will be displayed in LIGHTBLUE.
	
void textbackground (int color);
	Set a new color for the text background. You can use the same values 
	as for textcolor().

void textattr (int newattr);
	Set the text color and background in one call. Text and background 
	colors are encoded in the 'newattr' value by shifting the background 
	color value to the left 4 bits and then bitwise OR-ing or adding it 
	with the text color. For example, the 'newattr' value for YELLOW text
	on a BLUE background will be: (BLUE << 4) + YELLOW


Text I/O functions:
-------------------

void clrscr (void);
	Clears the screen. This is a really useful one.

void clreol (void);
	Clears all text from the current cursor position up to the right console
	margin (end of line).

void insline (void);
	Inserts a blank line at the current cursor position, scrolling down all 
	lines below.

void delline (void);
	Removes the current line, scrolling up all lines below, and inserting a 
	blank line at the screen bottom.

int movetext (
		int left, 
		int top, 
		int right, 
		int bottom, 
		int destleft, 
		int desttop);
	Copies (despite of its name) a rectangular section of the screen to 
	another place. Parameters are:
		- left, right, top, bottom: coordinates that describe the source
		rectangle. The upper left corner of the screen is (1,1).
		- destleft, desttop: coordinates of the uppper left corner of the
		destination rectangle. The destination rectangle has the same size
		of the source one.
	The return value is 1 if the text could be copied or 0 if it was not, 
	for example because the coordinates where invalid.
	
int gettext (int left, int top, int right, int bottom, void * destin);
	Saves the contents of a rectangular section of the screen into the 
	buffer pointed by 'destin'.
	This functions retrieves the text and the attributes, using the 
	following format:
	[char 0][attrib 0][char 1][attrib 1]...[char n][attrib n]
	So, each char-attrib pair has the size of 2 characters. Note that this 
	function can work with ANSI (OEM) characters as well as with Unicode 
	ones. If you are working with Unicode, each char-atrib pair will have 
	the size of two WCHARs.
	The return value is 1 for success, and 0 for failure.

int puttext (int left, int top, int right, int bottom, void * source);
	Restores the contents of a text rectangular region previously saved 
	with gettext().
	The return value is 1 for success, and 0 for failure.

char * getpass (const char * promt);
	Reads a password (up to 8 characters) without echoing. You can pass 
	a text string as the 'promp' parameter, that will be displayed before
	reading the password. The function returns a pointer to an internal 
	static buffer that is overwritten from call to call. Be carefull if
	you use this routine, because edition keys (cursors and delete) are
	not available (as in the Borland's version).


THAT'S ALL
----------

Well, I hope you find the library useful, even with the given limitations. 
At least, I think it can serve to teach how to use the Win32 console API.
Enjoy, and nice coding!.


LEGAL STUFF
-----------

All company and product names mentioned in this document may be trademarks 
or registred trade marks of their respective owners, and are used for 
informative purposes only. This text may contain errors and innacuracies. 
It is provided "AS IS", without warranties, both express or implied, 
including, but not limited to, fitness for any particular purpose.
