Функция ScrollConsoleScreenBuffer

Статья
12/13/2023

Важно!

В этом документе описаны функции платформы консоли, которые больше не являются частью стратегии развития экосистемы. Мы не рекомендуем использовать это содержимое в новых продуктах, но мы будем продолжать поддерживать существующие использования для неопределенного будущего. Наше предпочтительное современное решение ориентировано на последовательности виртуальных терминалов для обеспечения максимальной совместимости в кроссплатформенных сценариях. Дополнительные сведения об этом решении по проектированию можно найти в классической консоли и в документе виртуального терминала .

Перемещает блок данных в буфере экрана. Эффекты перемещения могут быть ограничены путем указания вырезки прямоугольника, поэтому содержимое буфера экрана консоли за пределами прямоугольника вырезки не изменяется.

Синтаксис

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 [ввод]
Дескриптор буфера экрана консоли. Этот дескриптор должен иметь право доступа GENERIC_READ. Дополнительные сведения см. в статье Безопасность и права доступа для буфера консоли.

lpScrollRectangle [in]
Указатель на структуру SMALL_RECT , члены которой указывают координаты прямоугольника буфера экрана консоли в верхнем левом и правом нижнем углу.

lpClipRectangle [in, необязательный]
Указатель на структуру SMALL_RECT , члены которой указывают координаты левого верхнего и нижнего левого угла прямоугольника буфера экрана консоли, на который влияет прокрутка. Этот указатель может иметь значение NULL.

dwDestinationOrigin [in]
Структура COORD, указывающая левый верхний угол нового расположения содержимого lpScrollRectangle в символах.

lpFill [in]
Указатель на структуру CHAR_INFO, указывающую атрибуты символа и цвета, которые будут использоваться в заполнении ячеек в пересечении lpScrollRectangle и lpClipRectangle, которые были оставлены пустыми в результате перемещения.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Замечания

ScrollConsoleScreenBuffer копирует содержимое прямоугольной области буфера экрана, указанного параметром lpScrollRectangle , в другую область буфера экрана консоли. Целевой прямоугольник имеет те же измерения, что и прямоугольник lpScrollRectangle с верхним левым углом в координатах, указанных параметром dwDestinationOrigin . Эти части lpScrollRectangle , которые не перекрываются с целевым прямоугольником, заполняются атрибутами символа и цвета, заданными параметром lpFill .

Прямоугольник обрезки применяется к изменениям, внесенным как в прямоугольник lpScrollRectangle, так и к целевому прямоугольнику. Например, если прямоугольник вырезки не включает область, заполненную содержимым lpFill, исходное содержимое региона остается неизменным.

Если области прокрутки или целевые области выходят за рамки буфера экрана консоли, они обрезаются. Например, если lpScrollRectangle — это регион, содержащийся (0,0) и (19,19) и dwDestinationOrigin (10,15), целевой прямоугольник — это регион, содержащийся (10 15) и (29 34). Тем не менее, если буфер экрана консоли имеет 50 символов ширины и 30 символов высокого уровня, целевой прямоугольник обрезается (10 15) и (29 29 29). Изменения буфера экрана консоли также обрезаются в соответствии с lpClipRectangle, если параметр задает SMALL_RECT структуру. Если прямоугольник вырезки указан как (0,0) и (49 19), вносятся только изменения, происходящие в этом регионе буфера экрана консоли.

Эта функция использует либо символы Юникода, либо 8-разрядные символы из текущей кодовой страницы консоли. Кодовая страница консоли по умолчанию изначально соответствует кодовой странице OEM системы. Чтобы изменить кодовую страницу консоли, используйте функции SetConsoleCP или SetConsoleOutputCP. Пользователи прежних версий могут также использовать команды chcp или mode con cp select= (но это не рекомендуется для новой разработки).

Совет

Этот API не рекомендуется и не имеет эквивалента виртуального терминала . С помощью полей прокрутки можно определить область экрана, положение курсора, чтобы задать активную позицию за пределами региона, а также новые строки для принудительного перемещения текста. Оставшееся пространство можно заполнить, переместив курсор, задав графические атрибуты и написав обычный текст.

Примеры

Пример см. в разделе "Прокрутка содержимого буфера экрана".

Requirements


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Верхний колонтитул	ConsoleApi2.h (через WinCon.h, включая Windows.h)
Библиотека	Kernel32.lib
DLL-библиотеки	Kernel32.dll
Имена Юникода и ANSI	ScrollConsoleScreenBufferW (Юникод) и ScrollConsoleScreenBufferA (ANSI)