forked from rvaiya/warpd
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathwarpd.scdoc
172 lines (125 loc) · 7.43 KB
/
warpd.scdoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
warpd(1)
# DESCRIPTION
A modal keyboard driven pointer manipulation program.
# SYNOPSIS
warpd [-f] [-l] [-v]
# OPTIONS
*-f*: Run warpd in the foreground (i.e do not daemonize). Mainly useful for debugging.
*-l*: Prints a list of valid keys which can be used as config values.
*-v*: Prints the current version.
# DESCRIPTION
warpd has three main modes which can be used to manipulate the pointer. The
primary mode is called 'normal mode' (A-M-c) and facilitates local pointer
movement using vi-like bindings (_h_ _j_ _k_ _l_). The other two modes, *hint*
and *grid* mode are used to effect larger movements across the screen and are
expected to be used in combination with normal mode to achieve the desired end.
For example, the user might activate warpd in hint mode (_A-M-x_) to pinpoint
the start of a text region before starting a drag operation (_v_) and
ultimately using normal mode to complete the selection. If the selection is a
large body of text, it may be desirable to activate grid (_g_) or hint (_x_)
mode for a second time to warp the pointer to the desired region's terminal
point.
See _CONFIG_OPTIONS_ for a comprehensive list of keys and their corresponding
configuration options (see also _USAGE_NOTES_).
A description of each mode follows:
## Normal Mode (A-M-c)
This is the default mode (and the endpoint of both grid and normal mode) which
is designed for short distance pointer manipulation. It is particularly useful
for manipulating popup menus and selecting text (see _Dragging_). The default
behaviour is vi-like. Pressing the mapped directional keys (default hjkl) moves
the cursor in a continuous fashion, but the pointer can also be warped to the edges
of the screen using the home (_H_), middle (_M_), and last (_L_) mappings (see
_CONFIG OPTIONS_). Finally, a numeric multiplier can be supplied to the
directional keys as an input prefix in order to move the cursor by a
proportional increment in the given direction (e.g 10j moves 10 units down).
## Hint Mode (A-M-x or simply 'x' within normal mode)
This mode populates the screen with a list of labels and allows the
user to immediately warp the pointer to a given location by pressing the
corresponding key sequence. It is similar to functionality provided by browser
plugins like Vimperator but works outside of the browser and indiscriminately
covers the entire screen. Once a target has been selected 'normal mode' is
entered for further manipulation.
*Note:* While it may at first be tempting to saturate the screen with hints,
the user is cautioned against this. A balance must be struck between hint size,
the number of hints and the size of the screen. Enough space must be left to
provide contextual awareness while enough hints must be present to facilitate
targetting UI elements without the need for too much adjustment. Once this
equilibrium has been achieved, using hint mode become second nature and is (in
the author's opinion) superior to grid mode for quickly pinpointing elements.
## Grid Mode ('A-M-g' or simply 'g' within normal mode)
By default grid mode divides the screen into a 2x2 grid. Each time a key
is pressed the grid shrinks to cover the targeted quadrant. The cursor is placed
in the middle of the grid.
covers the the desired target a mouse button (e.g 'm') can be pressed.
E.G
```
+--------+--------+ +--------+--------+
| | | | u | i | |
| u | i | |----m----+ |
M-x | | | u | j | k | |
-----> +--------m--------+ -----> +---------+ |
| | | | |
| j | k | | |
| | | | |
+--------+--------+ +--------+--------+
```
## Screen Selection Mode ('A-M-s' or simply 's' within normal mode)
This mode is intended for multi-screen setups and provides the user with a
dedicated set of hints for switching monitors and dropping them into normal
mode.
## Dragging
Pressing _v_ whilst in normal mode toggles a drag operation. The cursor can
then be warped around the screen as normal in order to select text or move
objects until the drag key is hit again or a mouse button is pressed.
Additionally, the *copy_and_exit* key (_c_) may be used to copy the selected
text to the system clipboard and terminate the current session.
# CONFIG OPTIONS
The following configuration options can be placed in *~/.config/warpd/config*
to modify the behaviour of the program. Each option must be specified on its
own line and have the format:
<option>: <value>
All values which contain more than one key are space delimited.
{opts}
# USAGE NOTES
The key to using warpd effectively is to learn when to exit normal mode. Much
of one's time at a computer is spent moving the mouse between windows,
interacting with UI elements, and reading text. It is in this mode of operation
that it makes sense to remain in normal mode.
Developing facility with the scroll and oneshot mouse buttons is key to
achieving this. For example, if you happen to have two documents open and wish
to switch between them, you can simply type _x fx_ (where _fx_ is a hint) if
normal mode is active. Scrolling can subsequently be achieved using _e_ and
_r_. Once you finally wish to type something you can do _x fx n_ to focus on
the UI element and exit.
Conversely, warpd can complement an input heavy workflow with its oneshot
functionality and dedicated activation keys (E.G _n_, _A-M-l_, _A-M-x_, etc).
It is important to note that warpd is not intended to replace mouse heavy
workflows and is inferior for precise rapid local movements. When confronted
with an IDE, or some other pointer driven crime against humanity, the author
still sometimes reach for his mouse.
## On Dragging
Activating discrete mode and pressing v can provide a familiar environment to a
_vi_ user but it is important to remember that cursor manipulation is
application agnostic and consequently ignorant of the text on the screen. All
movement is necessarily pixel based, consequently, drag + hint
mode can be a superior method for surgically selecting text (though it may at
first be less intuitive).
# CAVEATS
- Multiscreen support currently does not support hotplugging. This means that
you must restart warpd after making any changes to your screen configuration.
- For implementation reasons, the cursor position is not horizontally centered,
but to the right of the actual pointer. This generally isn't an issue,
but may become more noticeable as you increase _cursor_size_.
- Unplugging the keyboard while warpd is one of its active modes will cause
pandemonium. If you do this (don't :P), you may need to remotely ssh into
the machine or switch to a VT to kill the process.
- warpd uses Xinput for input processing to bypass certain limitation of the X
input system. A byproduct of this is that certain remapping tools will not
work (e.g xcape). If you are in the habit of making unorthodox changes to
your keymap (like remapping capslock to control/escape) you may want to try
an evdev based remapper like keyd (https://github.com/rvaiya/keyd).
- Programs which use Xinput to directly manipulate input devices may misbehave.
See [Issue #3](https://github.com/rvaiya/warpd/issues/3#issuecomment-628936249)
for details.
- Cursor hiding on macOS relies on a hack that some programs ignore (e.g iTerm).
Consequently the original cursor will sometimes overlap warpd's.