Função SetConsoleWindowInfo
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.
Define o tamanho e a posição atuais da janela de um buffer de tela de console.
Sintaxe
BOOL WINAPI SetConsoleWindowInfo(
_In_ HANDLE hConsoleOutput,
_In_ BOOL bAbsolute,
_In_ const SMALL_RECT *lpConsoleWindow
);
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.
bAbsolute [entrada]
Se esse parâmetro for TRUE, as coordenadas especificarão os novos cantos superior esquerdo e inferior direito da janela. Se for FALSE, as coordenadas serão relativas às coordenadas atuais do canto da janela.
lpConsoleWindow [entrada]
Um ponteiro para uma estrutura SMALL_RECT que especifica os novos cantos superior esquerdo e inferior direito da janela.
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
A função falhará se o retângulo de janela especificado se estender além dos limites do buffer de tela do console. Isso significa que os membros Top e Left do retângulo lpConsoleWindow (ou as coordenadas superior e esquerda calculadas, se bAbsolute for FALSE) não podem ser menores que zero. Da mesma forma, os membros Bottom e Right (ou as coordenadas inferior e direita calculadas) não podem ser maiores que (altura do buffer de tela – 1) e (largura do buffer de tela – 1), respectivamente. A função também falhará se o membro Right (ou a coordenada direita calculada) for menor que ou igual ao membro Left (ou coordenada esquerda calculada) ou se o membro Bottom (ou a coordenada inferior calculada) for menor que ou igual ao membro Top (ou a coordenada superior calculada).
Para consoles com mais de um buffer de tela, alterar o local da janela para um buffer de tela não afeta os locais da janela dos outros buffers de tela.
Para determinar o tamanho e a posição atuais da janela de um buffer de tela, use a função GetConsoleScreenBufferInfo. Essa função também retorna o tamanho máximo da janela, considerando o tamanho atual do buffer de tela, o tamanho da fonte atual e o tamanho da tela. A função GetLargestConsoleWindowSize retorna o tamanho máximo da janela, considerando a fonte atual e os tamanhos de tela, mas não considera o tamanho do buffer de tela do console.
SetConsoleWindowInfo pode ser usada para rolar o conteúdo do buffer de tela do console, alterando a posição do retângulo da janela sem alterar seu tamanho.
Dica
Essa API não é recomendada e não tem um equivalente de terminal virtual. Essa decisão alinha intencionalmente a plataforma Windows com outros sistemas operacionais nos quais o usuário tem controle total sobre essa opção de apresentação. A comunicação remota de aplicativos por meio de utilitários multiplataforma e transportes como SSH pode não funcionar como esperado se estiver usando essa API.
Exemplos
Para obter um exemplo, consulte Rolagem pela janela 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 |