WriteConsoleOutput

BOOL WriteConsoleOutput(hConsoleOutput, pchiSrcBuffer, coordSrcBufferSize, coordSrcBufferCoord, psrctDestRect)
HANDLE hConsoleOutput;	/* identifies console output buffer	*/
PCHAR_INFO pchiSrcBuffer;	/* source buffer with data to write	*/
COORD coordSrcBufferSize;	/* column/row size of source buffer	*/
COORD coordSrcBufferCoord;	/* upper-left cell to write from in src	*/
PSMALL_RECT psrctDestRect;	/* screen buffer rectangle to write to	*/

The WriteConsoleOutput function writes character and color attribute data to a rectangular block of cells in a console screen buffer. The data to be written is taken from a correspondingly sized rectangular block at a specified location in the source buffer.

Parameters

hConsoleOutput

Specifies an open handle to a console screen buffer that is to be written to. The handle must have GENERIC_READ access.

pchiSrcBuffer

Points to a buffer containing the data to be written to the screen buffer. This pointer is treated as the origin of a two dimensional array of CHAR_INFO whose size is specified by coordSrcBufferSize.

The CHAR_INFO data structure has the following format:

typedef struct _CHAR_INFO { /* chi */

union {

WCHAR UnicodeChar;

CHAR AsciiChar;

} Char;

WORD Attributes;

} CHAR_INFO, *PCHAR_INFO;

coordSrcBufferSize

Specifies the size in character cells of pchiSrcBuffer. The X member of the COORD structure is the number of columns; and the Y member is the number of rows.

The COORD data structure has the following format:

typedef struct _COORD { /* coord */

SHORT X; /* horizontal coordinate */

SHORT Y; /* vertical coordinate */

} COORD, *PCOORD;

coordSrcBufferCoord

Specifies the coordinates of the upper-left cell in pchiSrcBuffer to write data from. The X member of the structure is the column, and the Y member is the row.

psrctDestRect

Points to a SMALL_RECT structure. On input the structure members specify the upper-left and lower-right coordinates of the screen buffer rectangle to write to. On output, the structure members specify the actual rectangle that was written to.

The SMALL_RECT data structure has the following format:

typedef struct _SMALL_RECT { /* srct */

SHORT Left;

SHORT Top;

SHORT Right;

SHORT Bottom;

} SMALL_RECT, *PSMALL_RECT;

Return Value

The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.

Comments

The WriteConsoleOutput function treats the source buffer and the destination screen buffer as two-dimensional arrays (columns and rows of character cells). The psrctDestRect rectangle specifies the size and location of the block to write to in the screen buffer. A rectangle of the same size is located with its upper-left cell at coordSrcBufferCoord in the pchiSrcBuffer array. Data from the cells that are in the intersection of this rectangle and the SrcBuffer rectangle (whose dimensions are specified in coordSrcBufferSize) is written to the DestRect.

Cells in the DestRect whose corresponding source location are outside the boundaries of the SrcBuffer rectangle are left unaffected by the write operation (in other words, these are the cells for which there is no data available to be written).

When the function returns, the members of psrctDestRect have been set to the actual screen buffer rectangle that was affected by the write operation. This reflects the cells in the DestRect for which there existed a corresponding cell in the SrcBuffer; and it clips the dimensions of the DestRect to the boundaries of the screen buffer.

If the rectangle specified by psrctDestRect lies completely outside the boundaries of the screen buffer, or if the corresponding rectangle is positioned completely outside the boundaries of the SrcBuffer, no data is written. In this case, the function returns with the members of psrctDestRect set such that the Right member is less than the Left, or the Bottom member is less than the Top.

The WriteConsoleOutput function has no effect on the cursor position.

The WriteConsoleOutput function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).

Example

This example illustrates how WriteConsoleOutput acts when the DestRect extends beyond the boundaries of the screen buffer.

Assume that the screen buffer is 10 rows high, 8 columns wide, and that the rectangle pointed to by psrctDestRect has its members set as follows: Left = -2, Top = 3, Right = 4, and Bottom = 6. This extends the DestRect beyond the left edge of the screen buffer. Assume that the size of the SrcBuffer is 10 rows by 8 columns (coordSrcBufferSize = (8, 10)), and that coordSrcBufferCoord is set to (0, 0).

The corresponding rectangle in the SrcBuffer from which the data is taken would be: Left = 0, Top = 0, Right = 6, and Bottom = 3. In this case, the data in the SrcBuffer rectangle Left=2, Top=0, Right=6, and Bottom=3 will be copied to the screen buffer rectangle Left=0, Top=3, Right=4, Bottom=6. The data in the SrcBuffer rectangle Left=0, Top=0, Right=2, and Bottom=3 would not be copied because it corresponds to the portion of the DestRect that is outside the screen buffer boundaries.