From 5f31f22ba32d8285344fb985b544588c40bf475f Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Mon, 23 Sep 2024 09:44:49 +0200 Subject: [PATCH] [TASK] Describe caveats of HotKey API (#4774) * [TASK] Describe caveats of HotKey API original from: https://forge.typo3.org/issues/105078 * [CLEANUP] CGL --- .../Backend/JavaScript/HotkeyApi/Index.rst | 25 ++++++++++++++++++- .../Backend/JavaScript/HotkeyApi/_example.js | 4 +-- 2 files changed, 26 insertions(+), 3 deletions(-) diff --git a/Documentation/ApiOverview/Backend/JavaScript/HotkeyApi/Index.rst b/Documentation/ApiOverview/Backend/JavaScript/HotkeyApi/Index.rst index f8145b23a1..9c02f86be1 100644 --- a/Documentation/ApiOverview/Backend/JavaScript/HotkeyApi/Index.rst +++ b/Documentation/ApiOverview/Backend/JavaScript/HotkeyApi/Index.rst @@ -18,9 +18,32 @@ extensions. The module provides an enum with common modifier keys: :kbd:`Ctrl`, :kbd:`Meta`, :kbd:`Alt`, and :kbd:`Shift`), and also a public property describing the common hotkey modifier based on the user's operating system: :kbd:`Cmd` (Meta) on macOS, -:kbd:`Ctrl` on anything else. Using any modifier is optional, but highly +:kbd:`Ctrl` on anything else (this can be normalized via +:javascript:`Hotkeys.normalizedCtrlModifierKey`. Using any modifier is optional, but highly recommended. +.. hint:: + + Note that on macOS, using the :javascript:`ModifierKeys.ALT` to query a + pressed key needs you to listen on the key that results in using this + modifier. So, if you listen on: + + .. code-block:: javascript + + [Hotkeys.normalizedCtrlModifierKey, ModifierKeys.ALT, 'e'] + + this will not work, because on macOS :kbd:`ALT+e` results in `€`, + and you would need to bind to: + + .. code-block:: javascript + + [Hotkeys.normalizedCtrlModifierKey, ModifierKeys.ALT, '€'] + + instead. To make this work across different operating systems, + it would be recommended to listen on both variants with distinct + javascript callbacks executing the same action. Or, try avoiding + to bind to `ModifierKeys.ALT` altogether. + A hotkey is registered with the :js:`register()` method. The method takes three arguments: diff --git a/Documentation/ApiOverview/Backend/JavaScript/HotkeyApi/_example.js b/Documentation/ApiOverview/Backend/JavaScript/HotkeyApi/_example.js index 1ffdbaafd6..85646b3697 100644 --- a/Documentation/ApiOverview/Backend/JavaScript/HotkeyApi/_example.js +++ b/Documentation/ApiOverview/Backend/JavaScript/HotkeyApi/_example.js @@ -1,7 +1,7 @@ import Hotkeys, {ModifierKeys} from '@typo3/backend/hotkeys.js'; -Hotkeys.register([Hotkeys.normalizedCtrlModifierKey, ModifierKeys.ALT, 'e'], keyboardEvent => { - console.log('Triggered on Ctrl/Cmd+Alt+E'); +Hotkeys.register([Hotkeys.normalizedCtrlModifierKey, ModifierKeys.SHIFT, 'e'], keyboardEvent => { + console.log('Triggered on Ctrl/Cmd+Shift+E'); }, { scope: 'my-extension/module', bindElement: document.querySelector('.some-element')