Функция FillConsoleOutputCharacter

Статья
10/23/2023

Важно!

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

Записывает символ в буфер экрана консоли указанное количество раз, начиная с указанной координаты.

Синтаксис

BOOL WINAPI FillConsoleOutputCharacter(
  _In_  HANDLE  hConsoleOutput,
  _In_  TCHAR   cCharacter,
  _In_  DWORD   nLength,
  _In_  COORD   dwWriteCoord,
  _Out_ LPDWORD lpNumberOfCharsWritten
);

Параметры

hConsoleOutput [ввод]
Дескриптор буфера экрана консоли. У дескриптора должно быть право на доступ GENERIC_WRITE. Дополнительные сведения см. в статье Безопасность и права доступа для буфера консоли.

cCharacter [in]
Символ, записываемый в буфер экрана консоли.

nLength [in]
Число ячеек символов, в которые должен быть записан символ.

dwWriteCoord [in]
Структура COORD, указывающая координаты символов первой ячейки, в которую необходимо записать символ.

lpNumberOfCharsWritten [out]
Указатель на переменную, которая получает количество символов, фактически записанных в буфер экрана консоли.

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

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

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

Замечания

Если число символов для записи выходит за пределы указанной строки в буфере экрана консоли, символы записываются в следующую строку. Если число символов для записи в буфер экрана консоли выходит за пределы буфера экрана консоли, символы записываются до конца буфера экрана консоли.

Значения атрибутов в записываемых позициях не изменяются.

Эта функция использует либо символы Юникода, либо 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	FillConsoleOutputCharacterW (Юникод) и FillConsoleOutputCharacterA (ANSI)