explaining standard c++ way of clearing screen

[jonathanYoung]

allrighty, this MAY take a bit to answer, but i have here a standard visual c++ function that clears the screen, i found off the internet. what i need, is some help knowing what all the different functions inside do.... since codes useless unless you know what it does :)
note: when i try looking up each individual function on google, i find that it sends me right back to were i got this code from.

void clearscreen()
{
HANDLE hndl = GetStdHandle(STD_OUTPUT_HANDLE);
	CONSOLE_SCREEN_BUFFER_INFO csbi;
	GetConsoleScreenBufferInfo(hndl, &csbi);
	DWORD written;
	DWORD n = csbi.dwSize.X * csbi.dwCursorPosition.Y + csbi.dwCursorPosition.X + 1;	
	COORD curhome = {0,0};
	FillConsoleOutputCharacter(hndl, ' ', n, curhome, &written);
	csbi.srWindow.Bottom -= csbi.srWindow.Top;
	csbi.srWindow.Top = 0;
	SetConsoleWindowInfo(hndl, TRUE, &csbi.srWindow);
	SetConsoleCursorPosition(hndl, curhome);
}

[Clinton Portis]

i have here a standard visual c++ function that clears the screen

Be rest assured, this is not standard c++.

What this is though, is a group of functions derived from <windows.h> called the "windows advanced programming interface" or API.

The window.h library contains thousands of functions that allow you access to the deep internal workings of your computer. With the windows api, you can create windows, draw bitmaps, create multi-threaded programs, play sound, create timers, send data to the printer, create makefiles, and edit the system registry... and that just for starters. As you can see, it is a very powerful api.

Although very powerful, it is also very non-portable and is specific to only windows operating systems.

The forger's win32 tutorial is where most people go to get their first glimpse of windows programming.

More relevant to your question, here is a cool tutorial for windows programming in the dos environment.

So, to answer your question, we'll go through each function and tell briefly what it does:

GetStdHandle()
Returns a 'Handle' to the Dos Console window.

GetConsoleScreenBufferInfo()
The sole purpose of this function is to populate a struct called, CONSOLE_SCREEN_BUFFER_INFO with useful information.

Here is the groovy information that can be found inside the CONSOLE_SCREEN_BUFFER_INFO struct:

typedef struct _CONSOLE_SCREEN_BUFFER_INFO {
  COORD      dwSize;
  COORD      dwCursorPosition;
  WORD       wAttributes;
  SMALL_RECT srWindow;
  COORD      dwMaximumWindowSize;
} CONSOLE_SCREEN_BUFFER_INFO

COORD is a pretty self explanitory struct:

typedef struct _COORD {
  SHORT X;
  SHORT Y;
} COORD, *PCOORD;

FillConsoleOutputCharacter()
Writes a character to the console screen buffer a specified number of times, beginning at the specified coordinates.

SetConsoleWindoInfo()
Sets the current size and position of a console screen buffer's window.

SetConsoleCursorPosition()
Sets the cursor position in the specified console screen buffer.

Windows api functions can seem overwhelming at first. At second glance however, you can see that each function name is very self documenting; the function name alone can tell you what the function does. And if you're still not sure, MSDN is the home of every api function used in the windows enviorment. It is possible to look up documentation for any api function you desire.

void clearscreen()
{
        //Obtain a 'handle' to the DOS Console window
        HANDLE hndl = GetStdHandle(STD_OUTPUT_HANDLE);
        //Create an object to be populated with useful information about the DOS console
	CONSOLE_SCREEN_BUFFER_INFO csbi;
        //Populate the CSBI struct with current information about the DOS Console
	GetConsoleScreenBufferInfo(hndl, &csbi);
        //this variable will receive the number of characters actually written to the console screen buffer.
	DWORD written;
        //n will hold the area (length * width) dimension of the current dos window 
        //(total number of 'cells' that occupy the current window)
	DWORD n = csbi.dwSize.X * csbi.dwCursorPosition.Y + csbi.dwCursorPosition.X + 1;
        //The next function call requires this as an argument (initialize first cursor position)	
	COORD curhome = {0,0};
        //Everything we've done so far has built up to this
        //This actually writes ' ' white spaces to the available area of the current DOS console window
	FillConsoleOutputCharacter(hndl, ' ', n, curhome, &written); 
        //Now we begin some cleanup...
        //Determine the desired bottom row of our screen (position)
	csbi.srWindow.Bottom -= csbi.srWindow.Top;
        //Determine desired top row of our screen
	csbi.srWindow.Top = 0;
        //Here we set the current size and position of a console screen buffer's window.
	SetConsoleWindowInfo(hndl, TRUE, &csbi.srWindow);
        //Move the cursor to the upper-left corner of the dos window
	SetConsoleCursorPosition(hndl, curhome);
}