Последовательности виртуального терминала в консоли

Последовательности виртуальных терминалов — это последовательности символов управления, которые могут управлять перемещением курсора, цветом консоли и другими операциями при записи в выходной поток. Последовательности можно также получить из входного потока в ответ на последовательность сведений запроса потока вывода или в виде кодировки входных данных пользователя (если установлен соответствующий режим).

Для настройки такого поведения можно использовать функции GetConsoleMode и SetConsoleMode. В конце этого документа приведен пример предлагаемого способа включения поведения виртуальных терминалов.

Поведение следующих последовательностей основано на VT100 и производных технологиях эмулятора терминала, в частности эмулятора терминала xterm. Дополнительные сведения о последовательностях терминала можно найти по адресу http://vt100.net и http://invisible-island.net/xterm/ctlseqs/ctlseqs.html.

Выходные последовательности

Следующие последовательности терминалов перехватываются узлом консоли при записи в выходной поток, если флаг ENABLE_VIRTUAL_TERMINAL_PROCESSING установлен в дескриптор буфера экрана с помощью функции SetConsoleMode. Обратите внимание, что флаг DISABLE_NEWLINE_AUTO_RETURN также может оказаться полезным для эмулирования расположения курсора и прокрутки других эмуляторов терминала в отношении символов, записанных в последний столбец в любой строке.

Простое позиционирование курсора

Во всех следующих описаниях ESC всегда имеет шестнадцатеричное значение 0x1B. В последовательностях терминала не должно быть пробелов. Отдельные последовательности терминалов могут быть разделены по любому символу или байтам по нескольким последовательным вызовам WriteFile или WriteConsole, но рекомендуется включить всю последовательность в один вызов. Чтобы узнать, как использовать эти последовательности на практике, ознакомьтесь с примером в конце этой статьи.

В следующей таблице описаны простые escape-последовательности с одной командой действия непосредственно после символа ESC. Эти последовательности не имеют параметров и вступают в силу немедленно.

Все команды в этой таблице обычно эквивалентны вызову API консоли SetConsoleCursorPosition для размещения курсора.

Перемещение курсора будет ограничено текущим окном просмотра в буфере. Прокрутка (если доступна) не будет выполняться.

Позиционирование курсора

В указанных ниже таблицах приведены последовательности типа CSI (начала управляющей последовательности). Все последовательности CSI начинаются с ESC (0x1B), за которым следует [ (левая скобка, 0x5B) и могут содержать параметры переменной длины, чтобы указать дополнительные сведения для каждой операции. Это будет представлено в виде сокращения <n>. Каждая таблица ниже сгруппирована по функциональности. Ниже таблицы указаны примечания, объясняющие, как работает эта группа.

Для всех параметров применяются следующие правила, если не указано иное:

• <n> представляет расстояние для перемещения и является необязательным параметром;
• если параметр <n> опущен или равен 0, он будет рассматриваться как 1;
• <n> не может превышать 32 767 (максимальное короткое значение);
• <n> не может быть отрицательным.

Все команды в этом разделе обычно эквивалентны вызову API консоли SetConsoleCursorPosition.

Перемещение курсора будет ограничено текущим окном просмотра в буфере. Прокрутка (если доступна) не будет выполняться.

Видимость курсора

Следующие команды управляют видимостью курсора и его мигающим состоянием. Последовательности DECTCEM обычно эквивалентны вызову API консоли SetConsoleCursorInfo для переключения видимости курсора.

Фигура курсора

Следующие команды управляют и позволяют настраивать фигуру курсора.

Позиционирование окна просмотра

Все команды в этом разделе обычно эквивалентны вызову API консоли ScrollConsoleScreenBuffer для перемещения содержимого буфера консоли.

Внимание! Имена команд недостоверны. Прокрутка — это направление, в котором текст перемещается во время операции, а не возможное направление перемещения окна просмотра.

Текст перемещается, начиная со строки, в которой расположен курсор. Если курсор находится в средней строке окна просмотра, то прокрутка вверх приведет к перемещению нижней половины окна просмотра и вставке пустых строк в нижней части. Прокрутка вниз приведет к перемещению верхней половины строк окна просмотра и вставке новых строк в верхней части.

Кроме того, обратите внимание, что прокрутка вверх и вниз также влияет на поля прокрутки. Прокрутка вверх и вниз не влияет на строки за пределами полей прокрутки.

Значение по умолчанию для <n> равно 1 (его можно опустить).

Изменение текста

Все команды в этом разделе обычно эквивалентны вызову API-интерфейсов консоли FillConsoleOutputCharacter, FillConsoleOutputAttribute и ScrollConsoleScreenBuffer для изменения содержимого буфера текста.

Значение по умолчанию для <n> для каждой последовательности равно 0 (если оно опущено).

Для следующих команд параметр <n> имеет три допустимых значения:

• 0 — очищает все данные с текущей позиции курсора (включительно) до конца строки или экрана;
• 1 — очищает все данные с начала строки или экрана до текущей позиции курсора (включительно);
• 2 — очищает всю строку или экран.

Форматирование текста

Все команды в этом разделе обычно эквивалентны вызову API консоли SetConsoleTextAttribute для изменения форматирования всех будущих операций записи в буфер текста, выводимого на консоль.

Отличие этой команды заключается в том, что позиция <n>, указанная ниже, может принимать от 0 до 16 параметров, разделенных точкой с запятой.

Если параметры не указаны, все они обрабатываются как единственный параметр 0.

Указанная ниже таблица значений может использоваться для <n>, чтобы отобразить различные режимы форматирования.

Режимы форматирования применяются слева направо. Если применить конкурирующие параметры форматирования, крайний правый параметр будет приоритетным.

Для параметров, задающих цвета, будут использованы цвета, указанные в таблице цветов консоли, которую можно изменить с помощью API SetConsoleScreenBufferInfoEx. Если таблица изменена так, что "синяя" позиция в таблице отображает оттенок красного цвета RGB, то все вызовы синего цвета переднего плана будут отображать этот красный цвет до тех пор, пока не будет указано иное.

Дополнительные цвета

Некоторые эмуляторы виртуального терминала поддерживают палитру, превышающую 16 цветов, которые предоставляет консоль Windows. Для этих дополнительных цветов консоль Windows выберет ближайший подходящий цвет из существующей 16-цветной таблицы для отображения. В отличие от приведенных выше стандартных значений SGR, после первоначального обозначения дополнительные значения будут использовать дополнительные параметры в соответствии с таблицей ниже.

*Палитры цветов 88 и 256, поддерживаемые внутренне для сравнения, основаны на эмуляторе терминала xterm. В настоящее время невозможно изменить таблицы сравнения/округления.

Цвета экрана

Приведенная ниже команда позволяет приложению установить для значения палитры цветов экрана любое значение RGB.

Значения RGB должны быть в шестнадцатеричном формате в диапазоне от 0 до ff и разделяться символом косой черты (например, rgb:1/24/86).

Обратите внимание, что эта последовательность является последовательностью OSC "Команда операционной системы", а не CSI, как и многие другие последовательности, перечисленные, и как таковое, начинается с "\x1b], а не "\x1b[". Как последовательности OSC, они заканчиваются строковым терминатором, представленным как <ST> и передаваемые с ESC \ (0x1B 0x5C). Вместо признака конца строки можно использовать BEL (0x7), но рекомендуется использовать более длинную форму.

Изменения режима

Существуют последовательности, управляющие режимами ввода. Существует два разных набора режимов ввода: режим клавиш курсора и режим клавиш дополнительной клавиатуры. Режим клавиш курсора управляет последовательностями, которые сформированы клавишами со стрелками, а также клавишами Home и End. Режим клавиш дополнительной клавиатуры управляет в основном последовательностями, созданными клавишами цифровой клавиатуры, а также функциональными клавишами.

Каждый из этих режимов представляет собой простые логические параметры: режим клавиш курсора — "Обычный" (по умолчанию) или "Приложение", а режим клавиш дополнительной клавиатуры — "Числовой" (по умолчанию) или "Приложение".

Последовательности, созданные в этих режимах, см. в разделах о клавишах курсора и о цифровых и функциональных клавишах.

Состояние запроса

Все команды в этом разделе обычно эквивалентны вызову API консоли Get* для получения сведений о состоянии текущего состояния буфера консоли.

Символы табуляции

Хотя консоль Windows традиционно ожидает, что вкладки будут исключительно восемь символов широкими, *nix приложения, использующие определенные последовательности, могут управлять тем, где остановки вкладок находятся в окнах консоли для оптимизации перемещения курсора приложением.

Следующие последовательности позволяют приложению задавать расположения позиции табуляции в окне консоли, удалять их, а также перемещаться между ними.

• Для CHT и CBT <n> является необязательным параметром (по умолчанию равно 1), указывающим, сколько раз следует передвинуть курсор в указанном направлении.
• Если позиции табуляции не заданы через HTS, то CHT и CBT будут рассматривать первый и последний столбцы окна как единственные позиции табуляции.
• При использовании HTS для установки остановки табуляции консоль также приведет к переходу к следующей остановке табуляции в выходных данных символа TAB (0x09, '\t') таким же образом, как CHT.

Назначение набора символов

Следующие последовательности позволяют программе изменять сопоставление активного набора символов. Это позволяет программе выдавать 7-битные символы кодировки ASCII, но отображать их как другие глифы на экране терминала. В настоящее время единственными поддерживаемыми наборами символов являются ASCII (по умолчанию) и специальный набор графических символов в кодировке DEC. Список всех символов, представленных в наборе графических символов в кодировке DEC, см. по этому адресу http://vt100.net/docs/vt220-rm/table2-4.html.

Обратите внимание, что режим рисования линии DEC используется для очерчивания границ в консольных приложениях. В следующей таблице показано, какой символ ASCII соответствует символу рисования линии.

Поля прокрутки

Следующие последовательности позволяют программе настроить область прокрутки экрана, на которую влияют операции прокрутки. Это подмножество строк, которые настраиваются, когда экран будет прокручиваться в противном случае, например, на "\n" или RI. Эти поля также влияют на строки, измененные при выполнении операций вставки строки (IL), удаления строки (DL), прокрутки вверх (SU) и прокрутки вниз (SD).

Поля прокрутки могут особенно пригодиться для отображения части экрана, которая не прокручивается при заполнении остальной части экрана. Например, заголовок окна вверху или строка состояния в нижней части приложения.

Для DECSTBM есть два необязательных параметра: <t> и <b>. Они используются для указания строк, представляющих верхние и нижние строки области прокрутки (включительно). Если параметры не указаны, <t> по умолчанию равно 1, а <b> — текущей высоте окна просмотра.

Поля прокрутки задаются для каждого буфера, поэтому важно, чтобы альтернативный и основной буфер поддерживали отдельные параметры полей прокрутки (таким образом полноэкранное приложение в альтернативном буфере не навредит полям основного буфера).

Заголовок окна

Указанные ниже команды позволяют приложению задать для заголовка окна консоли значение указанного параметра <string>. Допустимое количество символов в строке не должно превышать 255. Это эквивалентно вызову SetConsoleTitle с заданной строкой.

Обратите внимание, что эти последовательности являются последовательностями OSC "Команда операционной системы", а не CSI, как и многие другие последовательности, перечисленные, и как это начинается с "\x1b], а не "\x1b[". Как последовательности OSC, они заканчиваются строковым терминатором, представленным как <ST> и передаваемые с ESC \ (0x1B 0x5C). Вместо признака конца строки можно использовать BEL (0x7), но рекомендуется использовать более длинную форму.

Завершающий символ здесь — символ "Колокол", "\x07"

Альтернативный буфер экрана

*Приложения стилей Nix часто используют альтернативный буфер экрана, чтобы они могли изменять все содержимое буфера, не влияя на запущенное приложение. Альтернативный буфер точно соответствует размеру окна без области обратной прокрутки.

В качестве примера такого поведения рассмотрим запуск Vim из Bash. Vim использует весь экран для редактирования файла, а затем возвращается к Bash, не затрагивая исходный буфер.

Ширина окна

Для управления шириной окна консоли можно использовать следующие последовательности. Они примерно эквивалентны вызову API консоли SetConsoleScreenBufferInfoEx для установки ширины окна.

Программный сброс

Для сброса некоторых свойств к значениям по умолчанию можно использовать указанную ниже последовательность. Следующие свойства сбрасываются к значениям по умолчанию (также перечислены последовательности, управляющие этими свойствами):

• Видимость курсора: видимый (DECTEM).
• Числовая клавиатура: числовой режим (DECNKM)
• Режим ключей курсора: обычный режим (DECCKM)
• Верхние и нижние поля: top=1, Bottom=Console height (DECS ТБ M)
• Набор символов: US ASCII
• Представление графики: по умолчанию или отключению (SGR)
• Сохранение состояния курсора: положение дома (0,0) (DECSC)

Входные последовательности

Следующие последовательности терминалов создаются узлом консоли во входном потоке, если флаг ENABLE_VIRTUAL_TERMINAL_INPUT установлен в дескриптор входного буфера с помощью флага SetConsoleMode.

Существует два внутренних режима, определяющих, какие последовательности выдаются для заданных клавиш ввода: режим клавиш курсора и режим клавиш дополнительной клавиатуры. Они подробно описаны в разделе "Изменения режима".

Клавиши курсора

Кроме того, если нажать клавишу Ctrl с любой из этих клавиш, будут выданы указанные ниже последовательности, независимо от режима клавиш курсора:

Клавиши цифровой клавиатуры и функциональные клавиши

Модификаторы

Alt обрабатывается префиксом последовательности с помощью escape-файла: ESC <c> , где <c> — символ, передаваемый операционной системой. Alt+Ctrl обрабатывается аналогичным образом, за исключением того, что у операционной системы будет предварительно сдвинута клавиша <c> на соответствующий управляющий символ, который будет передаваться в приложение.

Обычно передача Ctrl выполняется точно так же, как и при получении от системы. Обычно это один символ, который сдвинут вниз в зарезервированное пространство управляющего символа (0x0-0x1f). Например, ctrl+@ (0x40) становится NUL (0x00), CTRL+[ (0x5b) становится ESC (0x1b) и т. д. Несколько сочетаний клавиш CTRL обрабатываются специально в следующей таблице:

Примеры

Пример последовательностей терминала SGR

Следующий код содержит несколько примеров форматирования текста.

#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;
}

На следующем рисунке показаны выходные данные предыдущего примера кода.

Пример включения обработки виртуального терминала

В следующем коде приведен пример рекомендуемого способа включения обработки виртуального терминала для приложения. Цель примера — продемонстрировать, что:

1. Существующий режим всегда должен извлекаться через GetConsoleMode и анализироваться, прежде чем он будет задан с помощью SetConsoleMode.

2. Проверка того, возвращается 0 ли SetConsoleMode и GetLastError возвращает ERROR_INVALID_PARAMETER является текущим механизмом для определения при запуске в системе нижнего уровня. Приложение, получающее ERROR_INVALID_PARAMETER с одним из более новых флагов режима консоли в битовом поле, должно корректно снизить поведение и повторить попытку.

#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;
}

Пример выбора функций юбилейного обновления

Следующий пример представляет собой более надежный пример кода, использующий разнообразные escape-последовательности для работы с буфером, с акцентом на возможности, добавленные в юбилейном обновлении для Windows 10.

В этом примере используется альтернативный буфер экрана, выполняется управление позициями табуляции, установка полей прокрутки и изменение набора символов.

// 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");

}