# How to document Control/Command modifier for keyboard shortcuts?

**URL:** <https://discourse.slicer.org/t/how-to-document-control-command-modifier-for-keyboard-shortcuts/14449>\
**Category:** Development\
**Created:** [November 5, 2020, 4:21pm UTC](https://discourse.slicer.org/t/how-to-document-control-command-modifier-for-keyboard-shortcuts/14449 "2020-11-05T16:21:08Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [November 5, 2020, 4:21pm UTC](https://discourse.slicer.org/t/how-to-document-control-command-modifier-for-keyboard-shortcuts/14449/1 "2020-11-05T16:21:08Z")

</div>

Users seem to have a problem with interpreting our keyboard shortcuts (see for example [here](https://discourse.slicer.org/t/new-segment-editor-effect-local-threshold/9233/22)) 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](https://github.com/Slicer/Slicer/issues/5295) 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](https://docs.blender.org/manual/en/latest/interface/keymap/introduction.html).
- 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?

---

<div class="post-metadata">

**Author:** ![pieper](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/pieper/32/8_2.png) [@pieper](https://discourse.slicer.org/u/pieper)\
**Post date:** [November 5, 2020, 4:49pm UTC](https://discourse.slicer.org/t/how-to-document-control-command-modifier-for-keyboard-shortcuts/14449/2 "2020-11-05T16:49:52Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [November 5, 2020, 5:11pm UTC](https://discourse.slicer.org/t/how-to-document-control-command-modifier-for-keyboard-shortcuts/14449/3 "2020-11-05T17:11:34Z")

</div>

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](https://github.com/Kitware/VTK/blob/5a225156e34b9b1c21d367dee3afe0560677d98c/Interaction/Widgets/vtkEvent.h#L53-L57)). [Qt documentation](https://doc.qt.io/qt-5/qt.html#KeyboardModifier-enum) states that on macOS `ControlModifier` refers to the “Command” key.

---

<div class="post-metadata">

**Author:** ![jamesobutler](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/jamesobutler/32/7511_2.png) [@jamesobutler](https://discourse.slicer.org/u/jamesobutler)\
**Post date:** [November 5, 2020, 5:48pm UTC](https://discourse.slicer.org/t/how-to-document-control-command-modifier-for-keyboard-shortcuts/14449/4 "2020-11-05T17:48:38Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![jamesobutler](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/jamesobutler/32/7511_2.png) [@jamesobutler](https://discourse.slicer.org/u/jamesobutler)\
**Post date:** [November 5, 2020, 5:57pm UTC](https://discourse.slicer.org/t/how-to-document-control-command-modifier-for-keyboard-shortcuts/14449/5 "2020-11-05T17:57:19Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![pieper](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/pieper/32/8_2.png) [@pieper](https://discourse.slicer.org/u/pieper)\
**Post date:** [November 5, 2020, 6:09pm UTC](https://discourse.slicer.org/t/how-to-document-control-command-modifier-for-keyboard-shortcuts/14449/6 "2020-11-05T18:09:18Z")

</div>

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](https://support.google.com/chrome/answer/157179?hl=en&co=GENIE.Platform=Desktop)). 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.

---

<div class="post-metadata">

**Author:** ![jamesobutler](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/jamesobutler/32/7511_2.png) [@jamesobutler](https://discourse.slicer.org/u/jamesobutler)\
**Post date:** [November 5, 2020, 6:13pm UTC](https://discourse.slicer.org/t/how-to-document-control-command-modifier-for-keyboard-shortcuts/14449/7 "2020-11-05T18:13:31Z")

</div>

> [@pieper](#):
>
> 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.