Funções de saída do console de baixo nível
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.
As funções de saída de console de baixo nível oferecem acesso direto às células de caracteres de um buffer de tela. Um conjunto de funções lê ou grava em células consecutivas com início em qualquer local no buffer de tela do console. Outro conjunto de funções lê ou grava em blocos retangulares de células.
As funções a seguir leem ou gravam em um número especificado de células de caracteres consecutivas em um buffer de tela, com início em uma célula especificada.
| Função | Descrição |
|---|---|
| ReadConsoleOutputCharacter | Copia uma cadeia de caracteres Unicode ou ANSI de um buffer de tela. |
| WriteConsoleOutputCharacter | Grava uma cadeia de caracteres Unicode ou ANSI em um buffer de tela. |
| ReadConsoleOutputAttribute | Copia uma cadeia de caracteres de atributos de cor do texto e da tela de fundo de um buffer de tela. |
| WriteConsoleOutputAttribute | Grava uma cadeia de caracteres de atributos de cor do texto e da tela de fundo em um buffer de tela. |
| FillConsoleOutputCharacter | Grava um único caractere Unicode ou ANSI em um número especificado de células consecutivas em um buffer de tela. |
| FillConsoleOutputAttribute | Grava uma combinação de atributos de cor do texto e da tela de fundo em um número especificado de células consecutivas em um buffer de tela. |
Para todas essas funções, quando a última célula de uma linha é encontrada, a leitura ou gravação é quebrada para a primeira célula da próxima linha. Ao encontrar o final da última linha do buffer de tela do console, as funções de gravação descartam todos os caracteres ou atributos não gravados e as funções de leitura relatam o número de caracteres ou atributos realmente gravados.
As funções a seguir leem ou gravam em blocos retangulares de células de caracteres em um local especificado em um buffer de tela.
| Função | Descrição |
|---|---|
| ReadConsoleOutput | Copia dados de caracteres e cores de um bloco especificado de células de buffer de tela para um determinado bloco em um buffer de destino. |
| WriteConsoleOutput | Grava dados de caracteres e cores em um bloco especificado de células de buffer de tela de um determinado bloco em um buffer de origem. |
Essas funções tratam buffers de tela e buffers de origem ou destino como matrizes bidimensionais de estruturas CHAR_INFO (contendo dados de atributos de caracteres e de cores para cada célula). As funções especificam a largura e a altura do buffer de origem ou de destino, em células de caracteres, e o ponteiro para o buffer é tratado como um ponteiro para a célula de origem (0,0) da matriz bidimensional. As funções usam uma estrutura SMALL_RECT para o retângulo a ser acessado no buffer da tela do console, e as coordenadas da célula superior esquerda no buffer de origem ou de destino determinam o local do retângulo correspondente nesse buffer.
Essas funções cortam automaticamente o retângulo de buffer de tela especificado para que se mantenha dentro dos limites do buffer de tela do console. Por exemplo, se o retângulo especificar as coordenadas inferiores direitas como “coluna 100, linha 50” e o buffer de tela do console tiver somente 80 colunas de largura, as coordenadas serão cortadas para “coluna 79, linha 50”. Da mesma forma, esse retângulo ajustado é cortado outra vez para que permaneça dentro dos limites do buffer de origem ou destino. As coordenadas do buffer de tela do retângulo real que foi lido ou gravado são especificadas. Para ver um exemplo que usa essas funções, confira Ler e gravar blocos de caracteres e atributos.
A ilustração mostra uma operação ReadConsoleOutput em que o corte acontece quando o bloco é lido do buffer de tela do console e novamente quando o bloco é copiado para o buffer de destino. A função relata o retângulo de buffer de tela real do qual ele copiou.
