Функция WriteConsoleOutput
Важно!
В этом документе описаны функции платформы консоли, которые больше не являются частью стратегии развития экосистемы. Мы не рекомендуем использовать это содержимое в новых продуктах, но мы будем продолжать поддерживать существующие использования для неопределенного будущего. Наше предпочтительное современное решение ориентировано на последовательности виртуальных терминалов для обеспечения максимальной совместимости в кроссплатформенных сценариях. Дополнительные сведения об этом решении по проектированию можно найти в классической консоли и в документе виртуального терминала .
Записывает данные символов и атрибутов цвета в указанный прямоугольный блок ячеек символов в буфере экрана консоли. Данные, записанные, взяты из соответствующего прямоугольного блока размера в указанном расположении в исходном буфере.
Синтаксис
BOOL WINAPI WriteConsoleOutput(
_In_ HANDLE hConsoleOutput,
_In_ const CHAR_INFO *lpBuffer,
_In_ COORD dwBufferSize,
_In_ COORD dwBufferCoord,
_Inout_ PSMALL_RECT lpWriteRegion
);
Параметры
hConsoleOutput [ввод]
Дескриптор буфера экрана консоли. У дескриптора должно быть право на доступ GENERIC_WRITE. Дополнительные сведения см. в статье Безопасность и права доступа для буфера консоли.
lpBuffer [ввод]
Данные, записываемые в буфер экрана консоли. Этот указатель рассматривается как источник двухмерного массива CHAR_INFO структур, размер которого задается параметром dwBufferSize.
dwBufferSize [in]
Размер буфера, на который указывает параметр lpBuffer , в ячейках символов. Элемент X структуры COORD — это количество столбцов; элемент Y — это число строк.
dwBufferCoord [in]
Координаты левой верхней ячейки в буфере, на которую указывает параметр lpBuffer . Элемент X структуры COORD — это столбец, а элемент Y — строка.
lpWriteRegion [in, out]
Указатель на структуру SMALL_RECT . Во входных данных члены структуры указывают координаты прямоугольника буфера экрана консоли в левом верхнем и нижнем углу для записи. В выходных данных члены структуры указывают фактический прямоугольник, который использовался.
Возвращаемое значение
Если функция выполняется успешно, возвращается ненулевое значение.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Замечания
WriteConsoleOutput обрабатывает исходный буфер и буфер целевого экрана как двухмерные массивы (столбцы и строки символьных ячеек). Прямоугольник, на который указывает параметр lpWriteRegion , указывает размер и расположение блока, записываемого в буфер экрана консоли. Прямоугольник того же размера расположен с левой верхней ячейкой в координатах параметра dwBufferCoord в массиве lpBufferCoord . Данные из ячеек, которые находятся на пересечении этого прямоугольника и прямоугольника исходного буфера (измерения которых указаны параметром dwBufferSize ) записываются в прямоугольник назначения.
Ячейки в прямоугольнике назначения, соответствующее исходное расположение которых находится вне границ исходного прямоугольника буфера, остаются не затронуты операцией записи. Другими словами, это ячейки, для которых данные не доступны для записи.
Перед возвратом WriteConsoleOutput он задает элементы lpWriteRegion фактическим прямоугольником буфера экрана, затронутым операцией записи. Этот прямоугольник отражает ячейки в целевом прямоугольнике, для которого существовала соответствующая ячейка в исходном буфере, так как WriteConsoleOutput обрезает размеры целевого прямоугольника к границам буфера экрана консоли.
Если прямоугольник, указанный lpWriteRegion , находится полностью за пределами буфера экрана консоли или если соответствующий прямоугольник находится полностью за пределами исходного буфера, данные не записываются. В этом случае функция возвращается с элементами структуры, на которую указывает параметр lpWriteRegion, таким образом, чтоправый элемент меньше левого или нижнего элемента меньше верхнего. Чтобы определить размер буфера экрана консоли, используйте функцию GetConsoleScreenBufferInfo .
WriteConsoleOutput не влияет на положение курсора.
Эта функция использует либо символы Юникода, либо 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 | WriteConsoleOutputW (Юникод) и WriteConsoleOutputA (ANSI) |