Skip to content

Assign macOS text navigation key bindings - #1125

Merged
dail8859 merged 1 commit into
dail8859:masterfrom
hemanpa:fix/712-macos-navigation-shortcuts
Sep 12, 2026
Merged

Assign macOS text navigation key bindings#1125
dail8859 merged 1 commit into
dail8859:masterfrom
hemanpa:fix/712-macos-navigation-shortcuts

Conversation

@hemanpa

@hemanpa hemanpa commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Cause

Scintilla's macOS key bindings live behind OS_X_KEYS in KeyMap.cxx, which is gated on
PLAT_GTK_MACOSX. Platform.h takes the #elif defined(SCINTILLA_QT) branch, so
PLAT_GTK_MACOSX is always 0 and those bindings never apply.

Enabling that flag alone isn't sufficient, which is why the earlier attempt in this issue
didn't behave as expected: under OS_X_KEYS, Scintilla routes word-wise movement through
SCI_CTRL_META = SCI_META, but ScintillaEditBase calls ModifierFlags(shift, ctrl, alt)
and never reports meta at all — so word movement would have become unreachable entirely.

The effect today on macOS is that Command + arrow keys scroll the view or move by word
instead of moving to the start/end of the line and document, and Option + arrow keys do
nothing at all.

Approach

The bindings are assigned from EditorManager::setupEditor() under Q_OS_MACOS rather than
by patching the bundled Scintilla, so that updating Scintilla cannot silently revert them.
On macOS Qt reports Command as Qt::ControlModifier (SCMOD_CTRL) and Option as
Qt::AltModifier (SCMOD_ALT).

Keys Command
Cmd + Left/Right VCHome / LineEnd (+ Shift to extend)
Cmd + Up/Down DocumentStart / DocumentEnd
Option + Left/Right WordLeft / WordRight (+ Shift to extend)
Cmd + Option + Shift + arrows rectangular selection extend
Option + Backspace DelWordLeft
Cmd + Backspace DelLineLeft
Cmd + Shift + Z Redo

These follow the macOS system conventions and VS Code's defaults. Since Option + Shift +
Left/Right now select by word, Cmd + Option + Shift + arrows are added for rectangular
selection (also matching VS Code); Option + Shift + Up/Down keep Scintilla's default
rectangular behaviour as nothing else uses them.

Three notes:

  • Cmd + Shift + Up/Down are deliberately not bound. actionMoveSelectedLinesUp/Down
    already use Ctrl+Shift+Up/Down and QActions receive the key press before the editor does.
    Happy to relocate those on macOS instead if you'd prefer.
  • Cmd + Shift + Z is added at the editor level only; the Redo menu item still shows
    Ctrl+Y. Let me know if you'd rather the menu shortcut changed on macOS too.
  • While a multiple selection is active, BetterMultiSelection handles these keys before the
    editor's key bindings, so Cmd + Left/Right moves by word there rather than to the line
    start/end. That path is unchanged by this PR and matches VS Code's behaviour for
    multi-caret editing.

Testing

Built and tested by hand on macOS 26.6 with Qt 6.11.2. Every binding in the table above
behaves as expected, including the smart-home toggle on an indented line (first press moves
to the first non-whitespace character, second to column 1) and correct column alignment for
rectangular selections. Verified that Cmd + Shift + Up/Down still moves selected lines, and
all changes are inside #ifdef Q_OS_MACOS so other platforms are unaffected.

The failing codespell check is pre-existing on master (see #1124) and unrelated to this
change.

Fixes #712

Scintilla's macOS key bindings are gated on PLAT_GTK_MACOSX, which is never
defined for the Qt platform layer because Platform.h takes the SCINTILLA_QT
branch, so those bindings are never applied. Scintilla also routes word-wise
movement through SCI_META, but the Qt layer's ModifierFlags() only reports
shift, ctrl and alt, so that modifier is never delivered either.

The result on macOS is that Command and arrow keys scroll the view or move by
word rather than moving to the start/end of the line and of the document, and
Option and arrow keys do nothing at all.

Assign the standard macOS bindings from setupEditor() rather than patching the
bundled Scintilla, so that updating Scintilla cannot silently revert them.

Command + Shift + Up/Down are left alone since the Move Selected Lines Up/Down
actions already use them and receive the key press before the editor does.

Fixes dail8859#712
@dail8859
dail8859 merged commit e2e17cd into dail8859:master Sep 12, 2026
9 of 12 checks passed
@dail8859

Copy link
Copy Markdown
Owner

Appreciate your explanation as at the time when I took a shot at it, I wasn't exactly sure what the root problem was. Ultimately, it sounds like Scintilla is not quite configured right when compiling for Qt on Mac. This approach is clean and straightforward so I do not see a problem with it.

Ideally in the future it is likely that all shortcut keys will be handled through actions and not let Scintilla do any of the shortcut handling, that way the app can rely on Qt's Standard Key and allow for more customizations.

But for now I think this is the best approach.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Missing/inconsistent text navigation shortcuts on MacOS

2 participants