Move the documentation to `doc/plugin/MouseKeys.md`, sources under `src/kaleidoscope/plugin/` (appropriately namespaced). This is in preparation of merging plugins into a single monorepo. Signed-off-by: Gergely Nagy <algernon@keyboard.io>pull/365/head
Gergely Nagy
6 years ago
parent
b71ab5f1b3
commit
0683faeb79
@ -0,0 +1,246 @@
|
||||
# Kaleidoscope-MouseKeys
|
||||
|
||||
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 in your Sketch, tell the firmware
|
||||
to use the `MouseKeys` object, and place mouse keys on your keymap. It is best
|
||||
illustrated with an example:
|
||||
|
||||
```c++
|
||||
#include <Kaleidoscope.h>
|
||||
#include <Kaleidoscope-MouseKeys.h>
|
||||
|
||||
// Somewhere in the keymap:
|
||||
Key_mouseUp, Key_mouseDn, Key_mouseL, Key_mouseR,
|
||||
Key_mouseBtnL, Key_mouseBtnR
|
||||
|
||||
KALEIDOSCOPE_INIT_PLUGINS(MouseKeys);
|
||||
|
||||
void setup() {
|
||||
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,
|
||||
see [below](#accelspeed-and-acceldelay)), 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.
|
||||
* `Key_mouseScrollL`, `Key_mouseScrollR`: Scroll the mouse wheel left or right,
|
||||
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`, `Key_mouseBtnP`,
|
||||
`Key_mouseBtnN`: The left, middle, right, previous, and next 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 sector of the screen on first press, and any subsequent
|
||||
taps will warp within the previously selected sector. For example, pressing the
|
||||
north-west warp key twice will first jump to the middle of the north-west
|
||||
sector of your screen, then select the north-west sector of that, and jump to
|
||||
the middle of it.
|
||||
|
||||
To stop warping, use any other mouse key, or hit the "warp end" key.
|
||||
|
||||
### Warp grid size
|
||||
|
||||
The warp grid size determines how MouseKeys partitions the screen to select the
|
||||
next position to jump to when pressing a warp key. The plugin provides two grid
|
||||
sizes to choose from: a *2x2* grid that splits the screen into quadrants, and a
|
||||
*3x3* grid with nine cells similar to a navigation feature included with some
|
||||
speech recognition software. By default, the plugin splits the screen into the
|
||||
2x2 grid.
|
||||
|
||||
To change the warp grid size, call the plugin's `setWarpGridSize()` method:
|
||||
|
||||
```c++
|
||||
MouseKeys.setWarpGridSize(MOUSE_WARP_GRID_3X3);
|
||||
```
|
||||
|
||||
#### 2x2 grid
|
||||
|
||||
As described above, MouseKeys warps the pointer using a grid model that reflects
|
||||
locations on the screen. By default, the plugin uses a 2x2 grid. To understand
|
||||
how warping works, examine this diagram of a screen split into that 2x2 grid:
|
||||
|
||||
+-----------------------|-----------------------+
|
||||
| | | |
|
||||
| G | tab | |
|
||||
| | | |
|
||||
|-----------|-----------| tab |
|
||||
| | | |
|
||||
| B | esc | |
|
||||
| | | |
|
||||
+-----------------------|-----------------------+
|
||||
| | |
|
||||
| | |
|
||||
| | |
|
||||
| B | esc |
|
||||
| | |
|
||||
| | |
|
||||
| | |
|
||||
+-----------------------|-----------------------+
|
||||
|
||||
Each quadrant is labed with a key that, when pressed, moves the mouse pointer
|
||||
to the center of that quadrant. With this layout, pressing <kbd>G</kbd> warps
|
||||
the pointer to the top-left quadant. Then, the plugin "zooms" into that sector
|
||||
with a smaller grid so that the next warp key pressed jumps the pointer more
|
||||
precisely within the sector. In this case, if we press <kbd>esc</kbd> next,
|
||||
the pointer warps to the bottom-right corner within that quadrant.
|
||||
|
||||
The warping keys for the 2x2 grid 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.
|
||||
|
||||
#### 3x3 grid
|
||||
|
||||
A 3x3 warp grid assigns a key to each of nine sectors of the screen. The next
|
||||
diagram shows a screen with a key label that warps to each sector. As we can
|
||||
see, pressing <kbd>W</kbd> warps the pointer into the top-left sector, and
|
||||
pressing <kbd>V</kbd> warps to the bottom-right corner within that sector:
|
||||
|
||||
+-----------------|-----------------|-----------------+
|
||||
| W | E | R | | |
|
||||
|-----|-----|-----| | |
|
||||
| S | D | F | E | R |
|
||||
|-----|-----|-----| | |
|
||||
| X | C | V | | |
|
||||
+-----------------|-----------------|-----------------+
|
||||
| | | |
|
||||
| | | |
|
||||
| S | D | F |
|
||||
| | | |
|
||||
| | | |
|
||||
+-----------------|-----------------|-----------------+
|
||||
| | | |
|
||||
| | | |
|
||||
| X | C | V |
|
||||
| | | |
|
||||
| | | |
|
||||
+-----------------|-----------------|-----------------+
|
||||
|
||||
To use a 3x3 warp grid, we may need to remap some keys. A suggested warp key
|
||||
mapping is shown below on the left side of a keyboard with a QWERTY layout:
|
||||
|
||||
W | E | R T A - End Warping (Key_mouseWarpEnd)
|
||||
---|---|--- W - Warp NW Sector (Key_mouseWarpNW)
|
||||
A S | D | F G E - Warp N Sector (Key_mouseWarpN)
|
||||
---|---|--- R - Warp NE Sector (Key_mouseWarpNE)
|
||||
X | C | V B S - Warp E Sector (Key_mouseWarpE)
|
||||
D - Warp/Zoom Center (Key_mouseWarpIn)
|
||||
F - Warp W Sector (Key_mouseWarpW)
|
||||
K - Warp SE Sector (Key_mouseWarpSE)
|
||||
C - Warp S Sector (Key_mouseWarpS)
|
||||
V - Warp SW Sector (Key_mouseWarpSW)
|
||||
T - Right Click (Key_mouseBtnR)
|
||||
G - Left Click (Key_mouseBtnL)
|
||||
B - Middle Click (Key_mouseBtnM)
|
||||
|
||||
This example layout replaces the default directional mouse keys and sets the
|
||||
warp keys in a comfortable position for a warp-only configuration. Of course,
|
||||
a Kaleidoscope user may retain the directional keys and map the warp keys
|
||||
elsewhere according to his or her liking.
|
||||
|
||||
A 3x3 warp grid layout contains all of the keys from the 2x2 grid layout with
|
||||
the following additions:
|
||||
|
||||
* `Key_mouseWarpN`, `Key_mouseWarpE`, `Key_mouseWarpS`, `Key_mouseWarpW`:
|
||||
Warp towards the north, east, south, and west sectors, respectively.
|
||||
* `Key_mouseWarpIn`: Warp to the center sector of the grid. The plugin will
|
||||
continue to "zoom" into center of the current cell with each consecutive
|
||||
press of this key.
|
||||
|
||||
## 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.
|
||||
|
||||
### `.setSpeedLimit`
|
||||
|
||||
> This method sets the maximum speed after which acceleration stops.
|
||||
> The default is 127, and the minimum value is 16 (things will not work
|
||||
> properly below 16).
|
||||
|
||||
### `.setWarpGridSize`
|
||||
|
||||
> This method changes the size of the grid used for [warping](#warping). The
|
||||
> following are valid sizes: `MOUSE_WARP_GRID_2X2`, `MOUSE_WARP_GRID_3X3`
|
||||
@ -0,0 +1,55 @@
|
||||
/* Kaleidoscope-MouseKeys - Mouse keys for Kaleidoscope.
|
||||
* Copyright (C) 2017-2018 Keyboard.io, Inc.
|
||||
*
|
||||
* This program is free software: you can redistribute it and/or modify it under
|
||||
* the terms of the GNU General Public License as published by the Free Software
|
||||
* Foundation, version 3.
|
||||
*
|
||||
* This program is distributed in the hope that it will be useful, but WITHOUT
|
||||
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
||||
* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
|
||||
* details.
|
||||
*
|
||||
* You should have received a copy of the GNU General Public License along with
|
||||
* this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "Kaleidoscope.h"
|
||||
#include "MouseKeyDefs.h"
|
||||
#include "MouseWarpModes.h"
|
||||
|
||||
namespace kaleidoscope {
|
||||
namespace plugin {
|
||||
class MouseKeys_ : public kaleidoscope::Plugin {
|
||||
public:
|
||||
MouseKeys_(void) {}
|
||||
|
||||
static uint8_t speed;
|
||||
static uint16_t speedDelay;
|
||||
static uint8_t accelSpeed;
|
||||
static uint16_t accelDelay;
|
||||
static uint8_t wheelSpeed;
|
||||
static uint16_t wheelDelay;
|
||||
|
||||
static void setWarpGridSize(uint8_t grid_size);
|
||||
static void setSpeedLimit(uint8_t speed_limit);
|
||||
|
||||
EventHandlerResult onSetup();
|
||||
EventHandlerResult beforeReportingState();
|
||||
EventHandlerResult afterEachCycle();
|
||||
EventHandlerResult onKeyswitchEvent(Key &mappedKey, byte row, byte col, uint8_t keyState);
|
||||
|
||||
private:
|
||||
static uint8_t mouseMoveIntent;
|
||||
static uint32_t endTime;
|
||||
static uint32_t accelEndTime;
|
||||
static uint32_t wheelEndTime;
|
||||
|
||||
static void scrollWheel(uint8_t keyCode);
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
extern kaleidoscope::plugin::MouseKeys_ MouseKeys;
|
||||
@ -0,0 +1,74 @@
|
||||
/* Kaleidoscope-MouseKeys - Mouse keys for Kaleidoscope.
|
||||
* Copyright (C) 2017-2018 Keyboard.io, Inc.
|
||||
*
|
||||
* This program is free software: you can redistribute it and/or modify it under
|
||||
* the terms of the GNU General Public License as published by the Free Software
|
||||
* Foundation, version 3.
|
||||
*
|
||||
* This program is distributed in the hope that it will be useful, but WITHOUT
|
||||
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
||||
* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
|
||||
* details.
|
||||
*
|
||||
* You should have received a copy of the GNU General Public License along with
|
||||
* this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "Arduino.h"
|
||||
#include "MouseWarpModes.h"
|
||||
|
||||
// Warping commands
|
||||
|
||||
#define WARP_END 1
|
||||
#define WARP_UP 2
|
||||
#define WARP_DOWN 4
|
||||
#define WARP_LEFT 8
|
||||
#define WARP_RIGHT 16
|
||||
|
||||
// apparently, the mac discards 15% of the value space for mouse movement.
|
||||
// need to test this on other platforms
|
||||
|
||||
#define MAX_WARP_WIDTH 32767
|
||||
#define MAX_WARP_HEIGHT 32767
|
||||
|
||||
#define WARP_ABS_TOP 0
|
||||
#define WARP_ABS_LEFT 0
|
||||
|
||||
// Mouse acceleration
|
||||
|
||||
namespace kaleidoscope {
|
||||
namespace plugin {
|
||||
|
||||
class MouseWrapper_ {
|
||||
public:
|
||||
MouseWrapper_(void);
|
||||
|
||||
static void begin(void);
|
||||
static void move(int8_t x, int8_t y);
|
||||
static void warp(uint8_t warp_cmd);
|
||||
static void reset_warping();
|
||||
static void pressButton(uint8_t button);
|
||||
static void release_button(uint8_t button);
|
||||
static uint8_t accelStep;
|
||||
static uint8_t speedLimit;
|
||||
static uint8_t subpixelsPerPixel;
|
||||
static uint8_t warp_grid_size;
|
||||
|
||||
private:
|
||||
static uint16_t next_width;
|
||||
static uint16_t next_height;
|
||||
static uint16_t section_top;
|
||||
static uint16_t section_left;
|
||||
static boolean is_warping;
|
||||
|
||||
static uint8_t acceleration(uint8_t cycles);
|
||||
static void begin_warping();
|
||||
static void end_warping();
|
||||
static void warp_jump(uint16_t left, uint16_t top, uint16_t height, uint16_t width);
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
extern kaleidoscope::plugin::MouseWrapper_ MouseWrapper;
|
||||
Loading…
Reference in new issue