keynav

Table of Contents

keynav is a piece of software that lets you place your cursor as well as perform left/right click/drag all with keyboard.

1. startup script

keynav "loadconfig ~/.config/keynav/keynavrc"

2. configuration

An copy of a exmaple configuration is under usr/share/doc/keynav/keynavrc or usr/share/doc/keynav/examples/keynavrc.jordan (there’s 4 places that are different)

I copied the default because I want to use super+semicolon to start keynav. C-; conflicts with emacs’ comment-line which I use a lot. S-; conflicts with i3’s default right container which I had remapped.

# This is a keynavrc file. Yours should live in
# $HOME/.keynavrc
#
# Lines beginning with '#' are comments.
# Format is:
#   keysequence cmd1,cmd2,cmd3...
#
# Other special values are:
#   'clear' on a line by itself (no quotes) will erase all keybindings
#   (including the defaults)
#   'daemonize' on a line by itself (no quotes) will make keynav background
#   after parsing the configfile and having no critical errors.
#
# The 'start' command alone is handled specially, in that any key sequence
# mapped to 'start' will be grabbed when keynav starts up so you can invoke it
# to activate keynav. The remaining keys are only recognized while keynav is
# active
#
# Project page; http://www.semicomplete.com/projects/keynav

# Use 'clear' to blow away any previous keybindings
clear
# Use 'daemonize' to background ourselves.
#daemonize

# ctrl+semicolon start
Return warp,click 1,end
super+semicolon start
Escape end
ctrl+bracketleft end
h cut-left
j cut-down
k cut-up
l cut-right
y cut-left,cut-up
u cut-right,cut-up
b cut-left,cut-down
n cut-right,cut-down
shift+h move-left
shift+j move-down
shift+k move-up
shift+l move-right
shift+y move-left,move-up
shift+u move-right,move-up
shift+b move-left,move-down
shift+n move-right,move-down
space warp,click 1,end
semicolon warp,end
1 click 1
2 click 2
3 click 3

# Zoom to the current window
w windowzoom

# Zoom to the cursor location with a given height and width
c cursorzoom 200 200

# Handy for holding ctrl while using keynav:
ctrl+h cut-left
ctrl+j cut-down
ctrl+k cut-up
ctrl+l cut-right
ctrl+y cut-left,cut-up
ctrl+u cut-right,cut-up
ctrl+b cut-left,cut-down
ctrl+n cut-right,cut-down

# Record keynav actions
q record
shift+at playback
### Example using the 'sh' command.
# Make firefox the active window
f sh "xdotool windowactivate $(xdotool search -title -- '- Mozilla Firefox')", end
# Make a new tab in google chrome:
t sh "xdotool windowactivate $(xdotool search --title -- '- Google Chrome' | head -1); xdotool key ctrl+t",end
# Paste
v sh "xdotool key shift+Insert"

### Drag examples
# Start drag holding the left mouse button
#q drag 1
# Start drag holding middle mouse + control and shift
#w drag 2 ctrl+shift

### History
a history-back

### Example of cut and move without the default values
#h cut-left .75
#j cut-down .75
#k cut-up .75
#l cut-right .75
#shift+h move-left .50
#shift+j move-down .50
#shift+k move-up .50
#shift+l move-right .50

### Example using a 2-row, 3-column grid,
# mapped to Insert/Home/PageUp/etc...
#6 grid 2x3
#Insert cell-select 1x1
#Home cell-select 1x2
#Prior cell-select 1x3   # PageUp
#Delete cell-select 2x1
#End cell-select 2x2
#Next cell-select 2x3   # PageDown

### Example using a 3x3 grid with nethack-vi keys
#ctrl+semicolon start, grid 3x3
#h cell-select 2x1      # left
#j cell-select 3x2      # down
#k cell-select 1x2      # up
#l cell-select 2x3      # right
#y cell-select 1x1      # up-left
#u cell-select 1x3      # up-right
#b cell-select 3x1      # down-left
#n cell-select 3x3      # down-right
#period cell-select 2x2 # center

3. Tool intuition

3.1. Cutting intuition

You can think of going h,j,k,l (left, down, up, right) as cutting the opposite out or focus on only the “left” side. The primtives y,u,b,n (quadrants left top, right top, left bottom, right bottom) extends to this intuition nicely.

In this intuition you typically focus on the comparison of the “currently focused area” and “target area”, i.e. which little rectangle of the reference grid the target area is in, which could be a bit awkward to start with, as there are in total 8 points (to define each area) involved

3.2. Center moving intuition

You can think of going h,j,k,l as moving the center point {left, down, up, right}.

In this intuition you typically rely on feedback of where is your center point with respect to your target area: if target are is to the left of your center point, you go left(h), if target area is to the right, you go right (l), and the current focus area (the big white box) as well as cutting provides an heuristic to make the movement smaller more accurate. The center vertical and horizontal lines are usually what you focus on for that comparison

In this intuition you only need to focus on the center and move relatively to the target, which is indeed lighter mental load. y,u,b,n in this intuition corresponds to moving diagonally, which may be a bit strange as your screen is usually not a square but a rectangle in 16:9 or larger ratio, making estimation of where the center is moving a bit harder than vertical/horizontal movement.(and there’s no reference line for that)

4. Licencing

This software seems to be proprietary on first sight; In the git repo the licence is “all right reserved”.

However, redistribution and use in source and binary are permitted if “the copyright claim is copied” and “author’s name not used to promote derived work”, and the “AS IS” clause make this copyright licence looks a lot like MIT Licence stated less clearly.

Also, the package is in ubuntu’s apt universe repository, meaning it is “community-maintained free and open-source software”, according to official documentation

To conclude, I think this software is a FOSS with MIT-like terms and is safe to be used like other MIT licenced software.

5. caveats

The default configuration seems to be based on UK keyboard

Backlinks

desktop keybindings

This set of keybinding refers to my current (Wed Mar 13 19:58:08 2024) desktop setup with i3, keynav, and KDE plasma

  • meta = super = S
  • when shift is involved, I go with the shifted char and omit shift, i.e. shift-q -> Q
app keybinding what they do
Wacom    
  S-C-f map to fullscreen
  S-C-1 map to screen 1
  S-C-2 map to screen 2
  S-C-m toggle between screens
keynav    
  S-; start

Author: Linfeng He

Created: 2024-04-03 Wed 20:17