MAME/DEBUGGER_KEYMAP_HANDOFF.md

Handoff: переназначаемые горячие клавиши в дебаггерах MAME

Дай этот файл Claude в новой сессии (на другом компьютере) — он восстановит весь контекст задачи и сможет продолжить. Рабочая копия: /Users/tolik/Documents/GitHub/mame, ветка Vibe. Пользователь общается по-русски.

Цель

Добавить в дебаггеры MAME возможность переназначать горячие клавиши с сохранением между сессиями и UI для редактирования. Изначально просили для macOS-Cocoa-дебаггера (osd/modules/debugger/osx/), затем — «для остальных дебаггеров» в src/osd/modules/debugger/.

Статус по дебаггерам

• Cocoa (osx) — ✅ СДЕЛАНО и собиралось (отдельная реализация на Objective-C).
• ImGui (debugimgui.cpp) — ✅ СДЕЛАНО, компилируется чисто.
• Qt (debugqt.cpp + qt/) — ✅ СДЕЛАНО, компилируется чисто (с USE_QTDEBUG=1).
• Win (win/) — ⛔ ПРОПУЩЕНО по решению пользователя (нельзя собрать/проверить на macOS; нативный Win32-диалог — высокий риск вслепую). Не трогали.
• gdbstub / none — не GUI, не трогаем.

-debugger auto на macOS выбирает Cocoa (регистрируется первым, всегда инициализируется). Для проверки других: -debugger imgui -video bgfx или -debugger qt.

---

Архитектура

Общий C++-модуль (для ImGui/Qt/Win) — НОВЫЙ

• src/osd/modules/debugger/debugkeyconfig.h
• src/osd/modules/debugger/debugkeyconfig.cpp

namespace osd::debugger:

• struct key_shortcut { std::string key; bool ctrl, alt, shift; } — to_string() → "Ctrl+Shift+F9" (переносимый текст), from_string().
• struct key_action { std::string id, label, group; key_shortcut default_shortcut; }.
• class keymap_config(std::vector<key_action>&& actions) — хранит таблицу + override’ы: shortcut(id), is_default, conflicting_action, set_shortcut/clear/reset/reset_all, save(node) / load(node) (узел <keymap> с дочерними <key>).

Каждый дебаггер задаёт СВОЮ таблицу действий (id/label/group/дефолты), а хранилище, парсинг и XML — общие. Формат текстовый и единый → раскладка в default.cfg понятна всем трём (Qt↔ImGui↔Win шарят). Cocoa хранит в своём формате (codepoint+mask), с ним не пересекается — это ОК (разные id, конфликтов в файле нет).

XML-константы (общие) — в xmlconfig.h/.cpp

Добавлены: NODE_KEYMAP="keymap", NODE_KEYMAP_ITEM="key", ATTR_KEYMAP_ACTION="action", ATTR_KEYMAP_KEY="char", ATTR_KEYMAP_MODIFIERS="modifiers". (У C++-дебаггеров modifiers зашиты в текст ATTR_KEYMAP_KEY; у Cocoa — отдельные int.)

Персистентность

Все дебаггеры пишут раскладку как ГЛОБАЛЬНУЮ — в default.cfg, через config_register("debugger", …) и обработку config_type::DEFAULT (а не SYSTEM, который для позиций окон). Сохраняются только отличия от дефолтов; пустой <keymap> не пишется.

---

Что и где изменено

Cocoa (Objective-C, отдельная реализация — НЕ использует debugkeyconfig)

НОВЫЕ:

• osx/debugkeymap.h / osx/debugkeymap.mm — синглтон MAMEDebugKeyMap (реестр действий, лукапы, applyToMenuItem:forAction:, refreshMenu:, save/restore XML). Хранит unichar+mask.
• osx/debugkeymapviewer.h / osx/debugkeymapviewer.mm — окно MAMEKeyBindingsWindow (таблица + запись через локальный монитор NSEvent, конфликты, Reset All). ИЗМЕНЕНЫ:
• osx/debugwindowhandler.{h,mm} — addCommonActionItems: берёт клавиши из реестра; пункт «Customize Keys…»; showKeyBindings:; keyMapChanged: рефрешит главное меню и popup-кнопки окна; подписка на MAMEDebugKeyMapChangedNotification.
• osx/disassemblyview.mm — оба построителя меню (контекст + action-button) через реестр.
• debugosx.mm — build_menus (главное меню Debug/Run/Step) через реестр; пункт «Customize Keys…»; config_load/config_save обрабатывают DEFAULT для глобальной раскладки.
• osx/debugkeymap.h включает "../xmlconfig.h" (важно: с ../, файл в подкаталоге osx/). Идентификаторы Cocoa — camelCase ("stepInto" и т.п.).

ImGui — src/osd/modules/debugger/debugimgui.cpp

• Добавлены include debugkeyconfig.h, util/xmlfile.h.
• Статическая таблица f_imgui_keys[] (имя↔ImGuiKey), функции imgui_key_for_name, shortcut_pressed(key_shortcut), capture_shortcut(out).
• id-константы IMGUI_ACT_* (snake_case) + imgui_default_actions().
• Поля класса: keymap_config m_keymap, bool m_keybind_open, std::string m_keybind_recording, m_keybind_status. Инициализация в конструкторе.
• handle_events(): блок «global keys» переписан на shortcut_pressed(m_keymap.shortcut(ID)); в начале if(!m_keybind_recording.empty()) return;.
• init_debugger: config_register("debugger", …); РАСШИРЕН m_mapping — добавлены F1/F2/F4, все буквы, 0-9, Space, Insert (иначе MAME не прокидывает эти клавиши в ImGui и их нельзя ни нажать, ни записать).
• Меню Debug: ярлыки из m_keymap.shortcut(ID).to_string(), пункт «Customize keys...».
• Новые методы: config_load, config_save, draw_keybindings() (окно с таблицей, запись клавиш, Esc/Delete, конфликты, Reset All). Вызов draw_keybindings() в update().

Qt — 3 файла (без новых файлов и без новых moc-классов; диалог инлайн на лямбдах)

• qt/windowqt.h: include "../debugkeyconfig.h"; в DebuggerQt — virtual keymap_config &keymap()=0, сигнал keyBindingsChanged(), notifyKeyBindingsChanged(); в WindowQt — слоты applyKeyBindings(), debugActCustomizeKeys(), метод createKeyAction(id,text,slot), поле std::map<std::string,QAction*> m_keyActions. Объявлена std::vector<key_action> qtDefaultKeyActions();.
• qt/windowqt.cpp: id-константы ACT_* + qtDefaultKeyActions(); действия создаются через createKeyAction (ярлык из keymap, сохраняется в map); пункт «Customize Keys...»; applyKeyBindings(); debugActCustomizeKeys() — инлайн QDialog с QKeySequenceEdit на каждое действие, кнопки Ok/Cancel/RestoreDefaults; по OK пишет в keymap (через QKeySequence::toString(PortableText), берёт первый аккорд) и notifyKeyBindingsChanged().
• debugqt.cpp: член keymap_config m_keymap{qtDefaultKeyActions()}, override keymap(), в configuration_load/save добавлена ветка config_type::DEFAULT → m_keymap.load/save.
• Дефолты Qt ИЗМЕНЕНЫ со странных F16–F19 (заглушка в оригинале) на нормальные F5/F6/F7/F8/F11/F10/Shift+F11/F3/Shift+F3/Ctrl+M,D,L,B/Ctrl+W/Ctrl+Q — единые с остальными.

Build-скрипты

• scripts/src/osd/modules.lua — добавлены debugkeyconfig.cpp/.h в общий osdmodulesbuild() (компилируется во ВСЕХ OSD).
• scripts/src/osd/mac.lua, sdl.lua, sdl3.lua — добавлены 4 osx-файла Cocoa (debugkeymap.{h,mm}, debugkeymapviewer.{h,mm}).
• ImGui/Qt новых файлов не добавляли — правки в существующих.

---

Сборка и проверка (то, что использовалось)

Окружение: macOS, OSD sdl3, конфиг release64, тулчейн gmake-osx-clang, Qt5 (/usr/local/bin/qmake).

Регенерация проекта (ОБЯЗАТЕЛЬНО с --USE_QTDEBUG=1, иначе qt-файлы выпадают из сборки):

cd /Users/tolik/Documents/GitHub/mame
3rdparty/genie/bin/darwin/genie --with-emulator --USE_QTDEBUG=1 --OPTIMIZE=3 \
  --target='mame' --subtarget='mame' --build-dir='build' --osd='sdl3' \
  --targetos='macosx' --PLATFORM='x86' --gcc=osx-clang --gcc_version=17.0.0 gmake

Сборка только нужных библиотек (быстро, без линковки всего MAME):

make -R --no-print-directory -C build/projects/sdl3/mame/gmake-osx-clang config=release64 osd_sdl3 qtdbg_sdl3

• osd_sdl3 содержит debugimgui.o, debugkeyconfig.o, и osx-файлы Cocoa.
• qtdbg_sdl3 содержит debugqt.o, windowqt.o + moc.

Статус последней сборки: всё компилируется чисто, без ошибок/предупреждений (по теме). Полный бинарник (mame) НЕ релинковали — релинк потянул бы пересборку всего MAME. Для живого теста нужен полный билд (напр. make macosx_arm64_clang или скрипт пользователя), затем ~/Documents/MAME/debug.sh (там -debugger auto → Cocoa). Для ImGui/Qt — сменить -debugger (imgui требует -video bgfx).

Гочи сборки:

• genie без --USE_QTDEBUG=1 отключает qt → windowqt.o пропадает из всех .make (был эпизод: казалось, что файл не пересобирается).
• Объекты лежат в build/osx_clang/obj/x64/Release/<lib>/....
• qmake -query QT_INSTALL_LIBS даёт -F для фреймворков (macOS).

---

Что осталось / возможные продолжения

1. Win-дебаггер (пропущен). Если делать: ключи в win/debugwininfo.cpp (handle_key, WM_KEYDOWN-switch по VK_* + GetAsyncKeyState) и win/disasmbasewininfo.cpp; текст меню в create_standard_menubar() (строки вида "Run\tF5"); персист через debugwin config (DEFAULT); пункт «Customize keys…» + Win32-диалог (самое рискованное вслепую). Можно переиспользовать debugkeyconfig; нужен маппинг key_shortcut↔VK_*. Текстовый формат уже совместим — Windows-юзер и так может настроить через default.cfg/Qt/ImGui, а Win подхватит.
2. Полный релинк и интерактивная проверка ImGui/Qt вживую (запись клавиш, сохранение в default.cfg, перезапуск — раскладка восстановилась).
3. Возможная унификация Cocoa на тот же текстовый формат debugkeyconfig (сейчас отдельный) — не обязательно.

Действия (id → дефолт), для ориентира

ImGui (snake_case): new_disasm=Ctrl+D, new_memory=Ctrl+M, new_bpoints=Ctrl+B, new_wpoints=Ctrl+W, new_log=Ctrl+L, run=F5, run_next_cpu=F6, run_next_int=F7, run_vblank=F8, run_and_hide=F12, step_into=F11, step_over=F10, step_out=F9, soft_reset=F3, hard_reset=Shift+F3.

Qt (snake_case): new_memory=Ctrl+M, new_disasm=Ctrl+D, new_log=Ctrl+L, new_points=Ctrl+B, new_devices=(нет), run=F5, run_and_hide=F12, run_next_cpu=F6, run_next_int=F7, run_vblank=F8, step_into=F11, step_over=F10, step_out=Shift+F11, soft_reset=F3, hard_reset=Shift+F3, close_window=Ctrl+W, quit=Ctrl+Q.