From 9fd0fb0bb40c81ea96a39b244d2b9a042f1aa1b8 Mon Sep 17 00:00:00 2001 From: MURAOKA Taro Date: Tue, 16 Apr 2024 02:27:24 +0900 Subject: [PATCH] add comments, and documents --- .../keyboards/keyball/lib/keyball/README.md | 20 +++++++++- .../keyboards/keyball/lib/keyball/keyball.c | 4 +- .../keyboards/keyball/lib/keyball/keyball.h | 39 +++++++++++++++---- .../keyboards/keyball/lib/keyball/keycodes.md | 6 +++ 4 files changed, 58 insertions(+), 11 deletions(-) diff --git a/qmk_firmware/keyboards/keyball/lib/keyball/README.md b/qmk_firmware/keyboards/keyball/lib/keyball/README.md index 68a91e6df..3b4605bbe 100644 --- a/qmk_firmware/keyboards/keyball/lib/keyball/README.md +++ b/qmk_firmware/keyboards/keyball/lib/keyball/README.md @@ -1,5 +1,9 @@ # Keyball Core Function Library +## Scroll snap mode + +TODO + ## MEMO This section contains notes regarding the specifications of this library. @@ -11,10 +15,22 @@ please make pull requests to share it us. ## Scroll Snap Spec -デフォルトで有効になっているスクロールスナップ機能は、 -ボールによるスクロールを垂直方向に制限(スナップ)している。 この機能は config.h に `#define KEYBALL_SCROLLSNAP_ENABLE 0` を書き加えることで無効化できる。 +トラックボールによるスクロールの方向を制限するのがスクロールスナップ。 +現在のスクロールスナップには3つのモードがある。 + +* 垂直方向にスナップ (デフォルト) +* 水平方向にスナップ +* スナップしない自由スクロール + +以上を `SSNP_VER`, `SSNP_HOR`, `SSNP_FRE` の独自キーコードを用いて手動で切り替える。 + +### up to 1.3.2 + +初期状態でトラックボールによるスクロールを垂直方向に制限(スナップ)している。 +この振る舞いは config.h に `#define KEYBALL_SCROLLSNAP_ENABLE 1` を書き加えることで有効化できる。 + この機能はスナップモードとフリーモードから構成される。 初期状態はスナップモードで、このモードではスクロール方向は垂直に制限される。 スナップモードで水平の一定方向に一定カウント(デフォルトは12)以上スクロールするとフリーモードに遷移する。 diff --git a/qmk_firmware/keyboards/keyball/lib/keyball/keyball.c b/qmk_firmware/keyboards/keyball/lib/keyball/keyball.c index 838b01c65..aac689631 100644 --- a/qmk_firmware/keyboards/keyball/lib/keyball/keyball.c +++ b/qmk_firmware/keyboards/keyball/lib/keyball/keyball.c @@ -206,8 +206,9 @@ __attribute__((weak)) void keyball_on_apply_motion_to_mouse_scroll(keyball_motio # error("unknown Keyball model") #endif + // Scroll snapping #if KEYBALL_SCROLLSNAP_ENABLE == 1 - // scroll snap (behavior up to 1.3.2) + // Old behavior up to 1.3.2) uint32_t now = timer_read32(); if (r->h != 0 || r->v != 0) { keyball.scroll_snap_last = now; @@ -219,6 +220,7 @@ __attribute__((weak)) void keyball_on_apply_motion_to_mouse_scroll(keyball_motio r->h = 0; } #elif KEYBALL_SCROLLSNAP_ENABLE == 2 + // New behavior switch (keyball.scrollsnap_mode) { case KEYBALL_SCROLLSNAP_MODE_VERTICAL: r->h = 0; diff --git a/qmk_firmware/keyboards/keyball/lib/keyball/keyball.h b/qmk_firmware/keyboards/keyball/lib/keyball/keyball.h index b59470253..42db0a211 100644 --- a/qmk_firmware/keyboards/keyball/lib/keyball/keyball.h +++ b/qmk_firmware/keyboards/keyball/lib/keyball/keyball.h @@ -105,8 +105,8 @@ enum keyball_keycodes { SCRL_DVI = QK_KB_8, // Increment scroll divider SCRL_DVD = QK_KB_9, // Decrement scroll divider - SSNP_VER = QK_KB_13, // Set scroll snap mode as horizontal - SSNP_HOR = QK_KB_14, // Set scroll snap mode as vertical + SSNP_VER = QK_KB_13, // Set scroll snap mode as vertical + SSNP_HOR = QK_KB_14, // Set scroll snap mode as horizontal SSNP_FRE = QK_KB_15, // Set scroll snap mode as disable (free scroll) // Auto mouse layer control keycodes. @@ -230,20 +230,43 @@ bool keyball_get_scroll_mode(void); /// keyball_set_scroll_mode modify scroll mode. void keyball_set_scroll_mode(bool mode); -/// TODO: document +/// keyball_get_scrollsnap_mode gets current scroll snap mode. keyball_scrollsnap_mode_t keyball_get_scrollsnap_mode(void); -/// TODO: document +/// keyball_set_scrollsnap_mode change scroll snap mode. void keyball_set_scrollsnap_mode(keyball_scrollsnap_mode_t mode); -// TODO: document +/// keyball_get_scroll_div gets current scroll divider. +/// See also keyball_set_scroll_div for the scroll divider's detail. uint8_t keyball_get_scroll_div(void); -// TODO: document +/// keyball_set_scroll_div changes scroll divider. +/// +/// The scroll divider is the number that divides the raw value when applying +/// trackball motion to scrolling. The CPI value of the trackball is very +/// high, so if you apply it to scrolling as is, it will scroll too much. +/// In order to adjust the scroll amount to be appropriate, it is applied after +/// dividing it by a scroll divider. The actual denominator is determined by +/// the following formula: +/// +/// denominator = 2 ^ (div - 1) ^2 +/// +/// Valid values are between 1 and 7, KEYBALL_SCROLL_DIV_DEFAULT is used when 0 +/// is specified. void keyball_set_scroll_div(uint8_t div); -// TODO: document +/// keyball_get_cpi gets current CPI of trackball. +/// The actual CPI value is the returned value +1 and multiplied by 100: +/// +/// CPI = (v + 1) * 100 uint8_t keyball_get_cpi(void); -// TODO: document +/// keyball_set_cpi changes CPI of trackball. +/// Valid values are between 0 to 119, and the actual CPI value is the set +/// value +1 and multiplied by 100: +/// +/// CPI = (v + 1) * 100 +/// +/// In addition, if you do not upload SROM, the maximum value will be limited +/// to 34 (3500CPI). void keyball_set_cpi(uint8_t cpi); diff --git a/qmk_firmware/keyboards/keyball/lib/keyball/keycodes.md b/qmk_firmware/keyboards/keyball/lib/keyball/keycodes.md index dbfcb4a7d..44a70b460 100644 --- a/qmk_firmware/keyboards/keyball/lib/keyball/keycodes.md +++ b/qmk_firmware/keyboards/keyball/lib/keyball/keycodes.md @@ -21,6 +21,9 @@ | `AML_TO` | `Kb 10` | `0x7e0a` | Toggle automatic mouse layer | | `AML_I50` | `Kb 11` | `0x7e0b` | Increase 50ms automatic mouse layer timeout (max 1000ms) | | `AML_D50` | `Kb 12` | `0x7e0c` | Decrease 50ms automatic mouse layer timeout (min 100ms) | +| `SSNP_VER` | `Kb 13` | `0x7e0d` | Set scroll snap mode as vertical | +| `SSNP_HOR` | `Kb 14` | `0x7e0e` | Set scroll snap mode as horizontal | +| `SSNP_FRE` | `Kb 15` | `0x7e0f` | Set scroll snap mode as disable (free scroll) | [^1]: CPI, scroll divider, automatic mouse layer's enable/disable, and automatic mouse layer's timeout. @@ -42,5 +45,8 @@ | `AML_TO` | `Kb 10` | `0x7e0a` | 自動マウスレイヤーをトグルします。 | | `AML_I50` | `Kb 11` | `0x7e0b` | 自動マウスレイヤーのタイムアウトを50msec増やします (max 1000ms) | | `AML_D50` | `Kb 12` | `0x7e0c` | 自動マウスレイヤーのタイムアウトを50msec減らします (min 100ms) | +| `SSNP_VER` | `Kb 13` | `0x7e0d` | スクロールスナップモードを垂直にする | +| `SSNP_HOR` | `Kb 14` | `0x7e0e` | スクロールスナップモードを水平にする | +| `SSNP_FRE` | `Kb 15` | `0x7e0f` | スクロールスナップモードを無効にする(自由スクロール) | [^2]: CPI、スクロール除数、自動マウスレイヤーのON/OFF状態、及び自動マウスレイヤのタイムアウト