Make keyboard controls more discoverable

[Mike Gifford]

Took a few of us very experienced web developers to realize that the way we're supposed to get into the menu without a mouse was to use Alt+0. Once that was figured out we were able to proceed a bit better.

In evaluating the implementation on Drupal 8 we realized it was difficult to find - ​https://drupal.org/node/1904986

We'd stumbled upon the CNTR+B & but it should have been easier to identify. It would be very useful to build in a tooltip so that when you hover or focus on an icon that the title & keyboard shortcuts pop up. This is a UI pattern that has been common on the desktop for a while.

Is it possible to change the combinations? It would be useful both for other languages, but also that some assistive technology has reserved keyboard shortcuts.

[Jakub Ś]

IMO alt+0 is very discoravable. This is a11y and it has been described many, many times -
​http://ckeditor.com/about/features (main page)
​http://docs.cksource.com/CKEditor_3.x/Accessibility_Compliance
​http://docs.cksource.com/CKEditor_3.x/Accessibility
​http://ckeditor.com/blog/CKEditor-WAI-ARIA-Usable-Accessibility

I remember since I have worked here CKEditor has always placed a11y word somewhere. IMHO this is not just unpacking the editor and using it. Reading manuals can be useful too. Don't get me wrong. All I'm sayingis if something was unclear it was IMO enough to check the docs as it is mentioned there.

If you were visually impaired and using JAWS, it would tell you about Alt+0.
I'm not sure if tooltip is useful here.

[Jakub Ś]

It would be very useful to build in a tooltip so that when you hover or focus on an icon

If you talk about using shortcuts in CKEditor like in IDE then they don't inform about shortcuts with tooltip like 'I have shortcuts'.
Such shortcuts are usually described in docs.
IDEs have however one thing that CKEditor doesn't - shortcuts placed next to menu options.

[Mike Gifford]

I was sitting with 3 accessibility folks on the Drupal Skype (and indeed on the Drupal issue queue) and nobody discovered it without research. alt+0 is as discoverable only if you do a Google search first and skip down & read the documentation. That's really not discoverable enough. Even then, it's a page of text that most of us aren't going to memorize if you aren't actively using the WYSIWYG. The vast majority of users won't do that, or remember. The vast majority of Mac users won't know that for keyboard shortcuts for Alt+F10 you also need the shift key too or it adjusts something else.

Discoverability is about making the information known to a user while they are using the interface.

Not that there is a usability study available on this, but it would be curious what percentage of CKEditor users know anything about the keyboard shortcuts which you've built in. I'd assume it's a lot lower than 10%.

[Wiktor Walc]

The vast majority of Mac users won't know that for keyboard shortcuts for Alt+F10 you also need the shift key too or it adjusts something else.

1) I think you're talking here about this issue: ​http://dev.ckeditor.com/ticket/9821 right? Do you think that proper documentation where Alt+F10 is described will be enough?

2) The rest of the ticket is about making CKEditor more user friendly for disabled users who just downloaded/started using an application with CKEditor included and simply want to use it without having to google to discover basic things (being able to access the toolbar is a very basic thing). I couldn't agree with you more.

When I tried to use CKEditor with VoiceOver, it just read the iframe title. aria-describedby attribute pointing to cke_voice_label ("Press ALT 0 for help") was ignored. I believe this is the main reason why the first steps with CKEditor were problematic.

@mgifford If VoiceOver properly read the "Press ALT 0 for help" hint soon after CKEditor is focused ("Rich Text Editor, editor1, Press ALT 0 for help"), do you agree that we'd be fine here as well?

3) Providing hints for toolbar buttons e.g. "Bold, shortcut Ctrl B" (?) sounds to me like an useful addition.

[Mike Gifford]

1) That the instructions are Windows specific is one thing. Alt+F10 works great for windows, but messes up everyone else -> ​http://dev.ckeditor.com/ticket/7505

2) We've tried it with Drupal and it's working alright. Could certainly use more testing, but there's a demo up here -> ​https://drupal.org/node/1872206#comment-7007270

There's what needs to be done for screen reader users (which requires testing in JAWS, NVDA & VoiceOver), but then there's also keyboard only users. Right now there's nothing to alert a keyboard only user how to access the keyboard controls. In general, alerting users who are either tabbing over the interface (via ARIA & possibly a temporary pop-up) is a great way to get folks to start making better use of the WYSIWYG.

3) Thanks. Ya, it's really just following the pattern I remember having on my Mac Classic back in 1989. Nothing groundbreaking.

[Jakub Ś]

Issue one (Docs should fit all supported operating systems) has been described in ​http://dev.ckeditor.com/ticket/9821

Issue three - tooltips for buttons should look like "Bold, Ctrl+B"
Issue three is valid thus I'm confirming this ticket.

[Mike Gifford]

Adding keywords.

[Jakub Ś]

Please don't add keywords we don't use.

[Wiktor Walc]

During archaeological research Piotrek found this duplicate: #1365. It was reported years ago @ Sourceforge for FCKeditor and later moved to this tracker:

When you mouse over italic, it should popup not only that this is the button to press for italics, but also that Ctrl+I will invoke italics while typeing. A small point, to be sure, but I've found it makes a huge different with new users.

[Mike Gifford]

What do we need to do to get this addressed? Not everyone is going to think about reading the English docs to determine what the keyboard controls are to access the WYSIWYG. Most folks will just say "Damn editor!" and assume it's just busted for them like so much of the Internet.

[Frederico Caldeira Knabben]

Note that right now our accessibility compatibility target is JAWS+Firefox... I believe this issue is limited to VoiceOver, that's why we may have had some misunderstanding on the previous comments.

[Mike Gifford]

Thanks. Definitely good to address Safari/VoiceOver which is becoming an increasingly important combination. Good to know what the target is.

[Wim Leers]

So, it sounds like we need to do a few things here:

1. Make sure that the "Press ALT 0 for help" announcement is also read by other screen readers than JAWS, as wwalc already said. This is the most pressing problem: that many non-sighted users are not informed at all.
2. Inform sighted power users via the button tooltips what the corresponding shortcut is.

What was discussed here, but cannot be a CKEditor responsibility, but should be the CKEditor implementor's responsibility:

1. Make sure that when a sighted keyboard user who navigates onto a CKEditor instance for the first time is also informed. But… CKEditor cannot and should not know how to recognize a user. So this is really not CKEditor's responsibility, but the implementor's — in our case Drupal's.

[Wim Leers]

falcon03 on Drupal.org pointed out that the hover tooltip should also be made available to screen reader users. aria-describedby should be used to do that.

[Wim Leers]

Drupal needs this ticket to be resolved before the Drupal 8 release, as well as the ​http://dev.ckeditor.com/ticket/9821 and ​http://dev.ckeditor.com/ticket/7505 subtickets.

(I've linked to this comment from ​https://drupal.org/node/1904986#comment-7964161.)

[Jakub Ś]

I was convinced that we have different shortcuts assigned based on OS but it seems that this isn't the case as we have other issues of that kind: #11916, #9821.

[Piotrek Koszuliński]

We've been thinking about this feature for a long time, but it got lost somewhere in our backlogs.

My proposal for what we can do in 4.6 is to add keystrokes to:

• titles of buttons in the toolbar,
• option names in the context menu.

If I'm not mistaken, most of this can be done automatically, because buttons have commands assigned, and commands have keystrokes assigned. Keystrokes are defined as numbers (e.g. CKEDITOR.CTRL + 42), but using String.fromCharCode() (for keys which have the same code as ASCII chars) + a hash of other popular keys, we could translate them to string versions. We can even make this translation function overridable (an event like ariaSth?), so one can better localise it for their needs. I'm worried though about language with a very different keyboard layouts, so we must research it.

Later, we may also consider adding keystrokes to things like buttons in dialogs, but this of course can't be done automatically, and I would split it to a separate ticket.

[Wim Leers]

I'm worried though about language with a very different keyboard layouts, so we must research it.

Well, I think things like Bold (CTRL+B), Italics (CTRL+I), cut/copy/paste (X/C/V) etc. are the same in all languages. At least in Belgium, where we have AZERTY instead of QWERTY, and speak/write/type Dutch, French, German and English, we use the same shortcuts.

[Piotrek Koszuliński]

I didn't mean keystrokes, because they are known to CKEditor (they are part of its configuration). So even though e.g. in French bold is usually assigned to other letter than "B" that should not be problem. CKEditor will know that it's not a "B" because the keystroke must be changed by a developer who wants to align the default keystrokes to a French user.

What's unclear to me are different alphabets. E.g. what a user having Cyrillic layout need to press to trigger CTRL+B? Is the key which triggers an event with code "66" labeled "B" or is it some other character? Or the opposite – perhaps none of the keys on his keyboard is "B" so the default keystroke does not work at all, and perhaps every Russian user reconfigures CKEditor's default keystrokes? If so, how to get the Cyrillic character which represents a key to which the keystroke was set (using a key code which CKEditor knows).

[Wim Leers]

Good questions :)

[Piotrek Koszuliński]

I've just checked on ​http://keycode.info/ that if I switch keyboard layout to cyrillic, then pressing "B" (on my keyboard) gives me the key code from PL/EN layout (so representing latin B). The same if I switch to Hiragana. If my check is accurate, that would mean that most likely most developers use the same keystrokes settings as we do. Now, will displaying "CTRL+B" in a tooltip be clear to a Russian user who have "B" in a different place? This is the most tricky case I think, because some latin characters appear in cyrillic but they represent different letters.

As for Japanese/Korean/etc users, I think that I saw that many of them have latin characters additionally printed on their keyboards, to ease the switch. And I think that many of them may be used to such inconvenience. Most likely a lot of software face the same problems. Although, this seems to be feasible because we can have a hashmap from latin to local key labels.

[Wim Leers]

Tweeted some people who've lived in Japan (or at least been to Japan) for a while: ​https://twitter.com/wimleers/status/624598232207720448 — hopefully that'll get us the info this need to move forward :)

[Piotrek Koszuliński]

Thanks, Wim. There's still some homework (research) that we can do, but input from outside will be even more valuable.

[smartcore]

You can see how it looks in Russian version of MS Word. The same is for Copy(Ctrl+C), Cut(Ctrl+X), etc

.

[Szymon Kupś]

There are some other questions that should be answered:

1. Should we use CMD button instead of CTRL in tooltips/context menus for Mac users? We treat both keys equally so CMD+B, gives same result as CTRL+B.
2. Should we use ideograms instead of key names? For example: ⌘ as COMMAND, or ⌥ as ALT. Ideograms takes less space but this approach will require some changes to information presented in a11yhelp dialog.
   In the other hand - string representations will require some translations, for example: CTRL in Germany is STRG.
3. Which keys should be converted to ideograms or be translated?

Keyboard shortcut information presented in a11y help dialog should be consistent with shortcuts presentsd on tooltips/context menus. We should decide how to extract this common data(translations/ideograms), and where to keep it.

[Piotrek Koszuliński]

As for using ideograms, the thing to notice is that in MacOS in the native context menus you can always find only ideograms (for all kind of keys). So MacOS users should be used to that. On Windows... this is more tricky ;/ I'm afraid we may need to use names at least for CTRL and ALT (shift keys usually have the arrow printed on them). Other than that, we should be safe to use ideograms for arrows and enter, but I don't think we'll need to worry about those keys as none of our features require them. I think that we should focus on the most popular keystrokes like undo, redo, bold, italic, copy, cut, etc. Those require a modifier + letter.

[Piotrek Koszuliński]

Another thing to notice is that the a11y dialog mentions CTRL on all OSes (including MacOS). Those keystrokes actually work with CTRL and CMD, but it may be confusing for users.

[Marek Lewandowski]

Ideograms

We're safe for using them for Mac as they're commonly used in OSX itself, but for the most of other OS users it will be very misleading.

But we should go with KISS and use consistent solution for all platforms. Therefore:

• CTRL + B - Windows, Linux
• CMD + B - Mac

Keystroke in Tooltips

Good idea, the most common convention for tooltip is <function name> (<hotkey>), so we can use Bold (CTRL+B) (or Bold (CMD+B)).

Keystroke in Context Menu

As for context menu we should simply align hotkeys to right-hand side. Ssome apps show hotkeys in ctx menu only if it was accessed purely with keyboard, like application key - but I think we can go with simple solution and include hotkeys anyway.

Hotkeys in Dialogs

To provide good keyboard navigation in dialogs we might implement accelerator keys, just as they are implemented in Windows or Linux. It's basically about exposing every dialog widget (be it input, button, tab) by just pressing alt + <key> combination. As you press alt, every accessible widget gets it's accelerator letter underlined. But I think this solution would take notable effort, while being used only by less than a percent of users (though personaly I'd love to use it in CKE! :) ).

Different Keyboard Layouts

I'll need to make a deeper check before going with this one, will update comment later.

[Frederico Caldeira Knabben]

I agree that, for simplicity, we don't need to go with ideograms.

CTRL must definitely be interchanged by CMD on macs.

IMHO, this is not a dialog issue. At this stage we should be focused on toolbar tooltips and (eventually) context menu.

Maybe the only special keys that we need translation for are CTRL, CMD, ALT, SHIFT, SPACE, ENTER and BACKSPACE. These should go into the core translation file. We could have the keycode as the entry key and the text representation as the value. All other characters should be then represented as the plain character itself.

[Marek Lewandowski]

Guys, you asked me to check how these characters behave in JAWS, so I've used characters used in ​https://support.apple.com/en-us/HT201236 and it's a no-no for JAWS. Some of them are readen but... in totally unsemantical way, e.g. "⇧" is readen as "Upwards white arrow".

### Details

More on that you'll find in CKEditor docs

• Cmd - ⌘ - character not read
• Shift ⇧ - readen as "Upwards white arrow"
• Option ⌥ - character not read
• Control ⌃ - character readen as "caret"
• Caps Lock ⇪ - character readen as "Upwards white arrow from bar" (???)

And as for NVDA (different SR software) they're not readen at all.

[Marek Lewandowski]

For an example solution how to add scree reader-only labels, see issue 1112 in CKFinder repository. Although solution used there does not work with NVDA.

[Frederico Caldeira Knabben]

Some of them are readen but... in totally unsemantical way, e.g. "⇧" is readen as "Upwards white arrow".

IF a AT would ever read them, I would expect their Unicode names to be read. So "Upwards white arrow" makes sense: ​http://www.fileformat.info/info/unicode/char/21e7/index.htm

But it'll never mean what Apples means it to be. Another example is the 'PLACE OF INTEREST SIGN' (⌘): ​http://www.fileformat.info/info/unicode/char/2318/index.htm

[Szymon Kupś]

I would like to propose my solution, I've pushed it to ​branch:t/10015.

Changes made from user perspective:

• Added keyboard shortcuts to toolbar tooltips (⌘, ⇧ and ⌥ are used on Mac):
• Added keyboard shortcuts to context menus:
• Added aria-description with information about shortcuts to toolbar buttons and context menus. For example, when Bold button is focused JAWS reads: "Bold button. Keyboard shortcut CTRL+B."

Code changes:

• Added getCommandKeystroke method to CKEDITOR.editor - it returns keystroke associated with given command.
• Added keystrokeToString method to CKEDITOR.tools. With this method keystroke can be converted to its string representation. Two strings are generated: one for displaying and one for ARIA descriptions. Displayed strings contain special characters (⌘, ⇧, ⌥) for Mac devices while ARIA descriptions always use text representation ("CTRL+B" or "COMMAND+B"). Key translations are stored in editor.lang.common.keyboard and can be extended in the future.
• Added fakeKeystroke property to CKEDITOR.commandDefinition. Commands like cut/copy/paste do not have keystroke associated to them, but still they're supported natively. This property is used to handle such situations.
• Added tests.

[smartcore]

I think that it's better to use "Ctrl", not "CTRL"

[Piotrek Koszuliński]

I think that it's better to use "Ctrl", not "CTRL"

+1.

[Marek Lewandowski]

+1 In case of tooltip, having it all caps puts a lot of emphasize to the hotkey.

[Szymon Kupś]

Pushed new commit to ​branch:t/10015 - changing letter case.

[Wim Leers]

But we should go with KISS and use consistent solution for all platforms. Therefore:

This makes no sense IMO…

e.g. "⇧" is read as "Upwards white arrow".

… but this is of course a great reason to not do this. Then again, JAWS is not for OS X, so I wonder how VoiceOver behaves?

---

Every OS has its own HIG. CKEditor should try to match that to a reasonable extent.

Of course, this is just a nice-to-have. Many people will understand "CMD+B". So I think using ideograms on OS X is merely a nice-to-have, that could have a separate, lower priority ticket as a follow-up to this one, to be implemented (or contributed!) some day. The experience shown in the screenshots in ticket:10015#comment:35 present a huge step forward! :)

+1!

[Yahya Uddin]

When will this feature finally be added? It's been 3 years! A feature like this should surely be a critical feature for any editor!

Needless to say:

+1

[Mike Gifford]

This is an important piece of ATAG ​https://www.w3.org/WAI/intro/atag.php

Making the user interface accessible and documenting it so that people know what accessibility enhancements have been made.

[Marek Lewandowski]

Yes, we're definitely still looking on putting this enhancement into 4.6.0! However currently we have a lot of things going on in CKE, and we can't guarantee every thicket will make it. Nonetheless thanks for showing us that this enhancement is desired by our community, we always appreciate this kind of feedback.

[Tade0]

Code overall looks good, tests pass on IE11, Edge, Chrome, Firefox, Safari. I failed to break anything.

What's left is to check how this performs on screen readers.

[Marek Lewandowski]

Good job, I've added integration with the new skin and checked the a11y.

Fixed with ​git:320de9490c (merged to major).