Skip to content

Commit

Permalink
add comments, and documents
Browse files Browse the repository at this point in the history
  • Loading branch information
@koron
koron committed Apr 15, 2024
1 parent 409d474 commit 9fd0fb0
Show file tree
Hide file tree
Showing 4 changed files with 58 additions and 11 deletions.
20 changes: 18 additions & 2 deletions qmk_firmware/keyboards/keyball/lib/keyball/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Keyball Core Function Library

## Scroll snap mode

TODO

## MEMO

This section contains notes regarding the specifications of this library.
Expand All @@ -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)以上スクロールするとフリーモードに遷移する。
Expand Down
4 changes: 3 additions & 1 deletion qmk_firmware/keyboards/keyball/lib/keyball/keyball.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down
39 changes: 31 additions & 8 deletions qmk_firmware/keyboards/keyball/lib/keyball/keyball.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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);
6 changes: 6 additions & 0 deletions qmk_firmware/keyboards/keyball/lib/keyball/keycodes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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状態、及び自動マウスレイヤのタイムアウト

0 comments on commit 9fd0fb0

Please sign in to comment.