17.3.14 Writing Strings of Characters to a Screen Buffer

A program can write individual characters or strings to the screen at the current cursor location using the WriteFile call as described above in the section on File functions. Using the Console functions, you can write characters or attributes at specified character cells in the screen buffer. WriteConsoleOutputCharacter writes a specified number of ASCII or UNICODE characters from the caller's buffer to a specified location in the screen buffer. For example, the following code fragment writes a string of characters beginning at row 25, column 30 of the screen buffer.

HANDLE hOutput;

CHAR CharString[] = "Character String";

DWORD dwCharsWritten;

BOOL bSuccess;

COORD Coord;

Coord.X = 30;

Coord.Y = 25;

bSuccess = WriteConsoleOutputCharacter(hOutput,

CharString,

strlen(CharString),

Coord,

&dwCharsWritten

);

The coordinates specify the location of the character string in the screen buffer. The actual location in the console window at which these characters would be written depends on the current window origin. For a discussion of the window origin, refer to the section below on scrolling the screen buffer.

You can write the same ASCII or UNICODE character to the screen repeatedly by calling FillConsoleOutputCharacter. For example, the following code fragment clears a 25 x 80 screen buffer:

HANDLE hOutput;

BOOL bSuccess;

DWORD dwCharsWritten;

COORD Coord;

Coord.X = 0; // start at 0,0

Coord.Y = 0;

bSuccess = FillConsoleOutputCharacter(hOutput,

' ', // fill with blanks

80*25, // number of chars

Coord, // starting coords

&dwCharsWritten

);

In any of the calls that write characters or attributes to consecutive screen buffer cells, writing wraps around to the beginning of the next row when the end of the current screen buffer row is encountered. This occurs regardless of the state of the wrap at EOL output mode. When the end of the last row of the screen buffer is encountered, all characters or attributes remaining to be written are discarded.