[GSoC'24]: Implement Keyboard Shortcuts Helper #16880

SanjaySargam · 2024-08-16T06:37:03Z

Purpose / Description

Keyboard shortcuts for Chromebook users are important because they make it easier and faster to use AnkiDroid. Alt + K shortcut will show keyboard shortcuts dialog

How Has This Been Tested?

HP CHROMEBOOK
Screen recording 2024-08-16 11.38.57 AM.webm

Learning (optional, can help others)

Describe the research stage

_Links to blog posts, patterns, libraries or addons used to solve this problem
https://developer.android.com/develop/ui/compose/touch-input/keyboard-input/keyboard-shortcuts-helper

Checklist

Please, go through these checks before submitting the PR.

You have a descriptive commit message with a short title (first line, max 50 chars).
You have commented your code, particularly in hard-to-understand areas
You have performed a self-review of your own code
UI changes: include screenshots of all affected screens (in particular showing any new or changed strings)
UI Changes: You have tested your change using the Google Accessibility Scanner

github-actions · 2024-08-16T06:37:15Z

Message to maintainers, this PR contains strings changes.

Before merging this PR, it is best to run the "Sync Translations" GitHub action, then make and merge a PR from the i18n_sync branch to get translations cleaned out.
Then merge this PR, and immediately do another translation PR so the huge change made by this PR's key changes are all by themselves.

Read more about updating strings on the wiki,

AnkiDroid/src/main/java/com/ichi2/compat/Compat.kt

AnkiDroid/src/main/res/values/02-strings.xml

Arthur-Milchior · 2024-08-16T10:05:25Z

AnkiDroid/src/main/res/values/02-strings.xml

@@ -425,4 +425,35 @@ opening the system text to speech settings fails">
    <string name="play_recording">Play</string>
    <string name="next_recording">Next</string>

+    <!--Keyboard Shortcut Dialog-->
+    <string name="show_keyboard_shortcuts_dialog">Show keyboard shortcuts dialog</string>


I'm sorry, because, this is going to be very boring. But can you check that all of those strings are new. If they are not, then please simply consider reusing it.
I would expect that for most case, you'd have an entry in the menus. For example, instead of "Save Note", I think we could reuse "Save" that is already used as a label of the tick in the note editor.

Ideally, I 'd like the strings to be grouped with other strings related to the same feature. E.g. the Open Statistics could be in 10-preferences. After all, I expect that, from a translator point of view (which is what matters here), they should see this string when they want to consider the Preferences.

Finally, I'm going to ask you to add a comment for all of them, because it's probably not clear for translators that this string appear in the context of a shortcut description, or of the category of shortcuts.

It could be simply something such as
comment="Description of the shortcut that open the statistics page"

FYI, "Open statistics" is good, I'm happy that the descriptions are small as much as possible. However, the comment should be very very explicit. Because the translator can't just test the shortcut (as they are not currently using the app, and even if they have a smartphone with ankidroid, they may not even have a keyboard)
And they should be very sure what the shortcut does so that they can find an appropriate short description

Also: do other apps use Title Case, or Sentence case for these strings?

Yes
Ex: Discord

Arthur-Milchior · 2024-08-16T10:07:10Z

AnkiDroid/src/main/java/com/ichi2/compat/CompatV24.kt

+            )
+
+        val cardTemplateEditorShortcutGroup =
+            KeyboardShortcutGroup(


As discussed on discord, I'd prefer this to be in a companion object in the CardTemplateEditor. It will be simpler to find where to edit the shortcut content when you edit the code for shortcut.

Also, I'd appreciate if, near the function dealing with shortcut, you can add a comment that state "When you edit this field, reflect the change in cardTemplateEditorShortcutGroup

As discussed on discord, I'd prefer this to be in a companion object in the CardTemplateEditor. It will be simpler to find where to edit the shortcut content when you edit the code for shortcut.

Is this goes similar to other screens (DeckPicker, NoteEditor, CardBrowser) ??

david-allison

Fundamentally: great change!

AnkiDroid/src/main/java/com/ichi2/compat/CompatV23.kt

david-allison · 2024-08-19T13:42:30Z

AnkiDroid/src/main/java/com/ichi2/anki/AnkiActivity.kt

+        menu: Menu?,
+        deviceId: Int
+    ) {
+        val shortcutGroups = CompatHelper.compat.getAllShortcuts(this)


Why are we showing shortcuts irrelevant to the current screen?

The reply also be a code comment

We include all shortcuts here so that the keyboard shortcut dialog can be opened from anywhere in the app using the Alt+K shortcut, ensuring users have quick access to all available shortcuts regardless of the current screen.

I'll leave this one to @Arthur-Milchior

Personally:

If a screen has no specific actions, I'd want everything

If a screen has specific actions, I'd only want to see relevant actions + global actions

@Arthur-Milchior FYI

Oops sorry.
In my mind, if a screen has no specific action, I prefer to see only the ankidroid general actions, even if they are only two.
And, most importantly, let's not show the snackbar to tell users to use alt-k. After all, when there is no specific action, this snackbar is pointless

david-allison · 2024-08-19T13:44:15Z

AnkiDroid/src/main/java/com/ichi2/anki/AnkiActivity.kt

+    }
+
+    override fun onKeyUp(keyCode: Int, event: KeyEvent): Boolean {
+        if (keyCode == KeyEvent.KEYCODE_K && event.isAltPressed) {


This is a good start, but realistically nobody is going to know about this keyboard shortcut

There's a number of things we can do here, for example:

If a user presses an unmapped shortcut, show a message that "Alt+K" shows all shortcuts?

How can I get unmapped shortcut? Do you know any easy way to achieve it

Typically: super is not called if the action is handled

The snackbar shows up every time any key is pressed, which includes the back and volume buttons.

And why Alt+K? Is that a standard somewhere? In iPadOS it is Command (https://support.apple.com/en-us/102393). Anything that can benefit from external consistency is good to me.

If a user presses an unmapped shortcut, show a message that "Alt+K" shows all shortcuts?

It is useful only once and very annoying every time a miss a shortcut in the future. Alos, that will be a nightmare with controllers, special keys and special devices.

I refined the statement in a follow-up comment to only include shortcuts with modifier keys pressed

AnkiDroid/src/main/java/com/ichi2/compat/CompatV23.kt

david-allison · 2024-08-19T13:45:41Z

AnkiDroid/src/main/res/values/02-strings.xml

@@ -425,4 +425,35 @@ opening the system text to speech settings fails">
    <string name="play_recording">Play</string>
    <string name="next_recording">Next</string>

+    <!--Keyboard Shortcut Dialog-->
+    <string name="show_keyboard_shortcuts_dialog">Show keyboard shortcuts dialog</string>


Also: do other apps use Title Case, or Sentence case for these strings?

AnkiDroid/src/main/java/com/ichi2/compat/CompatV24.kt

AnkiDroid/src/main/res/values/02-strings.xml

AnkiDroid/src/main/res/values/07-cardbrowser.xml

david-allison · 2024-08-22T15:30:43Z

AnkiDroid/src/main/java/com/ichi2/anki/AnkiActivity.kt

+        menu: Menu?,
+        deviceId: Int
+    ) {
+        val shortcutGroups = CompatHelper.compat.getAllShortcuts(this)


I'll leave this one to @Arthur-Milchior

Personally:

If a screen has no specific actions, I'd want everything

If a screen has specific actions, I'd only want to see relevant actions + global actions

brishtibheja · 2024-08-24T15:21:11Z

Is Alt+K used in other Android devices? I couldn't find that on my own. In my Android, the global shortcut is Search+/ and it also works in Google keep notes. The app-specific shortcuts are shown along with the system shortcuts here.

SanjaySargam · 2024-08-24T15:53:51Z

Is Alt+K used in other Android devices?

Nope. Here K for keyboard shortcuts

brishtibheja · 2024-08-24T16:59:05Z

It would be nice to have it match with other apps/system shortcuts, although I'm not sure if there's a standard or it just depends on app/device.

Arthur-Milchior · 2024-08-25T03:35:32Z

My bad, I'm very sorry, my mistake.
When I saw

on https://developer.android.com/develop/ui/compose/touch-input/keyboard-input/keyboard-shortcuts-helper
I thought that "System" "Input" and "Open Apps" were three KeyboardShortcutGroup.

I would have been fine to have such a UI. Let's say you're in card browser, you'll see the CardBrowser group first. And if you wanted, you could open the other groups, to get an idea of what you can do in the deck picker let's say. But by default, you'd only get the currently relevent shortcuts.

Clearly, I was wrong, and the "groups" are all displayed at once in a single list. This indeed looks far too busy. I don't like it.

So, yeah, I'm sorry and I'll ask you to revert and only show the shortcuts from the current activities.

Please also only display the message about shortcut only if there are available shortcuts, so that we don't offer to the user a list of shortcut that only contains alt+k

SanjaySargam · 2024-08-31T05:51:59Z

@Arthur-Milchior

    <string name="deck_picker_widget_description">Deck Picker Widget</string>

OK?

Arthur-Milchior · 2024-08-31T20:37:15Z

No. It's clear in the context that it's a widget. No need to state it.
My point was really that it would be useful to add a comment="Title of the Deck Picker Widget. Displayed to the user in Android's Widget Selection menu"

mikehardy · 2024-09-16T12:37:45Z

@Arthur-Milchior this appears to have a high frequency of conflicts, and also requires strings
Is it ready to go now or not?

Arthur-Milchior

@mikehardy It was not mergeable. If you tried to type an upper case in the note editor, you'd get a toast telling you to use alt+k to see the list of shortcut.

I added two commits on top of it, with my suggestion of change, I hope we save time.

This refactor some code to avoid duplication. And avoid add an extra interface that does not seems very useful to me.
Plus, I ensure that "shift" does not trigger the "show shortcut list" toast

Arthur-Milchior · 2024-09-17T14:43:40Z

AnkiDroid/src/main/java/com/ichi2/anki/NoteEditor.kt

@@ -950,6 +963,12 @@ class NoteEditor : AnkiFragment(R.layout.note_editor), DeckSelectionListener, Su
                    }
                }
            }
+            KeyEvent.KEYCODE_K -> {
+                if (event.isAltPressed) {
+                    CompatHelper.compat.showKeyboardShortcutsDialog(ankiActivity)


I thought there was an agreement that, if there is no specific keyboard for an activity A, we'll just show the general shortcuts that are present in all activities.
If so, this part of the code should be in AnkiActivity so that the shortcut alt+k is always available, in all activities.

Arthur-Milchior · 2024-09-17T14:44:15Z

AnkiDroid/src/main/java/com/ichi2/anki/NoteEditor.kt

@@ -961,6 +980,12 @@ class NoteEditor : AnkiFragment(R.layout.note_editor), DeckSelectionListener, Su
            selectFieldIndex(humanReadableDigit - 1)
            return true
        }
+
+        // Show snackbar only if a modifier key is pressed and the keyCode is an unmapped alphabet key
+        if ((event.isCtrlPressed || event.isAltPressed || event.isShiftPressed) && keyCode in KeyEvent.KEYCODE_A..KeyEvent.KEYCODE_Z) {


and same with this case.

Arthur-Milchior · 2024-09-17T14:50:58Z

AnkiDroid/src/main/java/com/ichi2/anki/SingleFragmentActivity.kt

 }

 interface DispatchKeyEventListener {
    fun dispatchKeyEvent(event: KeyEvent): Boolean
 }
+
+interface KeyboardShortcutEventListener {
+    fun onProvideKeyboardShortcuts(


I'd appreciate a comment. Even if it's just @see and the function you imitate

Arthur-Milchior · 2024-09-17T15:02:05Z

AnkiDroid/src/main/java/com/ichi2/compat/CompatV24.kt

+            val label: String = label.toDisplayString(context)
+            val parts = shortcut.split("+")
+            val key = parts.last()
+            val keycode: Int = KeyEvent.keyCodeFromString(key)


This require the user to type "NUMPAD_1" and so on for number.
I suggest we have our own function getKey, similar to getModifier, that will return the keycode of a given key.
Except that the key could be a single digit, so we don't have to write "NUMPAD_1" everytime we use a number in a shortcut. (Admittedly, right now, this only concerns the reviewer. Still, I'd find it more readable in the reviewer code)

Arthur-Milchior · 2024-09-21T18:28:56Z

AnkiDroid/src/main/java/com/ichi2/anki/CardTemplateEditor.kt

@@ -321,62 +326,93 @@ open class CardTemplateEditor : AnkiActivity(), DeckSelectionListener {
        invalidateOptionsMenu()
    }

+    override fun onProvideKeyboardShortcuts(


It seems to me this could be in AnkiActivity, so we don't have to copy-paste it in every child

Arthur-Milchior · 2024-09-21T18:35:06Z

AnkiDroid/src/main/java/com/ichi2/anki/CardTemplateEditor.kt

            return true
        }
+
+        // Show snackbar only if a modifier key is pressed and the keyCode is an unmapped alphabet key
+        if ((event.isCtrlPressed || event.isAltPressed || event.isShiftPressed) && keyCode in KeyEvent.KEYCODE_A..KeyEvent.KEYCODE_Z) {


In my opinion:

alt+k should work in every activity. In the worst case, the user will see there is not a lot to do there

the snackbar should be shown iff there are anything specific to see there. So we don't invite the user to open the shortcut list uselessly. It can be done simply by checking whether shortcuts is null

on top of A-Z we should also consider digits.

Arthur-Milchior · 2024-09-21T18:42:52Z

AnkiDroid/src/main/java/com/ichi2/anki/SingleFragmentActivity.kt

+        if (fragment is KeyboardShortcutEventListener) {
+            fragment.onProvideKeyboardShortcuts(data, menu, deviceId)
+        } else {
+            super.onProvideKeyboardShortcuts(data, menu, deviceId)


I think you should call super in any case.

Arthur-Milchior · 2024-09-21T18:58:59Z

AnkiDroid/src/main/java/com/ichi2/anki/CardBrowser.kt

@@ -804,6 +822,12 @@ open class CardBrowser :
                }
            }
        }
+
+        // Show snackbar only if a modifier key is pressed and the keyCode is an unmapped alphabet key
+        if ((event.isCtrlPressed || event.isAltPressed || event.isShiftPressed) && keyCode in KeyEvent.KEYCODE_A..KeyEvent.KEYCODE_Z) {


The shift part should be removed I think. Because it's naturally used when typing in the search bar, and it ends up with the message appearing each time you put a upper case character

Arthur-Milchior · 2024-09-21T19:19:53Z

AnkiDroid/src/main/java/com/ichi2/compat/StringResource.kt

+import com.ichi2.anki.CollectionManager.TR
+import net.ankiweb.rsdroid.Translations
+
+sealed interface StringResource {


I'm not a huge fan of this interface.
Either we expect to have similar need into the future, in which case I believe it should also accept strings with parameters and be fully general.
Or we expect it to be only for Shortcut, in which case

/** * Provides a [CompatV24.Shortcut], from the shortcut keys and the resource id of its description. */ fun AnkiActivityProvider.shortcut(shortcut: String, @StringRes labelRes: Int) = CompatV24.Shortcut(shortcut, ankiActivity.getString(labelRes)) /** * Provides a [CompatV24.Shortcut], from the shortcut keys and the function from anki strings. */ fun shortcut(shortcut: String, getTranslation: Translations.() -> String) = CompatV24.Shortcut(shortcut, getTranslation(TR))

is largely sufficient.

With

interface AnkiActivityProvider { val ankiActivity: AnkiActivity }

Arthur-Milchior

@david-allison there was quite some changes since you reviewed. Including one that corrected a real bug. So I'd appreciate if you could re-review before we merge

github-actions bot added the Strings label Aug 16, 2024

SanjaySargam added Needs Review GSoC Pull requests authored by a Google Summer of Code participant [Candidate/Selected], for GSoC mentors Strings and removed Strings labels Aug 16, 2024

SanjaySargam force-pushed the keyboard-shortcut-helper branch 2 times, most recently from ee30b44 to a76f17d Compare August 16, 2024 09:53

Arthur-Milchior reviewed Aug 16, 2024

View reviewed changes

SanjaySargam force-pushed the keyboard-shortcut-helper branch from a76f17d to a5452c3 Compare August 17, 2024 12:20

github-actions bot added the Has Conflicts label Aug 19, 2024

david-allison added the Needs Author Reply Waiting for a reply from the original author label Aug 19, 2024

david-allison reviewed Aug 19, 2024

View reviewed changes

SanjaySargam force-pushed the keyboard-shortcut-helper branch from a5452c3 to 0c326ac Compare August 20, 2024 20:03

SanjaySargam removed the Has Conflicts label Aug 20, 2024

SanjaySargam force-pushed the keyboard-shortcut-helper branch from 0c326ac to 01902e2 Compare August 21, 2024 18:37

SanjaySargam removed the Needs Author Reply Waiting for a reply from the original author label Aug 21, 2024

SanjaySargam requested a review from Arthur-Milchior August 21, 2024 18:38

SanjaySargam force-pushed the keyboard-shortcut-helper branch from 01902e2 to 278d9e9 Compare August 22, 2024 05:18

SanjaySargam requested a review from david-allison August 22, 2024 06:01

david-allison requested changes Aug 22, 2024

View reviewed changes

SanjaySargam force-pushed the keyboard-shortcut-helper branch from 278d9e9 to f450244 Compare August 23, 2024 11:48

SanjaySargam requested a review from david-allison August 23, 2024 11:48

github-actions bot added the Has Conflicts label Aug 24, 2024

SanjaySargam force-pushed the keyboard-shortcut-helper branch from f450244 to 508aa7b Compare August 24, 2024 08:14

SanjaySargam removed the Has Conflicts label Aug 24, 2024

github-actions bot added the Has Conflicts label Aug 31, 2024

SanjaySargam force-pushed the keyboard-shortcut-helper branch 2 times, most recently from 2f550d3 to 4fc2a14 Compare August 31, 2024 05:51

SanjaySargam force-pushed the keyboard-shortcut-helper branch from 4fc2a14 to a509bc6 Compare August 31, 2024 06:08

SanjaySargam removed the Has Conflicts label Aug 31, 2024

github-actions bot added the Has Conflicts label Aug 31, 2024

SanjaySargam force-pushed the keyboard-shortcut-helper branch 2 times, most recently from 52d5b0f to 7aa5f6c Compare September 1, 2024 12:46

github-actions bot removed the Has Conflicts label Sep 1, 2024

SanjaySargam force-pushed the keyboard-shortcut-helper branch from 7aa5f6c to 5f6b5e7 Compare September 1, 2024 17:42

SanjaySargam requested a review from Arthur-Milchior September 1, 2024 17:51

github-actions bot added the Has Conflicts label Sep 8, 2024

SanjaySargam force-pushed the keyboard-shortcut-helper branch from 5f6b5e7 to 0a1554b Compare September 10, 2024 18:39

SanjaySargam removed the Has Conflicts label Sep 10, 2024

mikehardy added the Review High Priority Request for high priority review label Sep 16, 2024

github-actions bot added the Has Conflicts label Sep 21, 2024

SanjaySargam force-pushed the keyboard-shortcut-helper branch from 0a1554b to 5d35d8d Compare September 21, 2024 11:15

Arthur-Milchior reviewed Sep 21, 2024

View reviewed changes

Arthur-Milchior removed the Has Conflicts label Sep 21, 2024

SanjaySargam and others added 3 commits September 22, 2024 02:02

feat: keyboard shortcuts helper

675d5e2

tmp

9051aa0

NF: remove string resource

6b75e7b

SanjaySargam force-pushed the keyboard-shortcut-helper branch from 81ac1eb to 6b75e7b Compare September 21, 2024 20:46

Arthur-Milchior added the squash-merge The pull request currently requires maintainers to "Squash Merge" label Sep 21, 2024

Arthur-Milchior requested a review from david-allison September 21, 2024 21:24

Arthur-Milchior approved these changes Sep 21, 2024

View reviewed changes

github-actions bot added the Has Conflicts label Sep 28, 2024

[GSoC'24]: Implement Keyboard Shortcuts Helper #16880

Are you sure you want to change the base?

[GSoC'24]: Implement Keyboard Shortcuts Helper #16880

Conversation

SanjaySargam commented Aug 16, 2024

Purpose / Description

How Has This Been Tested?

Learning (optional, can help others)

Checklist

github-actions bot commented Aug 16, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

david-allison left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

david-allison Aug 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

david-allison Aug 22, 2024 • edited Loading

Choose a reason for hiding this comment

brishtibheja commented Aug 24, 2024

SanjaySargam commented Aug 24, 2024

brishtibheja commented Aug 24, 2024

Arthur-Milchior commented Aug 25, 2024

SanjaySargam commented Aug 31, 2024

Arthur-Milchior commented Aug 31, 2024

mikehardy commented Sep 16, 2024

Arthur-Milchior left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Arthur-Milchior left a comment

Choose a reason for hiding this comment

david-allison Aug 22, 2024 •

edited

Loading

david-allison Aug 22, 2024 •

edited

Loading