17.3.16 Writing Blocks of Characters and Attributes

WriteConsoleOutput provides another way to write characters and attributes to a screen buffer. This functions copies from the caller's buffer to a screen buffer, but the source buffer is treated as a two dimensional array rather than a string, and copying is done from a rectangular block in the source buffer to a destination block in the screen buffer. The source buffer's array elements contain both the ASCII or UNICODE character and the color attributes to be written.

A destination rectangle in the screen buffer is specified. The size of this rectangle and the coordinates of the first element in the source buffer determine the portion of the source that will be copied. Only those parts of the destination rectangle that are within the boundaries of the screen buffer can be written to. So any sections in the source buffer that correspond to the part of the destination that is outside the screen buffer boundaries are not copied. Similarly, if the source rectangle extends outside the boundaries of the source buffer, the corresponding portion of the screen buffer is not written to.

The following code fragment reads a block of characters and attributes from the top two rows of one screen buffer, and then writes them into the middle rows of another screen buffer:

HANDLE hOutput_1, hOutput_2;

SMALL_RECT ReadRegion; // region of screen buf to read from

SMALL_RECT WriteRegion; // region of screen buf to write to

CHAR_INFO Buffer[160]; // buffer to read into

COORD BufferSize; // size of buffer in character rows and cols

COORD BufferCoord; // starting row/col to read or write from

BOOL bSuccess;

// read from top rows of source screen buffer

ReadRegion.Left = 0;

ReadRegion.Right = 79;

ReadRegion.Top = 0;

ReadRegion.Bottom = 1;

BufferSize.Y = 2; // dest buffer is 2 rows x 80 columns

BufferSize.X = 80;

BufferCoord.X = 0; // read and write from first cell of buffer

BufferCoord.Y = 0;

bSuccess = ReadConsoleOutput(hOutput_1,

Buffer,

BufferSize,

BufferCoord,

&ReadRegion

);

// write from Buffer to middle rows of dest screen buffer

WriteRegion.Left = 0;

WriteRegion.Top = 10;

WriteRegion.Right = 79;

WriteRegion.Bottom = 11;

bSuccess = WriteConsoleOutput(hOutput_2,

(PCHAR_INFO) Buffer,

BufferSize,

BufferCoord,

&WriteRegion);

Note that if the destination screen buffer in this example is only 60 characters wide, the last 20 characters of the rows would be discarded. The current window size or origin does not affect writing to a screen buffer. It only determines which portion of the screen buffer is visible.