diff --git a/common_features.mk b/common_features.mk index bae23bb873..69fdac87dd 100644 --- a/common_features.mk +++ b/common_features.mk @@ -69,6 +69,10 @@ ifeq ($(strip $(FAUXCLICKY_ENABLE)), yes) SRC += $(QUANTUM_DIR)/fauxclicky.c endif +ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/pointing_device.c +endif + ifeq ($(strip $(UCIS_ENABLE)), yes) OPT_DEFS += -DUCIS_ENABLE UNICODE_COMMON = yes diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md new file mode 100644 index 0000000000..1ba8f7759e --- /dev/null +++ b/docs/feature_pointing_device.md @@ -0,0 +1,47 @@ +## Pointing Device + +Pointing Device is a generic name for a feature intended to be generic: moving the system pointer arround. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and lightweight. You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you. + +To enable Pointing Device, uncomment the following line in your rules.mk: + +``` +POINTING_DEVICE_ENABLE = yes +``` + +To manipulate the mouse report, you can use the following functions: + +* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer +* `pointing_device_set_report(report_mouse_t newMouseReport)` - Overrides and saves the report_mouse_t to be sent to the host computer + +Keep in mind that a report_mouse_t (here "mouseReport") has the following properties: + +* `mouseReport.x` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ to the right, - to the left) on the x axis. +* `mouseReport.y` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ upward, - downward) on the y axis. +* `mouseReport.v` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing vertical scrolling (+ upward, - downward). +* `mouseReport.h` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing horizontal scrolling (+ right, - left). +* `mouseReport.buttons` - this is a uint8_t in which the last 5 bits are used. These bits represent the mouse button state - bit 3 is mouse button 5, and bit 7 is mouse button 1. + +When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in "pointing_device_send()", which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden. + +In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function. Listen, this is an example: + +``` +case MS_SPECIAL: + report_mouse_t currentReport = pointing_device_get_report(); + if (record->event.pressed) + { + currentReport.v = 127; + currentReport.h = 127; + currentReport.buttons |= MOUSE_BTN1; //this is defined in report.h + } + else + { + currentReport.v = -127; + currentReport.h = -127; + currentReport.buttons &= ~MOUSE_BTN1; + } + pointing_device_set_report(currentReport); + break; +``` + +Recall that the mouse report is set to zero (except the buttons) whenever it is sent, so the scrolling would only occur once in each case. \ No newline at end of file diff --git a/docs/features.md b/docs/features.md index c5965f4c0e..2ef4361563 100644 --- a/docs/features.md +++ b/docs/features.md @@ -102,4 +102,4 @@ case MACRO_RAISED: update_tri_layer(LAYER_LOWER, LAYER_RAISED, LAYER_ADJUST); } break; -``` +``` \ No newline at end of file diff --git a/quantum/pointing_device.c b/quantum/pointing_device.c new file mode 100644 index 0000000000..0aaab84cd2 --- /dev/null +++ b/quantum/pointing_device.c @@ -0,0 +1,62 @@ +/* +Copyright 2017 Joshua Broekhuijsen + +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, either version 2 of the License, or +(at your option) any later version. + +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 . +*/ + +#include +#include "report.h" +#include "host.h" +#include "timer.h" +#include "print.h" +#include "debug.h" +#include "pointing_device.h" + +static report_mouse_t mouseReport = {}; + +__attribute__ ((weak)) +void pointing_device_init(void){ + //initialize device, if that needs to be done. +} + +__attribute__ ((weak)) +void pointing_device_send(void){ + //If you need to do other things, like debugging, this is the place to do it. + host_mouse_send(mouseReport); + //send it and 0 it out except for buttons, so those stay until they are explicity over-ridden using update_pointing_device + mouseReport.x = 0; + mouseReport.y = 0; + mouseReport.v = 0; + mouseReport.h = 0; +} + +__attribute__ ((weak)) +void pointing_device_task(void){ + //gather info and put it in: + //mouseReport.x = 127 max -127 min + //mouseReport.y = 127 max -127 min + //mouseReport.v = 127 max -127 min (scroll vertical) + //mouseReport.h = 127 max -127 min (scroll horizontal) + //mouseReport.buttons = 0x1F (decimal 31, binary 00011111) max (bitmask for mouse buttons 1-5, 1 is rightmost, 5 is leftmost) 0x00 min + //send the report + pointing_device_send(); +} + +report_mouse_t pointing_device_get_report(void){ + return mouseReport; +} + +void pointing_device_set_report(report_mouse_t newMouseReport){ + mouseReport = newMouseReport; +} \ No newline at end of file diff --git a/quantum/pointing_device.h b/quantum/pointing_device.h new file mode 100644 index 0000000000..40d71f7419 --- /dev/null +++ b/quantum/pointing_device.h @@ -0,0 +1,31 @@ +/* +Copyright 2017 Joshua Broekhuijsen + +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, either version 2 of the License, or +(at your option) any later version. + +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 . +*/ + +#ifndef POINTING_DEVICE_H +#define POINTING_DEVICE_H + +#include +#include "host.h" +#include "report.h" + +void pointingdevice_init(void); +void pointing_device_task(void); +void pointing_device_send(void); +report_mouse_t pointing_device_get_report(void); +void pointing_device_set_report(report_mouse_t newMouseReport); + +#endif diff --git a/tmk_core/common/keyboard.c b/tmk_core/common/keyboard.c index 1b7c8c1a2f..fd2cf74f57 100644 --- a/tmk_core/common/keyboard.c +++ b/tmk_core/common/keyboard.c @@ -63,6 +63,9 @@ along with this program. If not, see . #ifdef VISUALIZER_ENABLE # include "visualizer/visualizer.h" #endif +#ifdef POINTING_DEVICE_ENABLE +# include "pointing_device.h" +#endif #ifdef MATRIX_HAS_GHOST extern const uint16_t keymaps[][MATRIX_ROWS][MATRIX_COLS]; @@ -153,6 +156,9 @@ void keyboard_init(void) { #ifdef FAUXCLICKY_ENABLE fauxclicky_init(); #endif +#ifdef POINTING_DEVICE_ENABLE + pointing_device_init(); +#endif #if defined(NKRO_ENABLE) && defined(FORCE_NKRO) keymap_config.nkro = 1; #endif @@ -239,6 +245,10 @@ MATRIX_LOOP_END: visualizer_update(default_layer_state, layer_state, visualizer_get_mods(), host_keyboard_leds()); #endif +#ifdef POINTING_DEVICE_ENABLE + pointing_device_task(); +#endif + // update LED if (led_status != host_keyboard_leds()) { led_status = host_keyboard_leds();