avr/qmk/firmware - [no description]

diff options

Diffstat (limited to 'tmk_core/protocol/news.c')

0 files changed, 0 insertions, 0 deletions

# キーボードの挙動をカスタマイズする方法  多くの人にとって、カスタムキーボードはボタンの押下をコンピュータに送信するだけではありません。単純なボタンの押下やマクロよりも複雑なことを実行できるようにしたいでしょう。QMK にはコードを挿入したり、機能を上書きしたり、様々な状況でキーボードの挙動をカスタマイズできるフックがあります。このページでは、QMK に関する特別な知識は想定していませんが、[QMK の理解](ja/understanding_qmk.md)を読むとより根本的なレベルで何が起きているかを理解するのに役立ちます。 ## コア、キーボード、キーマップ階層 :id=a-word-on-core-vs-keyboards-vs-keymap 私たちは QMK を階層として構造化しました: * コア (`_quantum`) * キーボード/リビジョン (`_kb`) * キーマップ (`_user`) 以下で説明される各関数は `_kb()` サフィックスあるいは `_user()` サフィックスを使って定義することができます。`_kb()` サフィックスはキーボード/リビジョンレベルで使うことを意図しており、一方で `_user()` サフィックスはキーマップレベルで使われるべきです。キーボード/リビジョンレベルで関数を定義する場合、`_kb()` は他の何かを実行する前に `_user()` を呼び出すよう実装することが重要です。そうでなければ、キーマップレベル関数は呼ばれないでしょう。 # カスタムキーコード最も一般的なタスクは、既存のキーコードの挙動を変更するか、新しいキーコードを作成することです。コードの観点からは、それぞれの仕組みは非常に似ています。 ## 新しいキーコードの定義独自のカスタムキーコードを作成する最初のステップは、それらを列挙することです。これは、カスタムキーコードに名前を付け、そのキーコードにユニークな番号を割り当てることの両方を意味します。QMK は、カスタムキーコードを固定範囲の番号に制限するのではなく、`SAFE_RANGE` マクロを提供します。カスタムキーコードを列挙する時に `SAFE_RANGE` を使うと、ユニークな番号を取得することが保証されます。これは2つのキーコードを列挙する例です。このブロックを `keymap.c` に追加した後で、キーマップの中で `FOO` と `BAR` を使うことができます。 ```c enum my_keycodes { FOO = SAFE_RANGE, BAR }; ``` ## 任意のキーコードの挙動のプログラミング :id=programming-the-behavior-of-any-keycode 既存のキーの挙動を上書きしたい場合、あるいは新しいキーについて挙動を定義する場合、`process_record_kb()` および `process_record_user()` 関数を使うべきです。これらは実際のキーイベントが処理される前のキー処理中に QMK によって呼び出されます。これらの関数が `true` を返す場合、QMK はキーコードを通常通りに処理します。これは、キーを置き換えるのではなく、キーの機能を拡張するのに便利です。これらの関数が `false` を返す場合、QMK は通常のキー処理をスキップし、必要なキーのアップまたはダウンイベントを送信するのかはユーザ次第です。これらの関数はキーが押されるか放されるたびに呼び出されます。 ### `process_record_user()` の実装例この例は2つの事を行います。`FOO` と呼ばれるカスタムキーコードの挙動を定義し、Enter キーが押されるたびに音を再生します。 ```c bool process_record_user(uint16_t keycode, keyrecord_t *record) { switch (keycode) { case FOO: if (record->event.pressed) { // 押された時に何かをします } else { // 放された時に何かをします } return false; // このキーの以降の処理をスキップします case KC_ENTER: // enter が押された時に音を再生します if (record->event.pressed) { PLAY_SONG(tone_qwerty); } return true; // QMK に enter のプレスまたはリリースイベントを送信させます default: return true; // 他の全てのキーコードを通常通りに処理します } } ``` ### `process_record_*` 関数のドキュメント * キーボード/リビジョン: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` * キーマップ: `bool process_record_user(uint16_t keycode, keyrecord_t *record)` `keycode` 引数はキーマップで定義されているものです。例えば `MO(1)`、`KC_L` など。これらのイベントを処理するには `switch...case` ブロックを使うべきです。 `record` 引数は実際のプレスに関する情報を含みます: ```c keyrecord_t record { keyevent_t event { keypos_t key { uint8_t col uint8_t row } bool pressed uint16_t time } } ``` # LED 制御 QMK は HID 仕様で定義された5つの LED の読み取りメソッドを提供します: * Num Lock * Caps Lock * Scroll Lock * Compose * Kana ロック LED の状態を取得するには2つの方法があります: * `bool led_update_kb(led_t led_state)` あるいは `_user(led_t led_state)` を実装する、または * `led_t host_keyboard_led_state()` を呼び出す !> `host_keyboard_led_state()` は `led_update_user()` が呼ばれる前に新しい値を既に反映している場合があります。 LED の状態を `uint8_t` として提供する2つの非推奨の関数があります: * `uint8_t led_set_kb(uint8_t usb_led)` と `_user(uint8_t usb_led)` * `uint8_t host_keyboard_leds()` ## `led_update_user()` この関数はこれら5つの LED のいずれかの状態が変化すると呼ばれます。LED の状態を構造体のパラメータとして受け取ります。慣例により、`led_update_kb()` にそのコードを実行するようフックさせるために `led_update_user()` から `true` を返し、`led_update_kb()` でコードを実行したくない場合は `false` を返します。以下はいくつかの例です: - レイヤー表示のような何かのために LED を使うために LED を上書きする - `_kb()` 関数を実行したくないので、`false` を返します。これはレイヤーの挙動を上書きするためです。 - LED がオンあるいはオフになった時に音楽を再生する。 - `_kb` 関数を実行したいので、`true` を返します。これはデフォルトの LED の挙動に追加されます。 ?> `led_set_*` 関数は `bool` の代わりに `void` を返すため、キーボードの LED 制御を上書きすることができません。従って、代わりに `led_update_*` を使うことをお勧めします。 ### `led_update_kb()` の実装例 ```c bool led_update_kb(led_t led_state) { bool res = led_update_user(led_state); if(res) { // writePin は 1 でピンを high に、0 で low に設定します。 // この例では、ピンは反転していて、 // low/0 は LED がオンになり、high/1 は LED がオフになります。 // この挙動は、LED がピンと VCC の間にあるか、ピンと GND の間にあるかどうかに依存します。 writePin(B0, !led_state.num_lock); writePin(B1, !led_state.caps_lock); writePin(B2, !led_state.scroll_lock); writePin(B3, !led_state.compose); writePin(B4, !led_state.kana); } return res; } ``` ### `led_update_user()` の実装例この不完全な例は Caps Lock がオンまたはオフになった場合に音を再生します。また LED の状態を保持する必要があるため、`true` を返します。 ```c #ifdef AUDIO_ENABLE float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND); float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND); #endif bool led_update_user(led_t led_state) { #ifdef AUDIO_ENABLE static uint8_t caps_state = 0; if (caps_state != led_state.caps_lock) { led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off); caps_state = led_state.caps_lock; } #endif return true; } ``` ### `led_update_*` 関数のドキュメント * キーボード/リビジョン: `bool led_update_kb(led_t led_state)` * キーマップ: `bool led_update_user(led_t led_state)` ## `host_keyboard_led_state()` 最後に受信した LED の状態を `led_t` として取得するためにこの関数を呼びます。これは、`led_update_*` の外部から、例えば [`matrix_scan_user()`](#matrix-scanning-code) の中で LED の状態を読み取るのに便利です。 ## 物理的な LED の状態の設定一部のキーボードの実装は、物理的な LED の状態を設定するための便利なメソッドを提供しています。 ### Ergodox キーボード Ergodox の実装は、個々の LED をオンあるいはオフにするために `ergodox_right_led_1`/`2`/`3_on`/`off()` と、インデックスによってそれらをオンあるいはオフにするために `ergodox_right_led_on`/`off(uint8_t led)` を提供します。さらに、LED の明度を指定することができます。全ての LED に同じ明度を指定するなら `ergodox_led_all_set(uint8_t n)` を使い、個別の LED の明度を指定するなら `ergodox_right_led_1`/`2`/`3_set(uint8_t n)` を使い、LED のインデックスを指定して明度を指定するには `ergodox_right_led_set(uint8_t led, uint8_t n)` を使います。 Ergodox キーボードは、最低の明度として `LED_BRIGHTNESS_LO` を、最高の輝度(これはデフォルトです)として `LED_BRIGHTNESS_HI` も定義しています。 # キーボードの初期化コードキーボードの初期化プロセスには幾つかのステップがあります。何をしたいかによって、どの関数を使うべきかに影響します。 3つの主な初期化関数があり、呼び出される順番にリストされています。 * `keyboard_pre_init_*` - ほとんどのものが開始される前に起こります。非常に早くに実行したいハードウェアのセットアップに適しています。 * `matrix_init_*` - ファームウェアのスタートアッププロセスの途中で起こります。ハードウェアは初期化されますが、機能はまだ初期化されていない場合があります。 * `keyboard_post_init_*` - ファームウェアのスタートアッププロセスの最後に起こります。これはほとんどの場合、 "カスタマイズ"コードを配置する場所です。 !> ほとんどの人にとって、`keyboard_post_init_user` が呼び出したいものです。例えば、ここで RGB アンダーグローのセットアップを行います。 ## キーボードの事前初期化コード


context:
space:
mode: