ScrollConsoleScreenBuffer

  BOOL ScrollConsoleScreenBuffer(hConsoleOutput, psrctScrollRect, psrctClipRect, coordDestOrigin, pchiFill)    
  HANDLE hConsoleOutput; /* identifies screen buffer to scroll */
  PSMALL_RECT psrctScrollRect; /* rect within screen buffer to move */
  PSMALL_RECT psrctClipRect; /* affected rect within screen buffer */
  COORD coordDestOrigin; /* new location of psrctScrollRect */
  PCAR_INFO pchiFill; /* character and color attributes to use */

The ScrollConsoleScreenBuffer function is used to move a block of data within a console screen buffer. The effects of the move can be limited by specifying an optional clipping rectangle, so that the contents of the screen buffer outside the clipping rectangle are unchanged.

Parameters

hConsoleOutput

Specifies an open handle with GENERIC_WRITE access to a console screen buffer.

psrctScrollRect

Points to a SMALL_RECT structure whose members specify the upper-left and lower-right coordinates of the screen buffer rectangle to be moved.

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;

psrctClipRect

Points to a SMALL_RECT structure whose members specify the upper-left and lower-right coordinates of the screen buffer rectangle that may be affected by this scroll. This pointer may be NULL.

coordDestOrigin

Upper-left corner of new location of psrctScrollRect contents.

pchiFill

Points to a CHAR_INFO structure that specifies the character and color attributes to be used in filling the cells within the intersection of psrctScrollRect and psrctClipRect that were left empty as a result of the move.

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;

Return Value

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

Comments

This function copies the contents of a rectangular region of the screen buffer, psrctScrollRect, to another area of the screen buffer. The target is a rectangle with the same dimensions as psrctScrollRect with its upper-left corner at coordDestOrigin. Those parts of the original ScrollRect that do not overlap with the target rectangle are filled in with the character and attributes specified in pchiFill.

The optional clipping rectangle applies to changes made in both the original ScrollRect and the target rectangle. For example, if the clipping rectangle does not include a region that would have been filled by the contents of pchiFill, the original contents of the region are left unchanged.

If the scroll or target regions extend beyond the dimensions of the screen buffer, they are clipped. For example, if psrctScrollRect is the region contained by (0,0) and (19,19) and DestinationOrigin is (10,15), the target rectangle is the region contained by (10,15) and (29,34). But if the screen buffer is 50 cells wide and 30 cells high, the target rectangle is clipped to (10,15) and (29,29). The changes to the screen buffer are also clipped per the psrctClipRect, if one is specified. If the clip rectangle is specified as (0,0) and (49,19), only the changes that occur in that region of the screen buffer are made.

See Also

SetConsoleWindowInfo