Função WriteConsoleOutput

Artigo
12/15/2023

Importante

Este documento descreve a funcionalidade da plataforma do console que não faz mais parte do nosso roteiro de ecossistema. Não recomendamos o uso desse conteúdo em novos produtos, mas continuaremos a oferecer suporte aos usos existentes por tempo indeterminado. Nossa solução moderna preferida se concentra em sequências de terminais virtuais para máxima compatibilidade em cenários de multiplataforma. Você pode encontrar mais informações sobre essa decisão de design em nosso documento Console clássico versus terminal virtual.

Grava dados de atributo de caractere e cor em um bloco retangular especificado de células de caracteres em um buffer de tela do console. Os dados a serem gravados são retirados de um bloco retangular de tamanho correspondente em um local especificado no buffer de origem.

Sintaxe

BOOL WINAPI WriteConsoleOutput(
  _In_          HANDLE      hConsoleOutput,
  _In_    const CHAR_INFO   *lpBuffer,
  _In_          COORD       dwBufferSize,
  _In_          COORD       dwBufferCoord,
  _Inout_       PSMALL_RECT lpWriteRegion
);

Parâmetros

hConsoleOutput [in]
Um identificador do buffer da tela do console. O identificador deve ter o direito de acesso GENERIC_WRITE. Para saber mais, confira Segurança de buffer e direitos de acesso do console.

lpBuffer [in]
Os dados a serem gravados no buffer da tela do console. Esse ponteiro é tratado como a origem de uma matriz bidimensional de estruturas CHAR_INFO cujo tamanho é especificado pelo parâmetro dwBufferSize.

dwBufferSize [entrada]
O tamanho do buffer apontado pelo parâmetro lpBuffer, em células de caracteres. O membro X da estrutura COORD é o número de colunas, o membro Y é o número de linhas.

dwBufferCoord [entrada]
As coordenadas da célula superior esquerda no buffer apontadas pelo parâmetro lpBuffer. O membro X da estrutura COORD é a coluna e o membro Y é a linha.

lpWriteRegion [entrada, saída]
Um ponteiro para uma estrutura SMALL_RECT. Na entrada, os membros da estrutura especificam as coordenadas superior esquerda e inferior direita do retângulo do buffer da tela do console nas quais gravar. Na saída, os membros da estrutura especificam o retângulo real que foi usado.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

WriteConsoleOutput trata o buffer de origem e o buffer de tela de destino como matrizes bidimensionais (colunas e linhas de células de caracteres). O retângulo apontado pelo parâmetro lpWriteRegion especifica o tamanho e o local do bloco a ser gravado no buffer de tela do console. Um retângulo do mesmo tamanho está localizado com sua célula superior esquerda nas coordenadas do parâmetro dwBufferCoord na matriz lpBuffer. Os dados das células que estão na interseção desse retângulo e do retângulo do buffer de origem (cujas dimensões são especificadas pelo parâmetro dwBufferSize) são gravados no retângulo de destino.

As células no retângulo de destino cujo local de origem correspondente está fora dos limites do retângulo do buffer de origem não são afetadas pela operação de gravação. Em outras palavras, essas são as células para as quais não há dados disponíveis para gravação.

Antes do retorno de WriteConsoleOutput, ela define os membros de lpWriteRegion como o retângulo de buffer de tela real afetado pela operação de gravação. Esse retângulo reflete as células no retângulo de destino para as quais havia uma célula correspondente no buffer de origem, pois WriteConsoleOutput corta as dimensões do retângulo de destino até os limites do buffer de tela do console.

Se o retângulo especificado por lpWriteRegion estiver completamente fora dos limites do buffer de tela do console ou se o retângulo correspondente estiver posicionado totalmente fora dos limites do buffer de origem, nenhum dado será gravado. Nesse caso, a função retorna com os membros da estrutura apontados pelo conjunto de parâmetros lpWriteRegion, de forma que o membro Right seja menor que o membro Left ou que o membro Bottom seja menor que o membro Top. Para determinar o tamanho do buffer de tela do console, use a função GetConsoleScreenBufferInfo.

WriteConsoleOutput não tem efeito na posição do cursor.

Essa função usa caracteres Unicode ou caracteres de 8 bits da página de código atual do console. O padrão da página de código do console inicialmente é a página de código OEM do sistema. Para alterar a página de código do console, use as funções SetConsoleCP ou SetConsoleOutputCP. Os consumidores herdados também podem usar os comandos chcp ou mode con cp select=, mas eles não são recomendados para novos desenvolvimentos.

Dica

Essa API tem um terminal virtual equivalente nas sequeências de formatação de texto e posicionamento do cursor. Mova o cursor para o local a ser inserido, aplique a formatação desejada e escreva o texto. Sequências de terminais virtuais são recomendadas para todo o desenvolvimento novo e em andamento.

Exemplos

Para ver um exemplo, Ler e gravar blocos de caracteres e atributos.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	ConsoleApi2.h (via WinCon.h, inclui o Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll
Nomes Unicode e ANSI	WriteConsoleOutputW (Unicode) e WriteConsoleOutputA (ANSI)