zeal
zeal copied to clipboard
zealdocs
Adding improved support for keyboard navigation
Zeal is now working really well for me now; it's fast, and it doesn't take up additional space. The only thing I feel a bit missing is keyboard support for navigation. I understand this would not mean much importance for such a small application, but it still makes me wish that I don't need to lift my hands off my keyboard when I'm programming.
I appreciate any feedback, so thanks for mentioning it. If you could provide some specific examples of keyboard navigation improvements, I might be able to implement them.
I've already included the ability to use up/down arrow keys while typing the search query, because it seemed useful to me. So I suppose maybe other improvements for navigation within search results, like support for complex queries, could help even more... But I'm mostly guessing because I'm kind of a mouse person, so please provide some examples, if possible. I can't promise I'll find time to implement anything though. :)
Of course. For me Vim is my primary editor, so I'd like to have control over the navigation of the page by keys such as j, k , <C-b>, <C-f> and so on. aside from that it would also be nice to have a keyboard shortcut to switch focus between the search bar and the page.
First of all - @jkozera - AWESOME job. Dash-like app was one of few things I really miss from MacOS :) Anyway - regarding keyboard navigation. I'm using zeal in ubuntu/unity environment. And after using zeal for a while I have to say, that better support for keyboard navigation is really a must :) First of all - whenever zeal window is active, typing any letter should move focus to search input. Esc key should erase input When search input is empty, Esc should close windows. This one is very important, as when you will not close zeals window and move focus to another, global keyboard shortcut stops working - applications activator starts shaking, but window itself is not moved to the first plan. If you want any help from me on above, just let me know. I stoped programming in python/qt years ago, but maybe I will be able to fix something.
Thank you for your comments. Unfortunately at the moment I am too busy with other things to work actively on Zeal, and will probably not be able to implement any new features anytime soon. Code contributions are still welcome though. I will update README with project status shortly to reflect lack of active development.
A plus to this threat could be, add and button "back" (UIX) Some time I'm in a nesting reading, so I get deeper in the API documentation that when I want to return 3 o 2 functions back I don't know how to do it (in a easy way). I figure out I can "right click" and access the contextual menu and go back, but actually could be a great improvement some UIX for this stuff.
More or less like breadcrumb Back button a Share button (some time I want to sent some API info trough email or etc).
To add to these ideas, I think that ENTER should automatically focus the document pane (instead of needing to use TAB twice or thrice, depending on whether the input textbox is focused or the search results list is selected). The current behavior of ENTER displaying the selected documentation item from the list without defocusing the results list could be replaced by SPACEBAR. So ENTER to focus the document pane and SPACEBAR to select the highlighted item in the search list.
I’ve already opened issue #62 suggesting that the ‘/’ and ‘'’ keys copy mozilla’s behavior (search, search in-page links).
@killua99 , I have noticed that ALT-left and ALT-right for back/forward (copying web browsers) have recently been implemented, that’s good. @mlitwiniuk Also, to address request for ESC to close the zeal window, I normally just use zeal’s launch shortcut to close it and this works very well: on relaunching, the input textfield automatically has the search text highlighted so that you can just overwrite it or choose to type nothing and continue viewing the document you were reading before closing. Maybe the global shortcut becoming broken after closing the window was fixed before I ever heard about zeal’s existence ;-). But maybe other common shortcuts for closing and quitting, namely C-w (close window) and C-q (quit application) should be added.
I wonder if vimperator-like keyboard navigation would be possible here. (Personally I switched back to reading docs online in vimperator) That is going to be a large amount of work, I guess; not familiar with Qt I cannot help. I considered creating a Firefox plugin or XULRunner app, but that would run on OS X and compete with Dash, so am afraid that may not be allowed in-app download of Kapeli hosted docsets.
If implementing that in Zeal is practical, I'd expect its usability at the level of vimium, no need to match that of vimperator.
Btw a simple feature I would love is half-screen scrolling.
I think the best approach is to make all keybindings configurable. Also, adding some built-in settings (e.g. VIM-like, or web browser-like) should satisfy most users out of the box.
No any ETA though :)
+1 for support for configurable keybindings. I only use the mouse when I have no other option. I'd like to see keybindings for moving down and up the list. I prefer to use CtrlN (next) and Ctrl-P (previous) instead of the up and down arrow keys.
One way to move from the document window back to the search results is Ctrl+K then Tab.
Excellent!, this works. I would still like to change this as Ctrl-F or Ctrl-S is the typical search keyboard shortcut.
This would be awesome addition to the awesome tool. Here is a list of bare-minimum bindings that should make most vim users happy:
| Vi-like binding | Description | Equivalent default binding |
|---|---|---|
j |
Scroll one line down | Down Arrow |
k |
Scroll one line up | Up Arrow |
h |
Scroll left (horizontal) | Left Arrow |
l |
Scroll right (horizontal) | Right Arrow |
CTRL-d |
Scroll page down | PgDn |
CTRL-u |
Scroll page up | PgUp |
Looking through the source code:
There doesn't seem to be any keybinding for opening a tree on the docset list. This would be really nice.
I'm not sure what the Ctrl + %1 key is supposed to do. I know that Alt + %1 will switch between open tabs, but Ctrl?
Amazing program. I will continue looking through the code to see how all of the keyboard shortcuts could be possibly implemented.
The problem with the docset tree is that it's not really focused. Some key events are simply passed to it from the search input box. When the tree actually holds focus, then Right expands a tree node.
@trollixx Reminds me of my own implementation of that. My solution was to add a checkable menu item (with persisted state) to my existing "search settings" dropdown to allow the user to select how some of the keybindings which conflict would be interpreted.
That said, I didn't go as far as Left and Right. (Mainly just Home and End.)
I found a workaround for this issue:
I have a script that uses xdotool ::
xdotool mousemove 5 60 click --repeat 8 1
That will click the top member of the menu on the list. The repeat makes sure that it will work every time, but it will open up the menu. It's the only way I could make sure that it didn't click on a subsequent menu item instead, which would open up the doc. With my script that turns off the touchpad and hides the cursor that uses unclutter this will still still expand the element. Not sure how to get around that for now. I think figuring out how to make sure focus is always restored to the docset menu in the actual source would be the best bet.
#!/usr/bin/bash
xinput set-int-prop SynPS/2\ Synaptics\ TouchPad "Device Enabled" 8 0
unclutter -idle 0 -grab &
And I added it to my i3wm keybdinings with
bindsym $mod+z exec --no-startup-id /usr/local/bin/click-zeal
@trollixx No promises whatsoever, but would you be open to a PR to add support for vi/vim/less-style bindings?
If I find time, I might take a stab at this, but want to be certain that it would even be considered before making an effort.
@dsifford I've been pushing this down the line because it'd be better to move all shortcut management into one place, and then add support for profiles. That would allow users configure keyboard actions to their liking, as well as provide some some built-in options like browser-like, vi, etc.
If you want to contribute, that'd be greatly appreciated. We could have a more detailed discussion then.
@trollixx @dsifford Let me know if you want/need help. I'm open to contributing.
@trollixx Offloading keybinding customization into a user config seems like a good decision.
Not totally sure what the best approach would be in QT application. Are there examples of this in the wild that you find particularly compelling? Does QT have an interface that allows this natively? I haven't worked with QT in a few years so I'm sure you have a better handle on this than I do. Agree that it would prob be wise to be on the same page before diving in too deep in the weeds on this.
@dmocek If you'd like to champion this, feel free. My free time is limited to the weekends right now.
Sure. I'll start by gathering all of the shortcuts I can find and come up with a proposal.
Qt doesn't provide any built-in shortcut management solution. A while back I implemented something similar in another project, but haven't checked how useful that code can be.
I've completed the list of shortcuts. These are all I know at this point: https://github.com/dmocek/zeal-keyboard-shortcuts.
Hi everyone, thx for awesome app. Navigation like in vimium browser plugin would be killer feature, because it add possibility to "click" from keyboard to clipboard copy buttons and save snippet-like data directly from documentation. It's looks like doc + snippet combination for me
