Sequências de terminais virtuais de console

As sequências de terminais virtuais são sequências de caracteres de controle que podem controlar o movimento do cursor, a cor do console e outras operações quando gravadas no fluxo de saída. Sequências também podem ser recebidas no fluxo de entrada em resposta a uma sequência de informações de consulta de fluxo de saída ou como uma codificação de entrada do usuário quando o modo apropriado é definido.

Você pode usar as funções GetConsoleMode e SetConsoleMode para configurar esse comportamento. Um exemplo da maneira sugerida para habilitar comportamentos de terminal virtual está incluído no final deste documento.

O comportamento das sequências a seguir é baseado no VT100 e nas tecnologias derivadas do emulador de terminal, mais especificamente no emulador de terminal xterm. Mais informações sobre sequências terminais podem ser encontradas em http://vt100.net e em http://invisible-island.net/xterm/ctlseqs/ctlseqs.html.

Sequências de saída

As seguintes sequências de terminal são intercetadas pelo host do console quando gravadas no fluxo de saída, se o sinalizador de ENABLE_VIRTUAL_TERMINAL_PROCESSING estiver definido no identificador do buffer de tela usando a função SetConsoleMode . Observe que o sinalizador DISABLE_NEWLINE_AUTO_RETURN também pode ser útil para emular o posicionamento do cursor e o comportamento de rolagem de outros emuladores de terminal em relação aos caracteres gravados na coluna final em qualquer linha.

Posicionamento simples do cursor

Em todas as descrições a seguir, ESC é sempre o valor hexadecimal 0x1B. Não devem ser incluídos espaços nas sequências terminais. As sequências de terminais individuais podem ser divididas, em qualquer posição de caractere ou byte, em várias chamadas sequenciais para WriteFile ou WriteConsole , mas é uma prática recomendada incluir toda a sequência em uma chamada. Para um exemplo de como essas sequências são usadas na prática, veja o exemplo no final deste tópico.

A tabela a seguir descreve sequências de escape simples com um único comando de ação diretamente após o caractere ESC. Estas sequências não têm parâmetros e entram em vigor imediatamente.

Todos os comandos nesta tabela são geralmente equivalentes a chamar a API do console SetConsoleCursorPosition para colocar o cursor.

O movimento do cursor será limitado pela janela de visualização atual no buffer. A rolagem (se disponível) não ocorrerá.

Posicionamento do cursor

As tabelas a seguir abrangem sequências do tipo Control Sequence Introducer (CSI). Todas as sequências CSI começam com ESC (0x1B) seguido por [ (colchete esquerdo, 0x5B) e podem conter parâmetros de comprimento variável para especificar mais informações para cada operação. Isto será representado pela abreviatura <n>. Cada tabela abaixo é agrupada por funcionalidade com notas abaixo de cada tabela explicando como o grupo funciona.

Para todos os parâmetros, aplicam-se as seguintes regras, salvo indicação em contrário:

• <n> representa a distância a mover e é um parâmetro opcional
• Se <n> for omitido ou igual a 0, será tratado como um 1
• <n> não pode ser maior que 32.767 (valor curto máximo)
• <n> não pode ser negativo

Todos os comandos nesta seção são geralmente equivalentes a chamar a API do console SetConsoleCursorPosition .

O movimento do cursor será limitado pela janela de visualização atual no buffer. A rolagem (se disponível) não ocorrerá.

Visibilidade do cursor

Os comandos a seguir controlam a visibilidade do cursor e seu estado de piscar. As sequências DECTCEM são geralmente equivalentes a chamar a API do console SetConsoleCursorInfo para alternar a visibilidade do cursor.

Forma do cursor

Os comandos a seguir controlam e permitem a personalização da forma do cursor.

Posicionamento do Viewport

Todos os comandos nesta seção são geralmente equivalentes a chamar a API do console ScrollConsoleScreenBuffer para mover o conteúdo do buffer do console.

Atenção Os nomes dos comandos são enganosos. Scroll refere-se à direção em que o texto se move durante a operação, não à direção da janela de visualização que parece se mover.

O texto é movido começando com a linha em que o cursor está. Se o cursor estiver na linha do meio do visor, a rolagem para cima moverá a metade inferior do visor e inserirá linhas em branco na parte inferior. Rolar para baixo moveria a metade superior das linhas do visor e inseriria novas linhas na parte superior.

Também é importante notar que a rolagem para cima e para baixo também são afetadas pelas margens de rolagem. Rolar para cima e para baixo não afetará nenhuma linha fora das margens de rolagem.

O valor padrão para <n> é 1 e o valor pode ser opcionalmente omitido.

Modificação de texto

Todos os comandos nesta seção são geralmente equivalentes a chamar as APIs do console FillConsoleOutputCharacter, FillConsoleOutputAttribute e ScrollConsoleScreenBuffer para modificar o conteúdo do buffer de texto.

Para cada uma das sequências, o valor padrão para <n> se for omitido é 0.

Para os seguintes comandos, o parâmetro <n> tem 3 valores válidos:

• 0 apaga da posição atual do cursor (inclusive) para o final da linha/ecrã
• 1 apaga desde o início da linha/ecrã até à posição atual do cursor
• 2 apaga toda a linha/ecrã

Formatação de texto

Todos os comandos nesta seção são geralmente equivalentes a chamar APIs do console SetConsoleTextAttribute para ajustar a formatação de todas as gravações futuras no buffer de texto de saída do console.

Este comando é especial na medida em que a <posição n> abaixo pode aceitar entre 0 e 16 parâmetros separados por ponto-e-vírgula.

Quando nenhum parâmetro é especificado, ele é tratado da mesma forma que um único parâmetro 0.

A tabela de valores a seguir pode ser usada em <n> para representar diferentes modos de formatação.

Os modos de formatação são aplicados da esquerda para a direita. A aplicação de opções de formatação concorrentes resultará na precedência da opção mais à direita.

Para opções que especificam cores, as cores serão usadas conforme definido na tabela de cores do console, que pode ser modificada usando a API SetConsoleScreenBufferInfoEx . Se a tabela for modificada para que a posição "azul" na tabela exiba um tom RGB de vermelho, todas as chamadas para Azul de Primeiro Plano exibirão essa cor vermelha até que seja alterada de outra forma.

Cores estendidas

Alguns emuladores de terminal virtual suportam uma paleta de cores maior do que as 16 cores fornecidas pelo Console do Windows. Para essas cores estendidas, o Console do Windows escolherá a cor apropriada mais próxima da tabela de 16 cores existente para exibição. Ao contrário dos valores SGR típicos acima, os valores estendidos consumirão parâmetros adicionais após o indicador inicial, de acordo com a tabela abaixo.

*As paletas de cores 88 e 256 mantidas internamente para comparação são baseadas no emulador de terminal xterm. As tabelas de comparação/arredondamento não podem ser modificadas neste momento.

Cores da tela

O comando a seguir permite que o aplicativo defina os valores da paleta de cores da tela para qualquer valor RGB.

Os valores RGB devem ser valores hexadecimais entre 0 e ff, e separados pelo caractere de barra (por exemplo, rgb:1/24/86).

Observe que essa sequência é uma sequência OSC "Comando do sistema operacional", e não uma CSI como muitas das outras sequências listadas, e como tal começar com "\x1b]", não "\x1b[". Como sequências OSC, elas são terminadas com um String Terminator representado como <ST> e transmitido com ESC \ (0x1B 0x5C). BEL (0x7) pode ser usado em vez disso como terminador, mas a forma mais longa é preferível.

Alterações de modo

Estas são sequências que controlam os modos de entrada. Existem dois conjuntos diferentes de modos de entrada, o Modo de Teclas de Cursor e o Modo de Teclas de Teclado. O Modo de Teclas de Cursor controla as sequências que são emitidas pelas teclas de seta, bem como Home e End, enquanto o Modo de Teclas de Teclado controla as sequências emitidas pelas teclas no numpad principalmente, bem como as teclas de função.

Cada um desses modos são configurações booleanas simples – o Modo de Teclas do Cursor é Normal (padrão) ou Aplicativo, e o Modo de Teclas do Teclado é Numérico (padrão) ou Aplicativo.

Consulte as secções Teclas do cursor e Teclas de função Numpad & para obter as sequências emitidas nestes modos.

Estado da consulta

Todos os comandos nesta seção são geralmente equivalentes a chamar APIs do console Get* para recuperar informações de status sobre o estado atual do buffer do console.

Separadores

Enquanto o console do Windows tradicionalmente espera que as guias tenham exclusivamente oito caracteres de largura, os aplicativos *nix que utilizam certas sequências podem manipular onde as paradas de tabulação estão dentro das janelas do console para otimizar o movimento do cursor pelo aplicativo.

As sequências a seguir permitem que um aplicativo defina os locais de parada de tabulação na janela do console, remova-os e navegue entre eles.

• Para CHT e CBT, <n> é um parâmetro opcional que (padrão=1) indica quantas vezes o cursor deve avançar na direção especificada.
• Se não houver paradas de tabulação definidas via HTS, CHT e CBT tratarão a primeira e a última colunas da janela como as duas únicas paradas de tabulação.
• Usar HTS para definir uma parada de tabulação também fará com que o console navegue até a próxima parada de tabulação na saída de um caractere TAB (0x09, '\t'), da mesma maneira que CHT.

Designar conjunto de caracteres

As sequências a seguir permitem que um programa altere o mapeamento do conjunto de caracteres ativo. Isso permite que um programa emita caracteres ASCII de 7 bits, mas os exiba como outros glifos na própria tela do terminal. Atualmente, os dois únicos conjuntos de caracteres suportados são ASCII (padrão) e o DEC Special Graphics Character set. Consulte http://vt100.net/docs/vt220-rm/table2-4.html para obter uma lista de todos os caracteres representados pelo DEC Special Graphics Character set.

Notavelmente, o modo de desenho de linha DEC é usado para desenhar bordas em aplicativos de console. A tabela a seguir mostra o que o caractere ASCII mapeia para qual caractere de desenho de linha.

Margens de rolagem

As sequências a seguir permitem que um programa configure a "região de rolagem" da tela que é afetada pelas operações de rolagem. Este é um subconjunto das linhas que são ajustadas quando a tela rolaria, por exemplo, em um '\n' ou RI. Essas margens também afetam as linhas modificadas por Inserir linha (IL) e Excluir linha (DL), Rolar para cima (SU) e Rolar para baixo (SD).

As margens de rolagem podem ser especialmente úteis para ter uma parte da tela que não rola quando o resto da tela é preenchido, como ter uma barra de título na parte superior ou uma barra de status na parte inferior do seu aplicativo.

Para DECSTBM, há dois parâmetros opcionais, <t> e <b>, que são usados para especificar as linhas que representam as linhas superiores e inferiores da região de rolagem, inclusive. Se os parâmetros forem omitidos, <t> assume como padrão 1 e <b> como padrão a altura atual da janela de visualização.

As margens de rolagem são por buffer, tão importante, o Buffer Alternativo e o Buffer Principal mantêm configurações de margens de rolagem separadas (portanto, um aplicativo de tela cheia no buffer alternativo não envenenará as margens do buffer principal).

Título da janela

Os comandos a seguir permitem que o aplicativo defina o título da janela do console para o parâmetro string> fornecido<. A cadeia de caracteres deve ter menos de 255 caracteres para ser aceita. Isso equivale a chamar SetConsoleTitle com a cadeia de caracteres fornecida.

Observe que essas sequências são sequências OSC "Comando do sistema operacional", e não um CSI como muitas das outras sequências listadas, e como tal começa com "\x1b]", não "\x1b[". Como sequências OSC, elas são terminadas com um String Terminator representado como <ST> e transmitido com ESC \ (0x1B 0x5C). BEL (0x7) pode ser usado em vez disso como terminador, mas a forma mais longa é preferível.

O caractere final aqui é o caractere "Bell", '\x07'

Buffer de tela alternativo

*Os aplicativos estilo Nix geralmente utilizam um buffer de tela alternativo, para que possam modificar todo o conteúdo do buffer, sem afetar o aplicativo que os iniciou. O buffer alternativo é exatamente as dimensões da janela, sem qualquer região de scrollback.

Para obter um exemplo desse comportamento, considere quando o vim é iniciado a partir do bash. O Vim usa a totalidade da tela para editar o arquivo e, em seguida, retornar ao bash deixa o buffer original inalterado.

Largura da janela

As sequências a seguir podem ser usadas para controlar a largura da janela do console. Eles são aproximadamente equivalentes à chamada da API do console SetConsoleScreenBufferInfoEx para definir a largura da janela.

Reposição suave

A sequência a seguir pode ser usada para redefinir determinadas propriedades para seus valores padrão. As propriedades a seguir são redefinidas para os seguintes valores padrão (também listadas são as sequências que controlam essas propriedades):

• Visibilidade do cursor: visível (DECTEM)
• Teclado numérico: Modo numérico (DECNKM)
• Modo de teclas do cursor: Modo normal (DECCKM)
• Margens superior e inferior: superior=1, inferior=altura do console (DECSTBM)
• Conjunto de caracteres: US ASCII
• Representação gráfica: Default/Off (SGR)
• Guardar estado do cursor: Posição inicial (0,0) (DECSC)

Sequências de entrada

As seguintes sequências de terminal são emitidas pelo host do console no fluxo de entrada se o sinalizador ENABLE_VIRTUAL_TERMINAL_INPUT estiver definido no identificador do buffer de entrada usando o sinalizador SetConsoleMode.

Existem dois modos internos que controlam quais sequências são emitidas para as teclas de entrada dadas, o Modo de Teclas de Cursor e o Modo de Teclas de Teclado. Elas são descritas na seção Alterações de modo.

Teclas do cursor

Além disso, se Ctrl for pressionado com qualquer uma dessas teclas, as seguintes sequências serão emitidas, independentemente do modo de teclas do cursor:

Numpad & Teclas de Função

Modificadores

Alt é tratado prefixando a sequência com um escape: ESC <c onde><c> é o caractere passado pelo sistema operacional. Alt+Ctrl é tratado da mesma forma, exceto que o sistema operacional terá pré-deslocado a <tecla c> para o caractere de controle apropriado que será retransmitido para o aplicativo.

Ctrl geralmente é passado exatamente como recebido do sistema. Normalmente, trata-se de um único caractere deslocado para baixo no espaço reservado do caractere de controle (0x0-0x1f). Por exemplo, Ctrl+@ (0x40) torna-se NUL (0x00), Ctrl+[ (0x5b) torna-se ESC (0x1b), etc. Algumas combinações de teclas Ctrl são tratadas especialmente de acordo com a tabela a seguir:

Amostras

Exemplo de sequências terminais SGR

O código a seguir fornece vários exemplos de formatação de texto.

#include <stdio.h>
#include <wchar.h>
#include <windows.h>

int main()
{
    // Set output mode to handle virtual terminal sequences
    HANDLE hOut = GetStdHandle(STD_OUTPUT_HANDLE);
    if (hOut == INVALID_HANDLE_VALUE)
    {
        return GetLastError();
    }

    DWORD dwMode = 0;
    if (!GetConsoleMode(hOut, &dwMode))
    {
        return GetLastError();
    }

    dwMode |= ENABLE_VIRTUAL_TERMINAL_PROCESSING;
    if (!SetConsoleMode(hOut, dwMode))
    {
        return GetLastError();
    }

    // Try some Set Graphics Rendition (SGR) terminal escape sequences
    wprintf(L"\x1b[31mThis text has a red foreground using SGR.31.\r\n");
    wprintf(L"\x1b[1mThis text has a bright (bold) red foreground using SGR.1 to affect the previous color setting.\r\n");
    wprintf(L"\x1b[mThis text has returned to default colors using SGR.0 implicitly.\r\n");
    wprintf(L"\x1b[34;46mThis text shows the foreground and background change at the same time.\r\n");
    wprintf(L"\x1b[0mThis text has returned to default colors using SGR.0 explicitly.\r\n");
    wprintf(L"\x1b[31;32;33;34;35;36;101;102;103;104;105;106;107mThis text attempts to apply many colors in the same command. Note the colors are applied from left to right so only the right-most option of foreground cyan (SGR.36) and background bright white (SGR.107) is effective.\r\n");
    wprintf(L"\x1b[39mThis text has restored the foreground color only.\r\n");
    wprintf(L"\x1b[49mThis text has restored the background color only.\r\n");

    return 0;
}

O gráfico a seguir mostra a saída do exemplo de código anterior.

Exemplo de ativação do processamento de terminal virtual

O código a seguir fornece um exemplo da maneira recomendada de habilitar o processamento de terminal virtual para um aplicativo. A intenção da amostra é demonstrar:

1. O modo existente deve sempre ser recuperado via GetConsoleMode e analisado antes de ser definido com SetConsoleMode.

2. Verificar se SetConsoleMode retorna 0 e GetLastError retorna ERROR_INVALID_PARAMETER é o mecanismo atual para determinar quando executado em um sistema de nível inferior. Um aplicativo que recebe ERROR_INVALID_PARAMETER com um dos sinalizadores de modo de console mais recentes no campo bit deve degradar o comportamento e tentar novamente.

#include <stdio.h>
#include <wchar.h>
#include <windows.h>

int main()
{
    // Set output mode to handle virtual terminal sequences
    HANDLE hOut = GetStdHandle(STD_OUTPUT_HANDLE);
    if (hOut == INVALID_HANDLE_VALUE)
    {
        return false;
    }
    HANDLE hIn = GetStdHandle(STD_INPUT_HANDLE);
    if (hIn == INVALID_HANDLE_VALUE)
    {
        return false;
    }

    DWORD dwOriginalOutMode = 0;
    DWORD dwOriginalInMode = 0;
    if (!GetConsoleMode(hOut, &dwOriginalOutMode))
    {
        return false;
    }
    if (!GetConsoleMode(hIn, &dwOriginalInMode))
    {
        return false;
    }

    DWORD dwRequestedOutModes = ENABLE_VIRTUAL_TERMINAL_PROCESSING | DISABLE_NEWLINE_AUTO_RETURN;
    DWORD dwRequestedInModes = ENABLE_VIRTUAL_TERMINAL_INPUT;

    DWORD dwOutMode = dwOriginalOutMode | dwRequestedOutModes;
    if (!SetConsoleMode(hOut, dwOutMode))
    {
        // we failed to set both modes, try to step down mode gracefully.
        dwRequestedOutModes = ENABLE_VIRTUAL_TERMINAL_PROCESSING;
        dwOutMode = dwOriginalOutMode | dwRequestedOutModes;
        if (!SetConsoleMode(hOut, dwOutMode))
        {
            // Failed to set any VT mode, can't do anything here.
            return -1;
        }
    }

    DWORD dwInMode = dwOriginalInMode | dwRequestedInModes;
    if (!SetConsoleMode(hIn, dwInMode))
    {
        // Failed to set VT input mode, can't do anything here.
        return -1;
    }

    return 0;
}

Exemplo de selecionar recursos de atualização de aniversário

O exemplo a seguir pretende ser um exemplo mais robusto de código usando uma variedade de sequências de escape para manipular o buffer, com ênfase nos recursos adicionados na Atualização de Aniversário para Windows 10.

Este exemplo usa o buffer de tela alternativo, manipulando paradas de tabulação, definindo margens de rolagem e alterando o conjunto de caracteres.

// System headers
#include <windows.h>

// Standard library C-style
#include <wchar.h>
#include <stdlib.h>
#include <stdio.h>

#define ESC "\x1b"
#define CSI "\x1b["

bool EnableVTMode()
{
    // Set output mode to handle virtual terminal sequences
    HANDLE hOut = GetStdHandle(STD_OUTPUT_HANDLE);
    if (hOut == INVALID_HANDLE_VALUE)
    {
        return false;
    }

    DWORD dwMode = 0;
    if (!GetConsoleMode(hOut, &dwMode))
    {
        return false;
    }

    dwMode |= ENABLE_VIRTUAL_TERMINAL_PROCESSING;
    if (!SetConsoleMode(hOut, dwMode))
    {
        return false;
    }
    return true;
}

void PrintVerticalBorder()
{
    printf(ESC "(0"); // Enter Line drawing mode
    printf(CSI "104;93m"); // bright yellow on bright blue
    printf("x"); // in line drawing mode, \x78 -> \u2502 "Vertical Bar"
    printf(CSI "0m"); // restore color
    printf(ESC "(B"); // exit line drawing mode
}

void PrintHorizontalBorder(COORD const Size, bool fIsTop)
{
    printf(ESC "(0"); // Enter Line drawing mode
    printf(CSI "104;93m"); // Make the border bright yellow on bright blue
    printf(fIsTop ? "l" : "m"); // print left corner 

    for (int i = 1; i < Size.X - 1; i++)
        printf("q"); // in line drawing mode, \x71 -> \u2500 "HORIZONTAL SCAN LINE-5"

    printf(fIsTop ? "k" : "j"); // print right corner
    printf(CSI "0m");
    printf(ESC "(B"); // exit line drawing mode
}

void PrintStatusLine(const char* const pszMessage, COORD const Size)
{
    printf(CSI "%d;1H", Size.Y);
    printf(CSI "K"); // clear the line
    printf(pszMessage);
}

int __cdecl wmain(int argc, WCHAR* argv[])
{
    argc; // unused
    argv; // unused
    //First, enable VT mode
    bool fSuccess = EnableVTMode();
    if (!fSuccess)
    {
        printf("Unable to enter VT processing mode. Quitting.\n");
        return -1;
    }
    HANDLE hOut = GetStdHandle(STD_OUTPUT_HANDLE);
    if (hOut == INVALID_HANDLE_VALUE)
    {
        printf("Couldn't get the console handle. Quitting.\n");
        return -1;
    }

    CONSOLE_SCREEN_BUFFER_INFO ScreenBufferInfo;
    GetConsoleScreenBufferInfo(hOut, &ScreenBufferInfo);
    COORD Size;
    Size.X = ScreenBufferInfo.srWindow.Right - ScreenBufferInfo.srWindow.Left + 1;
    Size.Y = ScreenBufferInfo.srWindow.Bottom - ScreenBufferInfo.srWindow.Top + 1;

    // Enter the alternate buffer
    printf(CSI "?1049h");

    // Clear screen, tab stops, set, stop at columns 16, 32
    printf(CSI "1;1H");
    printf(CSI "2J"); // Clear screen

    int iNumTabStops = 4; // (0, 20, 40, width)
    printf(CSI "3g"); // clear all tab stops
    printf(CSI "1;20H"); // Move to column 20
    printf(ESC "H"); // set a tab stop

    printf(CSI "1;40H"); // Move to column 40
    printf(ESC "H"); // set a tab stop

    // Set scrolling margins to 3, h-2
    printf(CSI "3;%dr", Size.Y - 2);
    int iNumLines = Size.Y - 4;

    printf(CSI "1;1H");
    printf(CSI "102;30m");
    printf("Windows 10 Anniversary Update - VT Example");
    printf(CSI "0m");

    // Print a top border - Yellow
    printf(CSI "2;1H");
    PrintHorizontalBorder(Size, true);

    // // Print a bottom border
    printf(CSI "%d;1H", Size.Y - 1);
    PrintHorizontalBorder(Size, false);

    wchar_t wch;

    // draw columns
    printf(CSI "3;1H");
    int line = 0;
    for (line = 0; line < iNumLines * iNumTabStops; line++)
    {
        PrintVerticalBorder();
        if (line + 1 != iNumLines * iNumTabStops) // don't advance to next line if this is the last line
            printf("\t"); // advance to next tab stop

    }

    PrintStatusLine("Press any key to see text printed between tab stops.", Size);
    wch = _getwch();

    // Fill columns with output
    printf(CSI "3;1H");
    for (line = 0; line < iNumLines; line++)
    {
        int tab = 0;
        for (tab = 0; tab < iNumTabStops - 1; tab++)
        {
            PrintVerticalBorder();
            printf("line=%d", line);
            printf("\t"); // advance to next tab stop
        }
        PrintVerticalBorder();// print border at right side
        if (line + 1 != iNumLines)
            printf("\t"); // advance to next tab stop, (on the next line)
    }

    PrintStatusLine("Press any key to demonstrate scroll margins", Size);
    wch = _getwch();

    printf(CSI "3;1H");
    for (line = 0; line < iNumLines * 2; line++)
    {
        printf(CSI "K"); // clear the line
        int tab = 0;
        for (tab = 0; tab < iNumTabStops - 1; tab++)
        {
            PrintVerticalBorder();
            printf("line=%d", line);
            printf("\t"); // advance to next tab stop
        }
        PrintVerticalBorder(); // print border at right side
        if (line + 1 != iNumLines * 2)
        {
            printf("\n"); //Advance to next line. If we're at the bottom of the margins, the text will scroll.
            printf("\r"); //return to first col in buffer
        }
    }

    PrintStatusLine("Press any key to exit", Size);
    wch = _getwch();

    // Exit the alternate buffer
    printf(CSI "?1049l");

}