Função ScrollConsoleScreenBuffer
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.
Move um bloco de dados em um buffer de tela. Os efeitos da movimentação podem ser limitados por um retângulo de corte, já que o conteúdo do buffer de tela do console fora do retângulo de corte permanece inalterado.
Sintaxe
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
);
Parâmetros
hConsoleOutput [in]
Um identificador do buffer da tela do console. O identificador deve ter o direito de acesso GENERIC_READ. Para saber mais, confira Segurança de buffer e direitos de acesso do console.
lpScrollRectangle [in]
Um ponteiro para uma estrutura SMALL_RECT cujos membros especificam as coordenadas superior esquerda e inferior direita do retângulo de buffer da tela do console a ser movido.
lpClipRectangle [in, opcional]
Um ponteiro para uma estrutura SMALL_RECT cujos membros especificam as coordenadas superior esquerda e inferior direita do retângulo de buffer da tela do console afetado pela rolagem. Este ponteiro pode ser NULO.
dwDestinationOrigin [in]
Uma estrutura COORD que especifica o canto superior esquerdo do novo local do conteúdo de lpScrollRectangle, em caracteres.
lpFill [in]
Um ponteiro para uma estrutura CHAR_INFO que especifica os atributos de caracteres e de cor a serem usados no preenchimento das células na interseção de lpScrollRectangle e lpClipRectangle que ficaram vazias como resultado da movimentação.
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
ScrollConsoleScreenBuffer copia o conteúdo de uma região retangular de um buffer de tela, especificada pelo parâmetro lpScrollRectangle, para outra área do buffer de tela do console. O retângulo de destino tem as mesmas dimensões do retângulo lpScrollRectangle com seu canto superior esquerdo nas coordenadas especificadas pelo parâmetro dwDestinationOrigin. As partes de lpScrollRectangle não sobrepostas ao retângulo de destino são preenchidas com os atributos de caracteres e de cor especificados pelo parâmetro lpFill.
O retângulo de corte se aplica às alterações feitas no retângulo lpScrollRectangle e no retângulo de destino. Por exemplo, se o retângulo de corte não inclui uma região a ser preenchida pelo conteúdo de lpFill, o conteúdo original da região é mantido inalterado.
Se as regiões de rolagem ou de destino se estenderem além das dimensões do buffer de tela do console, elas serão cortadas. Por exemplo, se lpScrollRectangle é a região contida por (0,0) e (19,19) e dwDestinationOrigin é (10,15), o retângulo de destino é a região contida por (10,15) e (29,34). No entanto, se o buffer da tela do console tiver 50 caracteres de largura e 30 caracteres de altura, o retângulo de destino será cortado para (10,15) e (29,29). As alterações no buffer de tela do console também são cortadas de acordo com lpClipRectangle, se o parâmetro especificar uma estrutura SMALL_RECT. Se o retângulo de corte for especificado como (0,0) e (49,19), somente as alterações nessa região do buffer de tela do console serão feitas.
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 não é recomendada e não tem um terminal virtual equivalente. O uso pode ser aproximado com margens de rolagem para corrigir uma área da tela, posicionamento do cursor para definir a posição ativa fora da região e novas linhas para forçar o movimento do texto. O espaço que sobra pode ser preenchido pelo movimento do cursor, pela definição de atributos gráficos e pela gravação de texto normal.
Exemplos
Para obter um exemplo, consulte Rolar pelo conteúdo de um buffer de tela.
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 | ScrollConsoleScreenBufferW (Unicode) e ScrollConsoleScreenBufferA (ANSI) |