Função SetConsoleMode

Artigo
07/12/2023

Define o modo de entrada do buffer de entrada de um console ou o modo de saída de um buffer de tela do console.

Sintaxe

BOOL WINAPI SetConsoleMode(
  _In_ HANDLE hConsoleHandle,
  _In_ DWORD  dwMode
);

Parâmetros

hConsoleHandle [in]
Um identificador para o buffer de entrada do console ou um 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.

dwMode [in]
O modo de entrada ou saída a ser definido.

Se o parâmetro hConsoleHandle for um identificador de entrada, o modo poderá ser um ou mais dos valores a seguir. Quando um console é criado, todos os modos de entrada, exceto por ENABLE_WINDOW_INPUT e ENABLE_VIRTUAL_TERMINAL_INPUT, são habilitados por padrão.

Valor	Significado
ENABLE_ECHO_INPUT 0x0004	Os caracteres lidos pela função ReadFile ou ReadConsole são gravados no buffer de tela ativo à medida que são inseridos no console. Esse modo poderá ser usado somente se o modo ENABLE_LINE_INPUT também estiver habilitado.
ENABLE_INSERT_MODE 0x0020	Quando habilitado, o texto inserido em uma janela de console será inserido na localização do cursor atual e todo o texto após essa localização não será substituído. Quando desabilitado, todo o texto a seguir será substituído.
ENABLE_LINE_INPUT 0x0002	A função ReadFile ou ReadConsole será retornada somente quando um caractere de retorno de carro for lido. Se esse modo estiver desabilitado, as funções serão retornadas quando um ou mais caracteres estiverem disponíveis.
ENABLE_MOUSE_INPUT 0x0010	Se o ponteiro do mouse estiver dentro das bordas da janela do console e a janela tiver o foco do teclado, os eventos do mouse gerados pelo movimento do mouse e pressionamentos de botão serão colocados no buffer de entrada. Esses eventos são descartados por ReadFile ou ReadConsole, mesmo quando esse modo está habilitado. A função ReadConsoleInput pode ser usada para ler registros de entrada MOUSE_EVENT do buffer de entrada.
ENABLE_PROCESSED_INPUT 0x0001	CTRL+C é processado pelo sistema e não é colocado no buffer de entrada. Se o buffer de entrada estiver sendo lido por ReadFile ou ReadConsole, outras chaves de controle serão processadas pelo sistema e não serão retornadas no buffer ReadFile ou ReadConsole. Se o modo ENABLE_LINE_INPUT também estiver habilitado, o backspace, o retorno de carro e os caracteres de alimentação de linha serão administrados pelo sistema.
ENABLE_QUICK_EDIT_MODE 0x0040	Esse sinalizador permite que o usuário use o mouse para selecionar e editar o texto. Para habilitar esse modo, use `ENABLE_QUICK_EDIT_MODE \| ENABLE_EXTENDED_FLAGS`. Para desabilitar esse modo, use ENABLE_EXTENDED_FLAGS sem esse sinalizador.
ENABLE_WINDOW_INPUT 0x0008	As interações do usuário que alteram o tamanho do buffer da tela do console são relatadas no buffer de entrada do console. As informações sobre esses eventos podem ser lidas no buffer de entrada por aplicativos que usam a função ReadConsoleInput, mas não por aquelas que usam ReadFile ou ReadConsole.
ENABLE_VIRTUAL_TERMINAL_INPUT 0x0200	Definir esse sinalizador instrui o mecanismo de processamento do Terminal Virtual a converter a entrada do usuário recebida pela janela do console em Sequências de Terminais Virtuais do Console que podem ser recuperadas por um aplicativo de suporte por meio das funções ReadFile ou ReadConsole. O uso típico desse sinalizador é em conjunto com ENABLE_VIRTUAL_TERMINAL_PROCESSING no identificador de saída para se conectar a um aplicativo que se comunica exclusivamente por meio de sequências de terminais virtuais.

Se o parâmetro hConsoleHandle for um identificador de buffer de tela, o modo poderá ser um ou mais dos valores a seguir. Quando um buffer de tela é criado, ambos os modos de saída são habilitados por padrão.

Valor	Significado
ENABLE_PROCESSED_OUTPUT 0x0001	Os caracteres gravados pela função WriteFile ou WriteConsole ou reproduzidos pela função ReadFile ou ReadConsole são analisados para sequências de controle ASCII e a ação correta é executada. Os caracteres de backspace, de tabulação, de sino, de retorno de carro e de alimentação de linha são processados. Ele deve ser habilitado ao usar sequências de controle ou quando ENABLE_VIRTUAL_TERMINAL_PROCESSING estiver definido.
ENABLE_WRAP_AT_EOL_OUTPUT 0x0002	Ao gravar com WriteFile ou WriteConsole ou reproduzir com ReadFile ou ReadConsole, o cursor passa para o início da próxima linha quando chega ao final da linha atual. Isso faz com que as linhas exibidas na janela do console sejam roladas para cima automaticamente quando o cursor passa da última linha na janela. Isso também faz com que o conteúdo do buffer da tela do console role para cima (../descartando a linha superior do buffer da tela do console) quando o cursor passa da última linha no buffer da tela do console. Se esse modo estiver desabilitado, o último caractere na linha será substituído pelos caracteres subsequentes.
ENABLE_VIRTUAL_TERMINAL_PROCESSING 0x0004	Ao gravar com WriteFile ou WriteConsole, os caracteres são analisados para VT100 e sequências de caracteres de controle semelhantes que controlam o movimento do cursor, o modo de cor/fonte e outras operações que também podem ser executadas por meio de APIs de Console existentes. Para obter mais informações, confira Sequências de terminais virtuais do console. Verifique se ENABLE_PROCESSED_OUTPUT está definido ao usar esse sinalizador.
DISABLE_NEWLINE_AUTO_RETURN 0x0008	Ao gravar com o WriteFile ou o WriteConsole, estado adicional ao encapsulamento de fim da linha é adicionado, o que pode atrasar as operações de movimentação do cursor e de rolagem do buffer. Normalmente, quando ENABLE_WRAP_AT_EOL_OUTPUT é definido e o texto chega ao fim da linha, o cursor se moverá imediatamente para a próxima linha e o conteúdo do buffer será rolado uma linha para cima. Em contraste com esse conjunto de sinalizadores, o cursor não se move para a próxima linha, e a operação de rolagem não é executada. O caractere gravado será impresso na posição final da linha e o cursor permanecerá acima desse caractere como se o ENABLE_WRAP_AT_EOL_OUTPUT estivesse desativado, mas o próximo caractere imprimível será impresso como se ENABLE_WRAP_AT_EOL_OUTPUT estivesse ativado. Nenhuma substituição ocorrerá. Especificamente, o cursor avança rapidamente para a próxima linha, uma rolagem é executada, se necessário, o caractere é impresso e o cursor avança mais uma posição. O uso típico desse sinalizador é em conjunto com a configuração ENABLE_VIRTUAL_TERMINAL_PROCESSING a fim de simular melhor um emulador de terminal no qual gravar o caractere final na tela (../no canto inferior direito) sem disparar uma rolagem imediata é o comportamento desejado.
ENABLE_LVB_GRID_WORLDWIDE 0x0010	As APIs para gravar atributos de caractere, incluindo WriteConsoleOutput e WriteConsoleOutputAttribute permitem o uso de sinalizadores de atributos de caractere a fim de ajustar a cor do texto em primeiro plano e na tela de fundo. Além disso, um intervalo de sinalizadores DBCS foi especificado com o prefixo COMMON_LVB. Historicamente, esses sinalizadores funcionam apenas em páginas de código DBCS para os idiomas chinês, japonês e coreano. Com exceção dos sinalizadores de byte à esquerda e à direita, os sinalizadores restantes que descrevem o desenho de linha e o vídeo reverso (../alternar cores do primeiro plano e na tela de fundo) podem ser úteis em outros idiomas para enfatizar partes da saída. Definir esse sinalizador de modo de console permitirá que esses atributos sejam usados em todas as páginas de código em todos os idiomas. Ele está desativado por padrão para manter a compatibilidade com aplicativos conhecidos que têm aproveitado historicamente o console, ignorando esses sinalizadores em computadores que não são CJK para armazenar bits nesses campos para as próprias finalidades ou por acidente. Observe que o uso do modo ENABLE_VIRTUAL_TERMINAL_PROCESSING poderá fazer com que os sinalizadores de vídeo reverso e de grade LVB sejam definidos enquanto esse sinalizador ainda estiver desativado se o aplicativo anexado solicitar um vídeo reverso ou subjacente por meio do Sequências de terminais virtuais do console.

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

Um console consiste em um buffer de entrada e um ou mais buffers de tela. O modo de um buffer de console determina como o console se comporta durante as operações de E/S (entrada ou saída). Um conjunto de constantes de sinalizador é usado com identificadores de entrada e outro conjunto é usado com identificadores de buffer de tela (saída). Definir os modos de saída de um buffer de tela não afeta os modos de saída de outros buffers de tela.

Os modos ENABLE_LINE_INPUT e ENABLE_ECHO_INPUT afetam apenas processos que usam ReadFile ou ReadConsole para ler o buffer de entrada do console. De maneira semelhante, o modo ENABLE_PROCESSED_INPUT afeta principalmente usuários de ReadFile e de ReadConsole, exceto pelo fato que ele também determina se a entrada CTRL+C é relatada no buffer de entrada (a ser lido pela função ReadConsoleInput) ou é passada para uma função definida pelo aplicativo.

Os modos ENABLE_WINDOW_INPUT e ENABLE_MOUSE_INPUT determinam se as interações do usuário que envolvem o redimensionamento da janela e as ações do mouse são relatadas no buffer de entrada ou descartadas. Esses eventos podem ser lidos por ReadConsoleInput, mas são sempre filtrados por ReadFile e ReadConsole.

Os modos ENABLE_PROCESSED_OUTPUT e ENABLE_WRAP_AT_EOL_OUTPUT afetam somente processos que usam ReadFile ou ReadConsole e WriteFile ou WriteConsole.

Para determinar o modo atual de um buffer de entrada do console ou de um buffer de tela, use a função GetConsoleMode.

Exemplos

Para obter um exemplo, confira Como ler eventos de buffer de entrada.

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	ConsoleApi.h (via WinCon.h, inclui o Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll