diff options
Diffstat (limited to 'docs')
30 files changed, 638 insertions, 228 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 09ea9e6e79..c9d6c2bb14 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -3,7 +3,7 @@ * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) - * [Best Practices](newbs_best_practices.md) + * [Git Best Practices](newbs_best_practices.md) * [Learning Resources](newbs_learn_more_resources.md) * [QMK Basics](README.md) @@ -60,6 +60,7 @@ * [Key Lock](feature_key_lock.md) * [Layouts](feature_layouts.md) * [Leader Key](feature_leader_key.md) + * [LED Matrix](feature_led_matrix.md) * [Macros](feature_macros.md) * [Mouse Keys](feature_mouse_keys.md) * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) @@ -91,7 +92,8 @@ * [Understanding QMK](understanding_qmk.md) * Other Topics - * [Using Eclipse with QMK](eclipse.md) + * [Using Eclipse with QMK](other_eclipse.md) + * [Using VSCode with QMK](other_vscode.md) * [Support](support.md) * QMK Internals (In Progress) diff --git a/docs/config_options.md b/docs/config_options.md index 8fa6e944f0..ad42e97802 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -171,11 +171,15 @@ If you define these options you will enable the associated feature, which may in ## RGB Light Configuration * `#define RGB_DI_PIN D7` - * pin the DI on the ws2812 is hooked-up to + * pin the DI on the WS2812 is hooked-up to * `#define RGBLIGHT_ANIMATIONS` * run RGB animations -* `#define RGBLED_NUM 15` +* `#define RGBLED_NUM 12` * number of LEDs +* `#define RGBLED_SPLIT { 6, 6 }` + * number of LEDs connected that are directly wired to `RGB_DI_PIN` on each half of a split keyboard + * First value indicates number of LEDs for left half, second value is for the right half + * Needed if both halves of the board have RGB LEDs wired directly to the RGB output pin on the controllers instead of passing the output of the left half to the input of the right half * `#define RGBLIGHT_HUE_STEP 12` * units to step when in/decreasing hue * `#define RGBLIGHT_SAT_STEP 25` @@ -208,9 +212,13 @@ There are a few different ways to set handedness for split keyboards (listed in 1. Set `SPLIT_HAND_PIN`: Reads a pin to determine handedness. If pin is high, it's the left side, if low, the half is determined to be the right side 2. Set `EE_HANDS` and flash `eeprom-lefthand.eep`/`eeprom-righthand.eep` to each half + * For boards with DFU bootloader you can use `:dfu-split-left`/`:dfu-split-right` to flash these EEPROM files + * For boards with Caterina bootloader (like stock Pro Micros), use `:avrdude-split-left`/`:avrdude-split-right` 3. Set `MASTER_RIGHT`: Half that is plugged into the USB port is determined to be the master and right half (inverse of the default) 4. Default: The side that is plugged into the USB port is the master half and is assumed to be the left half. The slave side is the right half +#### Defines for handedness + * `#define SPLIT_HAND_PIN B7` * For using high/low pin to determine handedness, low = right hand, high = left hand. Replace `B7` with the pin you are using. This is optional, and if you leave `SPLIT_HAND_PIN` undefined, then you can still use the EE_HANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses. @@ -232,6 +240,9 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define MATRIX_COL_PINS_RIGHT { <col pins> }` * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns. +* `#define RGBLED_SPLIT { 6, 6 }` + * See [RGB Light Configuration](#rgb-light-configuration) + * `#define SELECT_SOFT_SERIAL_SPEED <speed>` (default speed is 1) * Sets the protocol speed when using serial communication * Speeds: @@ -307,8 +318,8 @@ Use these to enable or disable building certain features. The more you have enab * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common * `CUSTOM_MATRIX` * Allows replacing the standard matrix scanning routine with a custom one. -* `CUSTOM_DEBOUNCE` - * Allows replacing the standard key debouncing routine with a custom one. +* `DEBOUNCE_TYPE` + * Allows replacing the standard key debouncing routine with an alternative or custom one. * `WAIT_FOR_USB` * Forces the keyboard to wait for a USB connection to be established before it starts up * `NO_USB_STARTUP_CHECK` diff --git a/docs/contributing.md b/docs/contributing.md index eee40609bb..15066185bc 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -129,6 +129,20 @@ Documentation is one of the easiest ways to get started contributing to QMK. Fin You'll find all our documentation in the `qmk_firmware/docs` directory, or if you'd rather use a web based workflow you can click "Suggest An Edit" at the top of each page on http://docs.qmk.fm/. +When providing code examples in your documentation, try to observe naming conventions used elsewhere in the docs. For example, standardizing enums as `my_layers` or `my_keycodes` for consistency: + +```c +enum my_layers { + _FIRST_LAYER, + _SECOND_LAYER +}; + +enum my_keycodes { + FIRST_LAYER = SAFE_RANGE, + SECOND_LAYER +}; +``` + ## Keymaps Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap. @@ -137,7 +151,7 @@ Most first-time QMK contributors start with their personal keymaps. We try to ke * All Keymap PR's are squashed, so if you care about how your commits are squashed you should do it yourself * Do not lump features in with keymap PR's. Submit the feature first and then a second PR for the keymap. * Do not include `Makefile`s in your keymap folder (they're no longer used) -* Update copyrights in file headers (look for `REPLACE_WITH_YOUR_NAME `) +* Update copyrights in file headers (look for `%YOUR_NAME%`) ## Keyboards @@ -150,7 +164,7 @@ We also ask that you follow these guidelines: * Do not lump core features in with new keyboards. Submit the feature first and then submit a separate PR for the keyboard. * Name `.c`/`.h` file after the immediate parent folder, eg `/keyboards/<kb1>/<kb2>/<kb2>.[ch]` * Do not include `Makefile`s in your keyboard folder (they're no longer used) -* Update copyrights in file headers (look for `REPLACE_WITH_YOUR_NAME `) +* Update copyrights in file headers (look for `%YOUR_NAME%`) ## Quantum/TMK Core diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index cc84e141f9..655fa1578e 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -116,29 +116,29 @@ Use the `IS_LED_ON(usb_led, led_name)` and `IS_LED_OFF(usb_led, led_name)` macro ```c void led_set_user(uint8_t usb_led) { if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) { - PORTB |= (1<<0); + writePinLow(B0); } else { - PORTB &= ~(1<<0); + writePinHigh(B0); } if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) { - PORTB |= (1<<1); + writePinLow(B1); } else { - PORTB &= ~(1<<1); + writePinHigh(B1); } if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) { - PORTB |= (1<<2); + writePinLow(B2); } else { - PORTB &= ~(1<<2); + writePinHigh(B2); } if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) { - PORTB |= (1<<3); + writePinLow(B3); } else { - PORTB &= ~(1<<3); + writePinHigh(B3); } if (IS_LED_ON(usb_led, USB_LED_KANA)) { - PORTB |= (1<<4); + writePinLow(B4); } else { - PORTB &= ~(1<<4); + writePinHigh(B4); } } ``` @@ -189,16 +189,18 @@ However, if you have hardware stuff that you need initialized, this is the best ### Example `keyboard_pre_init_user()` Implementation -This example, at the keyboard level, sets up B1, B2, and B3 as LED pins. +This example, at the keyboard level, sets up B0, B1, B2, B3, and B4 as LED pins. ```c void keyboard_pre_init_user(void) { // Call the keyboard pre init code. // Set our LED pins as output - DDRB |= (1<<1); - DDRB |= (1<<2); - DDRB |= (1<<3); + setPinOutput(B0); + setPinOutput(B1); + setPinOutput(B2); + setPinOutput(B3); + setPinOutput(B4); } ``` @@ -270,16 +272,13 @@ This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_ ### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation -This example, at the keyboard level, sets up B1, B2, and B3 as LED pins. ```c -void suspend_power_down_user(void) -{ +void suspend_power_down_user(void) { rgb_matrix_set_suspend_state(true); } -void suspend_wakeup_init_user(void) -{ +void suspend_wakeup_init_user(void) { rgb_matrix_set_suspend_state(false); } ``` @@ -321,7 +320,7 @@ uint32_t layer_state_set_user(uint32_t state) { ``` ### `layer_state_set_*` Function Documentation -* Keyboard/Revision: `void uint32_t layer_state_set_kb(uint32_t state)` +* Keyboard/Revision: `uint32_t layer_state_set_kb(uint32_t state)` * Keymap: `uint32_t layer_state_set_user(uint32_t state)` The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status) @@ -356,11 +355,11 @@ user_config_t user_config; This sets up a 32 bit structure that we can store settings with in memory, and write to the EEPROM. Using this removes the need to define variables, since they're defined in this structure. Remember that `bool` (boolean) values use 1 bit, `uint8_t` uses 8 bits, `uint16_t` uses up 16 bits. You can mix and match, but changing the order can cause issues, as it will change the values that are read and written. -We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `matrix_init_user` and `process_record_user` to configure everything. +We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `keyboard_post_init_user` and `process_record_user` to configure everything. -Now, using the `matrix_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap. And It should look like: +Now, using the `keyboard_post_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap. And It should look like: ``` -void matrix_init_user(void) { +void keyboard_post_init_user(void) { // Call the keymap level matrix init. // Read the user config from EEPROM @@ -447,6 +446,7 @@ And lastly, you want to add the `eeconfig_init_user` function, so that when the ``` void eeconfig_init_user(void) { // EEPROM is getting reset! + user_config.raw = 0; user_config.rgb_layer_change = true; // We want this enabled by default eeconfig_update_user(user_config.raw); // Write default value to EEPROM now diff --git a/docs/faq_build.md b/docs/faq_build.md index be26a7c581..0c1bedd715 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -15,7 +15,7 @@ or just: $ sudo make <keyboard>:<keymap>:dfu -Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible. +Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible. ### Linux `udev` Rules On Linux, you'll need proper privileges to access the MCU. You can either use @@ -36,6 +36,12 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="066 # tmk keyboard products https://github.com/tmk/tmk_keyboard SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" ``` +**/etc/udev/rules.d/54-input-club-keyboard.rules:** + +``` +# Input Club keyboard bootloader +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" +``` ### Serial device is not detected in bootloader mode on Linux Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as @@ -47,7 +53,12 @@ If you're using Windows to flash your keyboard, and you are running into issues, Re-running the installation script for MSYS2 may help (eg run `./util/qmk_install.sh` from MSYS2/WSL) or reinstalling the QMK Toolbox may fix the issue. -If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, find the device in question, and select the `WinUS(libusb-1.0)` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again. +If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, find the device in question, and select the `WinUSB` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again. If that doesn't work, try all of the options, until one works. + +?> There isn't a best option for which driver should be used here. Some options work better on some systems than others. libUSB and WinUSB seem to be the best options here. + +If the bootloader doesn't show up in the list for devices, you may need to enable the "List all devices" option in the `Options` menu, and then find the bootloader in question. + ## WINAVR is Obsolete It is no longer recommended and may cause some problem. diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index b20acf3c44..a6ddf458cc 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -15,7 +15,7 @@ This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it mo ## Caveats -Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored. +Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored. If you need to apply modifiers to your tapped keycode, [Tap Dance](https://github.com/qmk/qmk_firmware/blob/master/docs/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this. Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two. diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 38861e8c14..e1dd4c5a85 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -100,6 +100,16 @@ In music mode, the following keycodes work differently, and don't pass through: * `KC_UP` - speed-up playback * `KC_DOWN` - slow-down playback +The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`: + + #define PITCH_STANDARD_A 432.0f + +You can completely disable Music Mode as well. This is useful, if you're pressed for space on your controller. To disable it, add this to your `config.h`: + + #define NO_MUSIC_MODE + +### Music Mask + By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this: #define MUSIC_MASK keycode != KC_NO @@ -120,13 +130,26 @@ For a more advanced way to control which keycodes should still be processed, you Things that return false are not part of the mask, and are always processed. -The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`: +### Music Map - #define PITCH_STANDARD_A 432.0f +By default, the Music Mode uses the columns and row to determine the scale for the keys. For a board that uses a rectangular matrix that matches the keyboard layout, this is just fine. However, for boards that use a more complicated matrix (such as the Planck Rev6, or many split keyboards) this would result in a very skewed experience. -You can completely disable Music Mode as well. This is useful, if you're pressed for space on your controller. To disable it, add this to your `config.h`: +However, the Music Map option allows you to remap the scaling for the music mode, so it fits the layout, and is more natural. - #define NO_MUSIC_MODE +To enable this feature, add `#define MUSIC_MAP` to your `config.h` file, and then you will want to add a `uint8_t music_map` to your keyboard's `c` file, or your `keymap.c`. + +```c +const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12( + 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, + 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, + 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 +); +``` + +You will want to use whichever `LAYOUT` macro that your keyboard uses here. This maps it to the correct key location. Start in the bottom left of the keyboard layout, and move to the right, and then upwards. Fill in all the entries until you have a complete matrix. + +You can look at the [Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) as an example of how to implement this. ## Audio Click diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index 82b3d7de12..5d4343f08b 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -2,45 +2,38 @@ QMK supports multiple debounce algorithms through its debounce API. -The underlying debounce algorithm is determined by which matrix.c file you are using. - The logic for which debounce method called is below. It checks various defines that you have set in rules.mk ``` +DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce DEBOUNCE_TYPE?= sym_g -VALID_DEBOUNCE_TYPES := sym_g eager_pk custom -ifeq ($(filter $(DEBOUNCE_TYPE),$(VALID_DEBOUNCE_TYPES)),) - $(error DEBOUNCE_TYPE="$(DEBOUNCE_TYPE)" is not a valid debounce algorithm) -endif -ifeq ($(strip $(DEBOUNCE_TYPE)), sym_g) - QUANTUM_SRC += $(DEBOUNCE_DIR)/debounce_sym_g.c -else ifeq ($(strip $(DEBOUNCE_TYPE)), eager_pk) - QUANTUM_SRC += $(DEBOUNCE_DIR)/debounce_eager_pk.c +ifneq ($(strip $(DEBOUNCE_TYPE)), custom) + QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c endif ``` # Debounce selection -| DEBOUNCE_ALGO | Description | What to do | -| ------------- | --------------------------------------------------- | ----------------------------- | -| Not defined | You are using the included matrix.c and debounce.c | Nothing. Debounce_sym_g will be compiled, and used if necessary | -| custom | Use your own debounce.c | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions | -| sym_g / eager_pk | You are using the included matrix.c and debounce.c | Use an alternative debounce algorithm | +| DEBOUNCE_TYPE | Description | What else is needed | +| ------------- | --------------------------------------------------- | ----------------------------- | +| Not defined | Use the default algorithm, currently sym_g | Nothing | +| custom | Use your own debounce.c | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions | +| anything_else | Use another algorithm from quantum/debounce/* | Nothing | -**Regarding split keyboards**: +**Regarding split keyboards**: The debounce code is compatible with split keyboards. # Use your own debouncing code * Set ```DEBOUNCE_TYPE = custom ```. * Add ```SRC += debounce.c``` -* Add your own ```debounce.c```. Look at included ```debounce_sym_g.c```s for sample implementations. +* Add your own ```debounce.c```. Look at current implementations in ```quantum/debounce``` for examples. * Debouncing occurs after every raw matrix scan. * Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly. # Changing between included debouncing methods You can either use your own code, by including your own debounce.c, or switch to another included one. Included debounce methods are: -* debounce_eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE_DELAY``` millseconds of no further input for that key -* debounce_sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE_DELAY``` milliseconds of no changes has occured, all input changes are pushed. +* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE_DELAY``` millseconds of no further input for that key +* sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE_DELAY``` milliseconds of no changes has occured, all input changes are pushed. diff --git a/docs/feature_grave_esc.md b/docs/feature_grave_esc.md index a7261d2dc8..f57c6042ca 100644 --- a/docs/feature_grave_esc.md +++ b/docs/feature_grave_esc.md @@ -18,7 +18,7 @@ If Mary presses GESC on her keyboard, the OS will see an KC_ESC character. Now i ### Caveats - * On macOS CMD/GUI + KC_GRV is actually mapped to a hot key so it will not output a backtick. +On macOS, Command+<code>`</code> is by default mapped to "Move focus to next window" so it will not output a backtick. Additionally, Terminal always recognises this shortcut to cycle between windows, even if the shortcut is changed in the Keyboard preferences. ## Configuration diff --git a/docs/feature_macros.md b/docs/feature_macros.md index 79419abd20..743fc3ad55 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -146,9 +146,59 @@ send_string(my_str); SEND_STRING(".."SS_TAP(X_END)); ``` -## The Old Way: `MACRO()` & `action_get_macro` -?> This is inherited from TMK, and hasn't been updated - it's recommend that you use `SEND_STRING` and `process_record_user` instead. +## Advanced Macro Functions + +There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple. + +### `record->event.pressed` + +This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is + +```c + if (record->event.pressed) { + // on keydown + } else { + // on keyup + } +``` + +### `register_code(<kc>);` + +This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`. + +### `unregister_code(<kc>);` + +Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent. + +### `tap_code(<kc>);` + +This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it). + +If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds. + +### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);` + +These functions work similar to their regular counterparts, but allow you to use modded keycodes (with Shift, Alt, Control, and/or GUI applied to them). + +Eg, you could use `register_code16(S(KC_5));` instead of registering the mod, then registering the keycode. + +### `clear_keyboard();` + +This will clear all mods and keys currently pressed. + +### `clear_mods();` + +This will clear all mods currently pressed. + +### `clear_keyboard_but_mods();` + +This will clear all keys besides the mods currently pressed. + + +## **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro` + +!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead. By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example: @@ -222,49 +272,8 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { }; ``` -## Advanced Macro Functions - -There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple. - -### `record->event.pressed` - -This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is - -```c - if (record->event.pressed) { - // on keydown - } else { - // on keyup - } -``` - -### `register_code(<kc>);` - -This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`. - -### `unregister_code(<kc>);` - -Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent. - -### `tap_code(<kc>);` - -This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it). - -If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds. - -### `clear_keyboard();` - -This will clear all mods and keys currently pressed. - -### `clear_mods();` - -This will clear all mods currently pressed. - -### `clear_keyboard_but_mods();` - -This will clear all keys besides the mods currently pressed. -## Advanced Example: Single-Key Copy/Paste +### Advanced Example: Single-Key Copy/Paste This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released. diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index 673eafaef5..e64ddf3d06 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -1,48 +1,48 @@ # Mousekeys -Mousekeys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer around, click up to 5 buttons, and even scroll in all 4 directions. QMK uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys). +Mousekeys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer around, click up to 5 buttons, and even scroll in all 4 directions. -## Adding Mousekeys to a Keymap +There are 2 ways to define how the mousekeys behave, using "[auto-accelerating](#configuring-the-behavior-of-mousekeys-with-auto-accelerated-movement)" or "[3-speed constant](#configuring-the-behavior-of-mousekeys-with-3-speed-constant-movement)" behavior. -There are two steps to adding Mousekeys support to your keyboard. You must enable support in the `rules.mk` file and you must map mouse actions to keys on your keyboard. +In either case, you will need to enable mousekeys in your makefile, +and add the relevant [keycodes](#mapping-mouse-actions-to-keyboard-keys) to your keymap. -### Adding Mousekeys Support in the `rules.mk` +#### Enable Mousekeys -To add support for Mousekeys you simply need to add a single line to your keymap's `rules.mk`: +To enable the mousekey functionality, add the following line to your keymap's `rules.mk`: ``` MOUSEKEY_ENABLE = yes ``` -You can see an example here: https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/keymaps/mouse_keys/rules.mk - -### Mapping Mouse Actions to Keyboard Keys +#### Mapping Mouse Actions to Keyboard Keys You can use these keycodes within your keymap to map button presses to mouse actions: -|Key |Aliases |Description | -|----------------|---------|---------------------------| -|`KC_MS_UP` |`KC_MS_U`|Mouse Cursor Up | -|`KC_MS_DOWN` |`KC_MS_D`|Mouse Cursor Down | -|`KC_MS_LEFT` |`KC_MS_L`|Mouse Cursor Left | -|`KC_MS_RIGHT` |`KC_MS_R`|Mouse Cursor Right | -|`KC_MS_BTN1` |`KC_BTN1`|Mouse Button 1 | -|`KC_MS_BTN2` |`KC_BTN2`|Mouse Button 2 | -|`KC_MS_BTN3` |`KC_BTN3`|Mouse Button 3 | -|`KC_MS_BTN4` |`KC_BTN4`|Mouse Button 4 | -|`KC_MS_BTN5` |`KC_BTN5`|Mouse Button 5 | -|`KC_MS_WH_UP` |`KC_WH_U`|Mouse Wheel Up | -|`KC_MS_WH_DOWN` |`KC_WH_D`|Mouse Wheel Down | -|`KC_MS_WH_LEFT` |`KC_WH_L`|Mouse Wheel Left | -|`KC_MS_WH_RIGHT`|`KC_WH_R`|Mouse Wheel Right | -|`KC_MS_ACCEL0` |`KC_ACL0`|Set mouse acceleration to 0| -|`KC_MS_ACCEL1` |`KC_ACL1`|Set mouse acceleration to 1| -|`KC_MS_ACCEL2` |`KC_ACL2`|Set mouse acceleration to 2| - -You can see an example in the `_ML` here: https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/keymaps/mouse_keys/keymap.c#L46 - -## Configuring the Behavior of Mousekeys +|Key |Aliases |Description | +|----------------|---------|-----------------------------------| +|`KC_MS_UP` |`KC_MS_U`|Mouse Cursor Up | +|`KC_MS_DOWN` |`KC_MS_D`|Mouse Cursor Down | +|`KC_MS_LEFT` |`KC_MS_L`|Mouse Cursor Left | +|`KC_MS_RIGHT` |`KC_MS_R`|Mouse Cursor Right | +|`KC_MS_BTN1` |`KC_BTN1`|Mouse Button 1 | +|`KC_MS_BTN2` |`KC_BTN2`|Mouse Button 2 | +|`KC_MS_BTN3` |`KC_BTN3`|Mouse Button 3 | +|`KC_MS_BTN4` |`KC_BTN4`|Mouse Button 4 | +|`KC_MS_BTN5` |`KC_BTN5`|Mouse Button 5 | +|`KC_MS_WH_UP` |`KC_WH_U`|Mouse Wheel Up | +|`KC_MS_WH_DOWN` |`KC_WH_D`|Mouse Wheel Down | +|`KC_MS_WH_LEFT` |`KC_WH_L`|Mouse Wheel Left | +|`KC_MS_WH_RIGHT`|`KC_WH_R`|Mouse Wheel Right | +|`KC_MS_ACCEL0` |`K |