Non-touch DPad improvements, largely kindle.

[Commodore64user]

as discussed in #11295, this PR should improve DPad support on older non-touch kindles.

It re-maps dPad to:

Up or Down: content selection (used for dict lookup, highlights and more)
Left: previous chapter
Right: next chapter

with the merge of #11802 ScreenKB would become a modifier key which allows shortcuts on kindle 4, the following are currently supported inside reader, for both fixed and flowable documents:

ScreenKB + Up: table of contents
ScreenKB + Left: bookmarks
ScreenKB + Right: bookmark current page
ScreenKB + Down: save current location to history
ScreenKB + Back: open previous document (supported on filemanager too)
ScreenKB + Home turn wifi on/off (supported on filemanager too)
ScreenKB + LeftPgBack/LeftPgFwd Previous/next page link (useful for footnotes)
ScreenKB + RightPgBack/RightPgFwd panning (with crengine and when in continuous mode only, normal page turning otherwise)

other shortcuts should be implemented soon in other PRs, for example, #11802 will introduce screenshots via

ScreenKB + Menu on kindle 4 or
Alt + Shift + G on all other non-touch kindles

In order to make content selection even better (as seen here #11749 (comment)), the following user adjustable settings (bottom three) have been added to all non-touch devices, although all other non-touch (not kindles) must trigger content selection from the menu.

once a user has entered "content selection" (via Up, Down or from menu) dPad keys become navigational and the following shortcuts become available. Note: although not introduced here, users with kindles with keyboards can also use this by replacing ScreenKB with Shift

ScreenKB + Up: move up by 20% of screen height (length, sigh...whatever)
ScreenKB + Left: move left by 20% of screen width
ScreenKB + Right: move right by 20% of screen width
ScreenKB + Down: move down by 20% of screen height

TL:DR this should make content selection (mentioned here #9063), dictionary lookups, highlighting (mentioned here #4329), link following (mentioned here #6562), text search just a tad lot better.
closes #11295

---

This change is 

[Commodore64user]

Current state of affairs:

Left/Right keys have been repurposed to 'Previous/Next Chapter' (on both readerrolling and readerpaging) -- Previous behaviour here was redundant 'Previous/Next Page' (this change seems inoffensive to all)

ScreenKB key (unique to K4) has been mapped to ToC (for both ePubs and PDFs) has been turned to a modifier key as of #11802 -- Previously unutilized.

Up/Down keys have been repurposed to 'Content selection' (on readerrolling ONLY, i.e ePubs) -- Previous behaviour was redundant 'Previous/Next Page' when in page mode, and 'Panning' when in continuous mode (this specific case has some, splitting hairs).

Regarding the importance of 'content selection': Currently the only way to do a dictionary lookup or start highlighting a passage requires you to: "Press Menu button > select page with text (this may take a few presses depending on where you last were on the menu) > press Up > Start content selection" and finally guide the little cross to where you need it to be. It can easily take a minimum of 4-5 button presses before you can control the cross (content selection) to find out what an unfamiliar word means. And this is not limited to just dictionary lookups, but to all functionality that requires the selection of text, i.e Wikipedia, View HTML, Translate, etc.

So if it is so amazing and solves all your problems, why not add it to readerpaging too? Well to quote @Frenzie, "A PDF page is typically taller than the screen, meaning it'll take [at least] two page turns to get through fully.", or in other words, that panning behaviour is strictly necessary.

So what are our options then? well the short/simple answer would be to break panning for continuous mode in lieu of a better experience. The more difficult option, to let the user decide via menu settings. If the latter, one could offer different mapping to both Up and Down independently, for example: Up could be "bookmark current page" and Down would be "content selection"

could look something like this (note that in this example, user cannot remap down/left/right keys)

[  ] Use up/down keys for page-turning/panning
     Up key mapping ‣            -- ( greyed out when above option selected)

where Up key mapping contains:

[  ] bookmark current page
[  ] go to page
... etc

[Frenzie]

So if it is so amazing and solves all your problems, why not add it to readerpaging too? Well to quote @Frenzie, "A PDF page is typically taller than the screen, meaning it'll take [at least] two page turns to get through fully.", or in other words, that panning behaviour is strictly necessary.

Panning behavior isn't really the right word. It simply goes per screen height instead of per page. My point isn't that you can't change things since the screen height behavior is simply the desired next page behavior, but that you have to make sure you don't break things.

[Commodore64user]

Panning behavior isn't really the right word. It simply goes per screen height instead of per page. My point isn't that you can't change things since the screen height behavior is simply the desired next page behavior, but that you have to make sure you don't break things.

well that is what is called in the code, and panning (with a camera) is slowly moving it from left to right (or up-down, or viceversa) to capture a whole scene that does not fit in one frame, like in panoramas. This is a sort of similar idea.

But anyway, we are in agreement that for PDFs up/down should not be changed (or at least it should remain that way by default)

[Commodore64user]

For reference, I am posting this here #4329 (comment) since I keep going on about how wonderful the button mapping on stock kindle is, for those unfamiliar with it

The original software provides "adding comments", and "highlighting", [dictionary lookup and footnote/links navigation]. The first one is in my eyes unbearable - too much fiddling with the arrow keys to select the single characters. It's a bit like writing SMS back in the days. Which leaves "highlighting" as the only viable use case (in my opinion) [all other three cases as viable].

It works like this:

• I am reading a document
• to enter highlighting I press either the "up" or "down" arrow key
• pressing "up" positions a blinking cursor on the lowest possible text position (usually the footer)
• pressing "down" positions the blinking cursor at the very top e.g. in front of the first character
• also a little help text box is displayed saying "press the middle button" to start selecting
• this text is positioned at top top when the cursor is at the bottom and vice versa
• I can now move the cursor around to the position where I want to start highlighting
• In the middle of the arrow keys is an other button which usually starts the KOReader page menu (where I can e.g. change the screen orientation)
• When I am in "blinking cursor" aka "selection" mode, this middle button on the Kindle almost starts the selection
• since the original software allows to "add notes" or "to highlight" the little help text box changes to a dialog asking "do you want to add notes or highlight?" I select "highlight" (since I think taking notes is not really useful this extra dialog could go, pressing the "middle" key could directly start "highlighting")
• I can now use the "right" arrow to select the text. the behaviour after pressing the middle key is like holding the Shift key on a keyboard and than using the keyboard arrow keys to select.
• the little help text box now says "press middle button" to stop selection
• When I do this in the little help text box I am asked if I want to finish the selection or not
• I choose "yes"
• I am then still in the "moving cursor" mode. The help text again says "press middle button" to start the selection so I could start over selecting something else.
• to go back to reading mode i press the "back" key

edit: well this largely describes the selection of text not the actual button mapping but still interesting to keep in mind.

[Frenzie]

well that is what is called in the code

I don't believe that's what it's called in the code. Panning is the act of arbitrarily panning, not the act of turning a page in continuous/scroll mode.

But anyway, we are in agreement that for PDFs up/down should not be changed (or at least it should remain that way by default)

I'm not at all sure that I'm in agreement though. The crucial factor is that it should remain usable, which means turning the page per screen and not per page is the thing that must remain, since otherwise you couldn't read.

[Commodore64user]

I don't believe that's what it's called in the code. Panning is the act of arbitrarily panning, not the act of turning a page in continuous/scroll mode.

Oops, yes you are right. I was assuming rolling and paging were using the same named function alas, they are not.

The crucial factor is that it should remain usable, which means turning the page per screen and not per page is the thing that must remain, since otherwise you couldn't read.

As of now, that is the case.

[Frenzie]

As of now, that is the case.

But what about the dictionary lookups and highlighting? The point is it should be properly usable while I get the feeling you're interpreting that restrictively in some manner. :-) Full page turns are of lesser importance if a choice is necessary.

[Commodore64user]

As of now, that is the case.

But what about the dictionary lookups and highlighting? The point is it should be properly usable while I get the feeling you're interpreting that restrictively in some manner. :-) Full page turns are of lesser importance if a choice is necessary.

What i was thinking was, to match the changes for readingpaging with those of readingrolling (up/down calls content selection) and to reassign the page turn ones to what up/down currently does???

[Frenzie]

What i was thinking was, to match the changes for readingpaging with those of readingrolling (up/down calls content selection) and to reassign the page turn ones to what up/down currently does???

To my knowledge page up/down work exactly as they should. Is that not the case? The important thing is that it works. You can't necessarily match them conceptually.

[Commodore64user]

waiting for @yparitcher to check this... and give his blessing

[yparitcher]

It looks that all the key_events now call events instead of new functions, so that looks good on my end.

[Commodore64user]

support LPg removed from "Panning"

[Commodore64user]

Last minute addition of link following, found here #6562

[Commodore64user]

We are good to go here 👍.

[Commodore64user]

Thank you to everyone who provided help, comments, feedback or mental support.

[poire-z]

I guess all the info in your posts above about the key combinations => action could be copied into a NT dedicated page on our Wiki (or added to one if it already exists).

[Frenzie]

If the info in the OP is up to date I'll also copy it into the release notes.

[Commodore64user]

If the info in the OP is up to date I'll also copy it into the release notes.

Of course it is up to date. Documentation must be released at the same time as the product. We are not amateurs here.

[Commodore64user]

Btw in honour of our maintainers, the next two releases should be "KOReader tiger roll" (or tiger bloomer or tiger bread) and "KOReader butter croissant".