17.2.2 Input and Output With Console Functions

Expanded access to input and output is possible through the Console functions. Through the Console functions, the application can use a handle to StdIn to directly access the input buffer. The console input buffer consists of input records that contain information about keyboard, mouse, and window size events. The File functions discard all but the keyboard input, but the Console functions provide direct access to the input buffer so the application can receive mouse and window resize events, in addition to keyboard input. Console input modes may be manipulated to filter mouse and screen buffer size events if the application is not interested in them. It is also possible using the Console functions to write input records to the input buffer; to read input records without removing them from the input buffer; to determine the number of pending events; or to flush the input buffer.

An application controls output to the screen by manipulating the contents of one or more screen buffers, and by selecting the active screen buffer which is the one that is currently displayed. Each TEXTMODE screen buffer is a two-dimensional array of character information records. The data for each character includes the UNICODE or ASCII value of the character and an attributes field that controls the foreground and background colors in which that character is displayed. The Console functions provide direct access to TEXTMODE screen buffers to enable the following functionality:

Strings of characters or character attributes (colors) can be read from or written to any location in a screen buffer, not just at the current cursor location (ReadConsoleOutputCharacter, ReadConsoleOutputAttribute, WriteConsoleOutputCharacter, WriteConsoleOutputAttribute).

Rectangular blocks of characters and attributes can be read from or written to any location in a screen buffer (ReadConsoleOutput, WriteConsoleOutput).

Any portion of a screen buffer can be filled with a single character or character attribute (FillConsoleOutputCharacter, FillConsoleOutputAttribute).

A sub-block of a screen buffer can be copied from one part of the screen buffer to another to allow scrolling of the sub-block within the console window (ScrollConsoleScreenBuffer).

The size of a screen buffer can be queried or set, although a screen buffer cannot be made smaller than the current size of the console window (SetConsoleScreenBufferSize, GetConsoleScreenBufferInfo).

The character attributes (color) with which subsequent characters will be written can be set (SetConsoleTextAttribute).

The location, appearance, and visibility of the cursor can be queried or set (GetConsoleCursorInfo, SetConsoleCursorInfo, SetConsoleCursorPosition).

The visible portion of a screen buffer can be changed by changing the origin of the buffer with respect to the window or by changing the width and height of the window (in character cells to be displayed). This can have the effect of scrolling the contents, resizing the window, or both. (SetConsoleWindowInfo)

Applications using the Console functions always receive raw character input, regardless of the line input and processed input modes. The File functions modes that affect output to the screen (echo input, processed output, wrap at EOL output) affect only applications that use ReadFile and WriteFile. The two console modes that affect input for applications using the Console functions (mouse aware and window aware) have no affect on applications using the File functions.