ScrollConsoleScreenBuffer 함수

아티클
07/12/2023

Important

이 문서에서는 더 이상 에코시스템 로드맵의 일부가 되지 않는 콘솔 플랫폼 기능에 대해 설명합니다. 이 콘텐츠를 신제품에서 사용하지 않는 것이 좋지만, 무기한 앞으로도 기존 사용을 계속 지원할 것입니다. 선호하는 최신 솔루션은 플랫폼 간 시나리오에서 최대 호환성을 위해 가상 터미널 시퀀스에 중점을 둡니다. 이 디자인 결정에 대한 자세한 내용은 클래식 콘솔과 가상 터미널 문서에서 확인할 수 있습니다.

화면 버퍼의 데이터 블록을 이동합니다. 이동의 효과는 클리핑 사각형을 지정하여 제한될 수 있으므로 클리핑 사각형 외부의 콘솔 화면 버퍼 내용이 변경되지 않습니다.

구문

BOOL WINAPI ScrollConsoleScreenBuffer(
  _In_           HANDLE     hConsoleOutput,
  _In_     const SMALL_RECT *lpScrollRectangle,
  _In_opt_ const SMALL_RECT *lpClipRectangle,
  _In_           COORD      dwDestinationOrigin,
  _In_     const CHAR_INFO  *lpFill
);

매개 변수

hConsoleOutput [in]
콘솔 화면 버퍼에 대한 핸들입니다. 핸들에는 GENERIC_READ 액세스 권한이 있어야 합니다. 자세한 내용은 콘솔 버퍼 보안 및 액세스 권한을 참조하세요.

lpScrollRectangle [in]
멤버가 이동할 콘솔 화면 버퍼 사각형의 왼쪽 위와 오른쪽 아래 좌표를 지정하는 SMALL_RECT 구조체에 대한 포인터입니다.

lpClipRectangle [in, optional]
멤버가 스크롤의 영향을 받는 콘솔 화면 버퍼 사각형의 왼쪽 위와 오른쪽 아래 좌표를 지정하는 SMALL_RECT 구조체에 대한 포인터입니다. 이 포인터는 NULL일 수 있습니다.

dwDestinationOrigin [in]
lpScrollRectangle 콘텐츠의 새 위치의 왼쪽 위 모서리를 문자 단위로 지정하는 COORD 구조체입니다.

lpFill [in]
이동의 결과로 비어 있는 lpScrollRectangle 및 lpClipRectangle의 교차점 내에서 셀을 채우는 데 사용할 문자 및 색 특성을 지정하는 CHAR_INFO 구조체에 대한 포인터입니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

ScrollConsoleScreenBuffer는 lpScrollRectangle 매개 변수로 지정된 화면 버퍼의 사각형 영역 내용을 콘솔 화면 버퍼의 다른 영역에 복사합니다. 대상 사각형은 dwDestinationOrigin 매개 변수로 지정된 좌표에서 왼쪽 위 모서리가 있는 lpScrollRectangle 사각형과 동일한 차원을 줍니다. 대상 사각형과 겹치지 않는 lpScrollRectangle의 해당 부분은 lpFill 매개 변수에 지정된 문자 및 색 특성으로 채워집니다.

클리핑 사각형은 lpScrollRectangle 사각형과 대상 사각형 모두에서 변경된 내용에 적용됩니다. 예를 들어 클리핑 사각형에 lpFill의 내용으로 채워진 영역이 포함되지 않은 경우 해당 지역의 원래 콘텐츠는 변경되지 않은 상태로 유지됩니다.

스크롤 또는 대상 영역이 콘솔 화면 버퍼의 차원 이상으로 확장되면 잘립니다. 예를 들어 lpScrollRectangle이 (0,0) 및 (19,19)에 포함된 지역이고 dwDestinationOrigin이(10,15)인 경우 대상 사각형은 (10,15) 및 (29,34)에 포함된 영역입니다. 그러나 콘솔 화면 버퍼의 너비가 50자이고 높이가 30자인 경우 대상 사각형은 (10,15) 및 (29,29)로 잘립니다. 매개 변수가 SMALL_RECT 구조를 지정하는 경우 콘솔 화면 버퍼에 대한 변경 내용도 lpClipRectangle에 따라 잘립니다. 클리핑 사각형이 (0,0) 및 (49,19)로 지정된 경우 콘솔 화면 버퍼의 해당 영역에서 발생하는 변경 내용만 수행됩니다.

이 함수는 콘솔의 현재 코드 페이지에서 유니코드 문자 또는 8비트 문자를 사용합니다. 콘솔의 코드 페이지는 처음에 기본적으로 시스템의 OEM 코드 페이지로 설정됩니다. 콘솔의 코드 페이지를 변경하려면 SetConsoleCP 또는 SetConsoleOutputCP 함수를 사용합니다. 레거시 소비자는 chcp 또는 mode con cp select= 명령을 사용할 수도 있지만 새로운 개발에는 추천되지 않습니다.

팁

이 API는 권장되지 않으며 해당하는 가상 터미널이 없습니다. 스크롤 여백을 사용하여 화면 영역을 수정하고, 커서 위치를 지정하여 영역 외부의 활성 위치를 설정하고, 줄 바꿈을 사용하여 텍스트를 강제로 이동할 수 있습니다. 커서를 이동하고 그래픽 특성을 설정하고 일반 텍스트를 작성하여 다시 기본 공간을 채울 수 있습니다.

예제

예를 들어 화면 버퍼의 내용 스크롤을 참조 하세요.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
헤더	ConsoleApi2.h(WinCon.h를 통해 Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll
유니코드 및 ANSI 이름	ScrollConsoleScreenBufferW (유니코드) 및 ScrollConsoleScreenBufferA (ANSI)