Move the documentation to `doc/plugin/Macros.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
4a77929a26
commit
c27fbfa3e8
@ -0,0 +1,183 @@
|
||||
# Kaleidoscope-Macros
|
||||
|
||||
Macros are a standard feature on many keyboards and Kaleidoscope-powered ones
|
||||
are no exceptions. Macros are a way to have a single key-press do a whole lot of
|
||||
things under the hood: conventionally, macros play back a key sequence, but with
|
||||
Kaleidoscope, there is much more we can do. Nevertheless, playing back a
|
||||
sequence of events is still the primary use of macros.
|
||||
|
||||
Playing back a sequence means that when we press a macro key, we can have it
|
||||
play pretty much any sequence. It can type some text for us, or invoke a
|
||||
complicated shortcut - the possibilities are endless!
|
||||
|
||||
In Kaleidoscope, macros are implemented via this plugin. You can define upto 256 macros.
|
||||
|
||||
## Using the plugin
|
||||
|
||||
To use the plugin, we need to include the header, tell the firmware to `use` the
|
||||
plugin, place macros on the keymap, and create a special handler function
|
||||
(`macroAction`) that will tell the plugin what shall happen when macro keys are
|
||||
pressed. It is best illustrated with an example:
|
||||
|
||||
```c++
|
||||
#include <Kaleidoscope.h>
|
||||
#include <Kaleidoscope-Macros.h>
|
||||
|
||||
// Give a name to the macros!
|
||||
enum {
|
||||
MACRO_MODEL01,
|
||||
MACRO_HELLO,
|
||||
MACRO_SPECIAL,
|
||||
};
|
||||
|
||||
// Somewhere in the keymap:
|
||||
M(MACRO_MODEL01), M(MACRO_HELLO), M(MACRO_SPECIAL)
|
||||
|
||||
// later in the Sketch:
|
||||
const macro_t *macroAction(uint8_t macroIndex, uint8_t keyState) {
|
||||
switch (macroIndex) {
|
||||
case MACRO_MODEL01:
|
||||
return MACRODOWN(I(25),
|
||||
D(LeftShift), T(M), U(LeftShift), T(O), T(D), T(E), T(L),
|
||||
T(Spacebar),
|
||||
W(100),
|
||||
T(0), T(1) );
|
||||
case MACRO_HELLO:
|
||||
if (keyToggledOn(keyState)) {
|
||||
return Macros.type(PSTR("Hello "), PSTR("world!"));
|
||||
}
|
||||
break;
|
||||
case MACRO_SPECIAL:
|
||||
if (keyToggledOn(keyState)) {
|
||||
// Do something special
|
||||
}
|
||||
break;
|
||||
}
|
||||
return MACRO_NONE;
|
||||
}
|
||||
|
||||
KALEIDOSCOPE_INIT_PLUGINS(Macros);
|
||||
|
||||
void setup() {
|
||||
Kaleidoscope.setup ();
|
||||
}
|
||||
```
|
||||
|
||||
## Keymap markup
|
||||
|
||||
### `M(id)`
|
||||
|
||||
> Places a macro key on the keymap, with the `id` number (0 to 255) as identifier. Whenever this key
|
||||
> has to be handled, the `macroAction` overrideable function will be called,
|
||||
> with the identifier and key state as arguments.
|
||||
>
|
||||
> It is recommended to give a *name* to macro ids, by using an `enum`.
|
||||
|
||||
## Plugin methods
|
||||
|
||||
The plugin provides a `Macros` object, with the following methods and properties available:
|
||||
|
||||
### `.play(macro)`
|
||||
|
||||
> Plays back a macro, where a macro is a sequence created with the `MACRO()`
|
||||
> helper discussed below. This method will be used by the plugin to play back
|
||||
> the result of the `macroAction()` method, but is used rarely otherwise.
|
||||
>
|
||||
> The `macro` argument must be a sequence created with the `MACRO()` helper!
|
||||
|
||||
### `.type(strings...)`
|
||||
|
||||
> In cases where we only want to type some strings, it is far more convenient to
|
||||
> use this method: we do not have to use the `MACRO()` helper, but just give
|
||||
> this one a set of strings, and it will type them for us on the keyboard. We
|
||||
> can use as many strings as we want, and all of them will be typed in order.
|
||||
>
|
||||
> Each string is limited to a sequence of printable ASCII characters. No
|
||||
> international symbols, or unicode, or anything like it: just plain ASCII.
|
||||
>
|
||||
> Each of `strings` arguments must also reside in program memory, and the
|
||||
> easiest way to do that is to wrap the string in a `PSTR()` helper. See the
|
||||
> program code at the beginning of this documentation for an example!
|
||||
|
||||
### `.row`, `.col`
|
||||
|
||||
> The `row` and `col` properties describe the physical position a macro was
|
||||
> triggered from if it was triggered by a key. The playback functions
|
||||
> do not use these properties, but they are available, would one want to create
|
||||
> a macro that needs to know which key triggered it.
|
||||
>
|
||||
> When the macro was not triggered by a key the value of these properties are
|
||||
> unspecified.
|
||||
|
||||
## Macro helpers
|
||||
|
||||
Macros need to be able to simulate key down and key up events for any key - even
|
||||
keys that may not be on the keymap otherwise. For this reason and others, we
|
||||
need to define them in a special way, using the `MACRO` helper (or its
|
||||
`MACRODOWN()` variant, see below):
|
||||
|
||||
### `MACRO(steps...)`
|
||||
|
||||
> Defines a macro, that is built up from `steps` (explained below). The plugin
|
||||
> will iterate through the sequence, and re-play the steps in order.
|
||||
>
|
||||
> Note: In older versions of the Macros plugin, the sequence of steps had to end
|
||||
> with a special step called END. This is no longer required. Existing macros
|
||||
> that end with END will still work correctly, but new code should not use END;
|
||||
> usage of END is deprecated.
|
||||
|
||||
### `MACRODOWN(steps...)`
|
||||
|
||||
> The same as the `MACRO()` helper above, but it will create a special sequence,
|
||||
> where the steps are only played back when the triggering key was just pressed.
|
||||
> That is, the macro will not be performed when the key is released, or held, or
|
||||
> not pressed at all.
|
||||
>
|
||||
> Use this over `MACRO()` when you only want to perform an action when the key
|
||||
> actuates, and no action should be taken when it is held, released, or when it
|
||||
> is not pressed at all. For a lot of macros that emit a sequence without any
|
||||
> other side effects, `MACRODOWN()` is usually the better choice.
|
||||
>
|
||||
> Can only be used from the `macroAction()` overrideable method.
|
||||
|
||||
## `MACRO` steps
|
||||
|
||||
Macro steps can be divided into two groups:
|
||||
|
||||
### Delays
|
||||
|
||||
* `I(millis)`: Sets the interval between steps to `millis`. By default, there is
|
||||
no delay between steps, and they are played back as fast as possible. Useful
|
||||
when we want to see the macro being typed, or need to slow it down, to allow
|
||||
the host to process it.
|
||||
* `W(millis)`: Waits for `millis` milliseconds. For dramatic effects.
|
||||
|
||||
### Key events
|
||||
|
||||
Key event steps have three variants: one that prefixes its argument with `Key_`,
|
||||
one that does not, and a third that allows for a more compact - but also more
|
||||
limited - representation. The first are the `D`, `U`, and `T` variants, the
|
||||
second are `Dr`, `Ur`, and `Tr`, and the last variant are `Dc`, `Uc`, and `Tc`.
|
||||
In most cases, one is likely use normal keys for the steps, so the `D`, `U`, and
|
||||
`T` steps apply the `Key_` prefix. This allows us to write `MACRO(T(X))` instead
|
||||
of `MACRO(Tr(Key_X))` - making the macro definition shorter, and more readable.
|
||||
|
||||
The compact variant (`Dc`, `Uc`, and `Tc`) prefix the argument with `Key_` too,
|
||||
but unlike `D`, `U`, and `T`, they ignore the `flags` component of the key, and
|
||||
as such, are limited to ordinary keys. Mouse keys, consumer- or system keys are
|
||||
not supported by this compact representation.
|
||||
|
||||
* `D(key)`, `Dr(key)`, `Dc(key)`: Simulates a key being pressed (pushed down).
|
||||
* `U(key)`, `Ur(key)`, `Uc(key)`: Simulates a key being released (going up).
|
||||
* `T(key)`, `Tr(key)`, `Tc(key)`: Simulates a key being tapped (pressed first, then released).
|
||||
|
||||
## Overrideable methods
|
||||
|
||||
### `macroAction(macroIndex, keyState)`
|
||||
|
||||
> The `macroAction` method is the brain of the macro support in Kaleidoscope:
|
||||
> this function tells the plugin what sequence to play when given a macro index
|
||||
> and a key state.
|
||||
>
|
||||
> It should return a macro sequence, or `MACRO_NONE` if nothing is to be played
|
||||
> back.
|
||||
@ -0,0 +1,86 @@
|
||||
/* Kaleidoscope-Macros - Macro 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 "MacroKeyDefs.h"
|
||||
#include "MacroSteps.h"
|
||||
|
||||
const macro_t *macroAction(uint8_t macroIndex, uint8_t keyState);
|
||||
|
||||
#if !defined(MAX_CONCURRENT_MACROS)
|
||||
#define MAX_CONCURRENT_MACROS 8
|
||||
#endif
|
||||
|
||||
struct MacroKeyEvent {
|
||||
byte key_code;
|
||||
byte key_id;
|
||||
byte key_state;
|
||||
};
|
||||
|
||||
namespace kaleidoscope {
|
||||
namespace plugin {
|
||||
|
||||
class Macros_ : public kaleidoscope::Plugin {
|
||||
public:
|
||||
Macros_(void) {}
|
||||
|
||||
static MacroKeyEvent active_macros[MAX_CONCURRENT_MACROS];
|
||||
static byte active_macro_count;
|
||||
static void addActiveMacroKey(byte key_code, byte key_id, byte key_state) {
|
||||
// If we've got too many active macros, give up:
|
||||
if (active_macro_count >= MAX_CONCURRENT_MACROS) {
|
||||
return;
|
||||
}
|
||||
active_macros[active_macro_count].key_code = key_code;
|
||||
active_macros[active_macro_count].key_id = key_id;
|
||||
active_macros[active_macro_count].key_state = key_state;
|
||||
++active_macro_count;
|
||||
}
|
||||
|
||||
EventHandlerResult onKeyswitchEvent(Key &mappedKey, byte row, byte col, uint8_t keyState);
|
||||
EventHandlerResult beforeReportingState();
|
||||
EventHandlerResult afterEachCycle();
|
||||
|
||||
void play(const macro_t *macro_p);
|
||||
|
||||
/* What follows below, is a bit of template magic that allows us to use
|
||||
Macros.type() with any number of arguments, without having to use a
|
||||
sentinel. See the comments on Kaleidoscope.use() for more details - this is
|
||||
the same trick.
|
||||
*/
|
||||
inline const macro_t *type() {
|
||||
return MACRO_NONE;
|
||||
}
|
||||
const macro_t *type(const char *string);
|
||||
template <typename... Strings>
|
||||
const macro_t *type(const char *first, Strings&&... strings) {
|
||||
type(first);
|
||||
return type(strings...);
|
||||
}
|
||||
|
||||
static byte row, col;
|
||||
|
||||
private:
|
||||
Key lookupAsciiCode(uint8_t ascii_code);
|
||||
};
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
extern kaleidoscope::plugin::Macros_ Macros;
|
||||
Loading…
Reference in new issue