diff --git a/README.md b/README.md index ce8ad7e8..bc883b29 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,139 @@ # Kaleidoscope-MouseKeys -This is a plugin for [Kaleidoscope][fw], that adds support for mouse keys. +![status][st:stable] [![Build Status][travis:image]][travis:status] - [fw]: https://github.com/keyboardio/Kaleidoscope + [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-MouseKeys.svg?branch=master + [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-MouseKeys + + [st:stable]: https://img.shields.io/badge/stable-✔-black.svg?style=flat&colorA=44cc11&colorB=494e52 + [st:broken]: https://img.shields.io/badge/broken-X-black.svg?style=flat&colorA=e05d44&colorB=494e52 + [st:experimental]: https://img.shields.io/badge/experimental----black.svg?style=flat&colorA=dfb317&colorB=494e52 + +Have you ever wanted to control the mouse cursor from the comfort of your +keyboard? With this plugin, you can. While it may not replace the mouse in all +situations, there are plenty of cases where one will not have to lift their +hands off the keyboard just to nudge the mouse cursor away a little. + +Of course, there are a lot more one can do with the plugin than to nudge the +cursor! Mouse keys are provided for all four *and* diagonal movement; mouse +buttons; and a unique warping mechanism too. And not only these: the speed of +the cursor, the mouse wheel, and that of acceleration can all be configured to +match one's desired behaviour. + +## Using the plugin + +To use the plugin, simply include the header, make sure the `MouseKeys` object +is properly used, and place mouse keys on your keymap. It is best illustrated +with an example: + +```c++ +#include +#include + +// Somewhere in the keymap: +Key_mouseUp, Key_mouseDn, Key_mouseL, Key_mouseR, +Key_mouseBtnL, Key_mouseBtnR + +void setup() { + Kaleidoscope.use(&MouseKeys); + + Kaleidoscope.setup (); +} +``` + +## Keys provided by the plugin + +The plugin provides a number of keys one can put on the keymap, that allow +control of the mouse. They can be divided into a few groups: + +### Cursor movement + +The simplest set of keys are the mouse cursor movement keys. These move the +cursor one direction or the other, with speed and acceleration factored in. When +a mouse cursor movement key is held down, it will move `.speed` pixels each +`.speedDelay` milliseconds without acceleration. But when `.accelSpeed` is +non-zero (and it is not zero by default), the speed will increase by +`.accelSpeed` every `.accelDelay` milliseconds. Thus, unless configured +otherwise, holding a direction will move that way at increasing speed. + +One can hold more than one key down at the same time, and the cursor will move +towards a direction that is the combination of the keys held. For example, +holding the "mouse up" and "mouse right" keys together will move the cursor +diagonally up and right. + +The cursor movement keys are as follows: + +* `Key_mouseUp`, `Key_mouseDn`, `Key_mouseL`, `Key_mouseR`: Move the cursor up, + down, left, or right, respectively. +* `Key_mouseUpL`, `Key_mouseUpR`, `Key_mouseDnL`, `Key_mouseDnR`: Move the + cursor up-left, up-right, down-left, down-right, respectively. + +### Scroll wheel + +Controlling the scroll wheel is similarly simple. It does not have acceleration, +but one can control the speed with the `.wheelSpeed` and `.wheelDelay` +properties (see below). + +* `Key_mouseScrollUp`, `Key_mouseScrollDn`: Scroll the mouse wheel up or down, + respectively. + +### Buttons + +Buttons are even simpler than movement: there is no movement speed, nor +acceleration involved. One just presses them. + +* `Key_mouseBtnL`, `Key_mouseBtnM`, `Key_mouseBtnR`: The left, middle, and right + mouse buttons, respectively. + +### Warping + +Warping is one of the most interesting features of the plugin, and is a feature +unique to Kaleidoscope, as far as we can tell. The warping keys position the +mouse cursor within a quadrant of the screen on first press, and any subsequent +taps will warp within the previously selected quadrant. For example, pressing +the north-west warp key twice will first jump to the middle of the north-west +quadrant of your screen, then select the north-west quadrant of that, and jump +to the middle of it. + +To stop warping, use any other mouse key, or hit the "warp end" key. + +This features works out of the box on Windows and OSX. On Linux, a patch exists, +but has not been finalised and merged yet. + +The warping keys are the following: + +* `Key_mouseWarpNW`, `Key_mouseWarpNE`, `Key_mouseWarpSW`, `Key_mouseWarpSE`: + Warp towards the north-west, north-east, south-west, or south-east quadrants, + respectively. +* `Key_mouseWarpEnd`: End the warping sequence, resetting it to the default + state. Using any of the warping keys after this will start from the whole + screen again. + +## Plugin methods + +The plugin provides a `MouseKeys` object, with the following methods and +properties available: + +### `.speed` and `.speedDelay` + +> These two control the speed of the mouse cursor, when a movement key is held. +> The former, `.speed`, controls the amount of pixels the cursor moves, when it +> has to move, and defaults to 1. The latter, `.speedDelay` is the amount of +> time - in milliseconds - to wait between two movements, and defaults to 0, no +> delay. + +### `.accelSpeed` and `.accelDelay` + +> These two properties control the speed of acceleration. The former, +> `.accelSpeed`, controls how much the speed shall be increased at each step, +> while the second, `.accelDelay`, controls how often (in milliseconds) +> acceleration should be applied. +> +> They default to 1 pixel and 50 milliseconds, respectively. + +### `.wheelSpeed` and `.wheelDelay` + +> The last two properties supported by the plugin control the mouse wheel +> scrolling speed. The former, `.wheelSpeed`, controls the amount of ticks the +> wheel shall scroll, and defaults to 1. The second, `.wheelDelay`, controls the +> delay between two scroll events, and defaults to 50 milliseconds.