How to document Control/Command modifier for keyboard shortcuts?

Users seem to have a problem with interpreting our keyboard shortcuts (see for example here) because Windows and Linux’s “Control” key is mapped to “Command” key on Mac. Qt automatically generates shortcut name based on operating system (Ctrl or ⌘) and we could replace hardcoded “Ctrl” string with platform-specific string in all of our modules (added an issue to track this), but what to do with the documentation?

  • Option A: Use “Ctrl” and describe somewhere that on Mac you need to hit ⌘ if you read “Ctrl” in the documentation. Are Mac of multiplatform software got used to this? For example, I see that this is done in the Blender manual.
  • Option B: Replace shortcuts such as Ctrl+A by Ctrl/⌘+A. Would this be clear enough for Mac users? Would it be acceptable (wouldn’t it cause confusion) for Windows users?

Modern mac keyboards include the text “command” on the modifier key, so I would avoid the “⌘” character. The “⌘” looks very 80s to me and feels like mac pretentiousness (said as a regular mac user for decades).

As long as we are consistent that command on mac always means the same as control on non-mac then I would be comfortable just saying Ctrl- in the documentation and mac users can easily learn it.

My concern would be that at the vtk event level we actually need to use the key marked control. Are we sure it’s always mapped to command in all uses?

OK, having to display only Ctrl would simplify things.

In source code it is already just called Ctrl, in both Qt and VTK. There is not even a “Cmd” modifier in VTK (see here). Qt documentation states that on macOS ControlModifier refers to the “Command” key.

If you only display it in the documentation as “Ctrl”, you’re still going to have the same issue of Apple Mac users reading “Ctrl+A” and actually pressing the “Control” key instead of the “Command” key on their keyboard.

⌘+A actually seems appropriate since macOS shows it as such in the menubar area even though the actual key no longer has the “⌘” symbol.

There’s no perfect solution, and mac users need to live with the legacy of single-button mice. So the ‘control’ key on the mac keyboard together with a left mouse click is equal to the right mouse click on other platforms. (And shift-left mouse is the middle mouse button.)

So yes, as long as both Qt and VTK both uniformly map control to the command key we just need to find a clean way to communicate that.

The cleanest I have seen is to just have multiple shortcut tables as needed for the platforms you support (e.g. here’s what Chrome does). That way you avoid the extra visual distraction of trying to put multiple shortcut options into a single string, particularly when there are multiple modifiers involved. So you get “⌘ + Shift + b” in the mac table and ‘Ctrl + Shift + b’ in the windows/linux table rather than the probably confusing “Ctrl + Shift/Ctrl + Shift b” in a unified table. So I’d vote for either separate tables or separate columns.

I second that vote. That will make it obviously clear to Apple Mac users.