exchanger/docs/operations/ON_SCREEN_KEYBOARD.md

Экранная клавиатура

Назначение

Владелец автомата может полностью редактировать настройки с тач-экрана без физической клавиатуры. Тап по LineEdit открывает текстовую клавиатуру, тап по внутреннему полю SpinBox — цифровую. Существующие полноэкранные клавиатуры PIN и произвольной суммы оплаты остаются отдельными сценариями и не используют этот компонент.

Возможности

Текстовая клавиатура поддерживает:

• русскую раскладку по умолчанию, включая Ё;
• английскую раскладку;
• Shift для регистра букв;
• страницу из 33 цифр и спецсимволов, в том числе знаки для локальных путей;
• пробел, очистку, удаление и перемещение каретки;
• скрытие кнопкой в правом верхнем углу.

Цифровая клавиатура содержит цифры 0–9, очистку, удаление и отдельную кнопку скрытия. Для текущих SpinBox не показываются минус и десятичный разделитель: все доступные владельцу числовые настройки являются неотрицательными целыми значениями.

При открытии нижней панели ScrollContainer поднимает активное поле выше клавиатуры. Смена раздела, повторное нажатие сервисной кнопки и выход из Settings применяют введённое значение SpinBox, скрывают клавиатуру и освобождают фокус. Валидные изменения продолжают использовать обычное автосохранение с задержкой 0,5 секунды.

Архитектура

Логика находится в src/ui/OnScreenKeyboard/:

• OnScreenKeyboardState хранит RU/EN/symbols/numeric и Shift без зависимости от Godot;
• OnScreenKeyboardView описывает обязательные ссылки на уже готовые узлы темы;
• OnScreenKeyboardController связывает поля, кнопки и прокрутку.

Контроллер использует LineEdit.InsertTextAtCaret, DeleteText, выделение и составные Unicode- символы. Для числового поля после изменения вызывается SpinBox.Apply(). Синтетические InputEventKey не отправляются, поэтому TextChanged/ValueChanged, валидация и автосохранение работают обычным путём. У обслуживаемых полей отключены VirtualKeyboardEnabled и VirtualKeyboardShowOnFocus.

В fallback-сцене панели находятся в SafeMargin/KeyboardOverlay. Внешняя тема может располагать их иначе, но обязана предоставить все 57 metadata binding-id из каталога v2. Приложение не создаёт, не перемещает и не стилизует визуальные узлы внешней сцены; их внешний вид полностью принадлежит теме и совпадает с её preview.

Проверка

Перед выпуском необходимо проверить на 720×1280:

1. ввод русского и английского текста, Shift и возврат со страницы ?123;
2. вставку в середину строки, выделение, удаление и MaxLength;
3. ввод цены, бонусов и карточных сумм через цифровую панель;
4. повторное открытие после кнопки «Скрыть»;
5. переключение между полями и вкладками;
6. закрытие Settings повторным нажатием IN8 и сохранение последнего числа;
7. одинаковую композицию fallback, preview и установленной DLC-темы.

Чистое состояние раскладок покрыто NUnit-тестами. Наличие панелей, отсутствие runtime-создания визуальных узлов и интеграционные маркеры сцены проверяются smoke-тестами.

Автоматический Godot smoke запускается из корня проекта сначала с установленной темой, затем с fallback:

$godot = "D:\Applications\Godot\Godot_v4.7.1-stable_mono_win64\Godot_v4.7.1-stable_mono_win64_console.exe"
& $godot --headless --path . tests/runtime/OnScreenKeyboardSmoke.tscn -- --mock-hardware=true
& $godot --headless --path . tests/runtime/OnScreenKeyboardSmoke.tscn -- --no-theme-dlc --mock-hardware=true

Оба запуска обязаны вывести ON_SCREEN_KEYBOARD_RUNTIME_SMOKE_OK и завершиться с кодом 0.