Gergely Nagy
ad076a36dd
|
7 years ago | |
---|---|---|
examples/LED-Palette-Theme | 8 years ago | |
src | 7 years ago | |
.gitignore | 8 years ago | |
.travis.yml | 8 years ago | |
COPYING | 8 years ago | |
Makefile | 8 years ago | |
README.md | 8 years ago | |
library.properties | 8 years ago |
README.md
Kaleidoscope-LED-Palette-Theme
A common base for plugins that want to provide themes, or theme-related capabilities, using a 15+1 color palette. In other words, this is for plugin authors primarily. The primary aim of the plugin is to provide not only a common palette, but tools that make it easier to use it too.
Using the plugin
To use the plugin, one needs to do a bit more than include the header, and tell the firmware to use it. Itself being a mere building block, to use it to its full extent, we need to create our own plugin on top of it.
#include <Kaleidoscope.h>
#include <Kaleidoscope-EEPROM-Settings.h>
#include <Kaleidoscope-LED-Palette-Theme.h>
#include <Kaleidoscope-Focus.h>
namespace example {
class TestLEDMode : public LEDMode {
public:
TestLEDMode() {}
void begin(void) final;
void update(void) final;
static bool focusHook(const char *command);
private:
static uint16_t map_base_;
};
uint16_t TestLEDMode::map_base_;
void
TestLEDMode::begin(void) {
LEDMode::begin();
map_base_ = LEDPaletteTheme.reserveThemes(1);
}
void
TestLEDMode::update(void) {
LEDPaletteTheme.updateHandler(map_base_, 0);
}
bool
TestLEDMode::focusHook(const char *command) {
return LEDPaletteTheme.themeFocusHandler(command, PSTR("testLedMode.map"), map_base_, 1);
}
}
example::TestLEDMode TestLEDMode;
void setup() {
Serial.begin(9600);
USE_PLUGINS(&Focus, &LEDPaletteTheme, &TestLEDMode, &EEPROMSettings);
Kaleidoscope.setup();
EEPROMSettings.seal();
TestLEDMode.activate();
Focus.addHook(FOCUS_HOOK_LEDPALETTETHEME);
Focus.addHook(FOCUS_HOOK(TestLEDMode.focusHook, "testLEDMode.map"));
}
This is a simple extension, where it provides a testLEDMode.map
Focus command,
with which one can set the theme which will be saved to EEPROM.
Plugin methods
The plugin provides the LEDPaletteTheme
object, which has the following methods and properties:
.reserveThemes(max_themes)
Reserve space in EEPROM for
max_themes
. Each key on a theme uses half a byte of space. The function returns thetheme_base
to be used with the rest of the methods.The
theme_base
is a pointer into the EEPROM where the theme storage starts.
.updateHandler(theme_base, theme)
A helper we can call in our plugin's
.update()
method: given an EEPROM location (theme_base
), and atheme
index, it will update the keyboard with the colors of the specified theme.The
theme
argument can be any index between zero andmax_themes
. How the plugin decides which theme to display depends entirely on the plugin.
.themeFocusHandler(command, expected_command, theme_base, max_themes)
To be used in a custom
Focus
handler: handles theexpected_command
Focus command, and provides a way to query and update the themes supported by the plugin.When queried, it will list the color indexes. When used as a setter, it expects one index per key.
The palette can be set via the
palette
focus command, implemented by theFOCUS_HOOK_LEDPALETTETHEME
hook explained below.
.transparent_index
The plugin supports transparent colors too: by default, the last color (index 15) is treated as transparent. If a pixel is found to be transparent,
.updateHandler
will not change its color, but leave it as is. This way one can create layers of themes, if so desired.This property can be set to a number between 0 and 15 to make that index transparent, or to a number higher than 15 to disable transparency support, and gain another color on the palette.
Focus commands
The plugin provides a single Focus
hook, FOCUS_HOOK_LEDPALETTETHEME
,
implementing the following command:
palette
Without arguments, prints the palette: RGB values for all 16 colors.
With arguments, updates the palette with new colors. One does not need to give the full palette, the plugin will process as many arguments as available, and ignore anything past the last index. It expects colors to have all three components specified, or none at all. Thus, partial palette updates are possible, but only on the color level, not at component level.
Dependencies
Further reading
Starting from the example is the recommended way of getting started with the plugin.