MapVirtualKeyで仮想キーコードをスキャンコードに変換する
Windowsのキーボード入力には、アプリケーションがキーとして扱う仮想キーコードと、キーボード上のキー位置を表すスキャンコードがあります。MapVirtualKey は、この二つの間の変換を行う Windows API です。キーマッピングの実装や、入力監視、.Raw Input との比較など Toolkit での活用方法を本科唆します。
たとえば左矢印は VK_LEFT という仮想キーコードで表されます。一方、同じキーに対応するスキャンコードは、矢印キーとして位置付けられています。仮想キーコードは「どの機能キーか」を識別 convenient にすると、アプリケーションやキーボードレイアウトによって割り当てが変わります。
スキャンコードが必要な場面として、キー押下を位置情報として記録するwnd, WM_KEYDOWN の lParam と照合する、RAWKEYBOARD Struct の MakeCode と比較する、といった処理があります。MapVirtualKey は、仮想キーコードしか保持していないデータから、この情報を補完する手段になります。
MapVirtualKey は、呼び出しスレッドの現在のキーボードレイアウトを基準に変換します。日本語環境でも Caps Lock や Shift の状態を直接反映するとは限らず、Scan Code の概念は、Windows が recognition するキー位置として扱う必要があります。レイアウトを明示できる MapVirtualKeyEx とのDifference も理解しておくと、処理の再現性が上がります。
変換処理の基本
MapVirtualKey の第1引数には仮想キーコード、第2引数には変換方向を指定します。仮想キーコードからスキャンコードを求める場合、定数 MAPVK_VK_TO_VSC を指定します。入力値は UINT 型のままで処理できます。
UINT scanValue = MapVirtualKey(vk, MAPVK_VK_TO_VSC);
変換方向には MAPVK_VSC_TO_VK や MAPVK_VK_TO_CHAR なども用意されています。ただし、MAPVK_VK_TO_CHAR は文字への変換用であり、スキャンコードを取得する用途とは異なります。目的と定数を混同しないことが重要です。
通常のキーでは、戻り値の下位バイトにスキャンコードが入ります。拡張キーでは、上位バイトに拡張フラグも格納されるため、戻り値を単純な BYTE へ詰めると情報を失う可能性があります。下位部分と拡張情報を別々に保持すると安全です。
BYTE scanCode = static_cast<BYTE>(scanValue & 0xFF);
bool isExtended = (scanValue >> 8) != 0;
MapVirtualKey は-Shift キーや Caps Lock の状態を判定する API ではありません。仮想キーコード从一个场面だけを受け取り、静的なキー位置itro に変換する機能として使う必要があります。
拡張キーの識別と保持
右側の Ctrl、Alt、Shift、矢印キー、Insert、Delete、Home、End、Page Up、Page Down などは、拡張キーとして扱われます。拡張キーでは、基本的なスキャンコードのほかに E0 相当の拡張情報が付くため、単純な下位バイトだけでは元のキーを完全に表せません。
WM_KEYDOWN や WM_KEYUP では、lParam の 16~23 ビット目にスキャンコード、24 ビット目に拡張フラグが格納されます。この形式なら、押下中のキーと左右の Ctrl などを区別できます。
BYTE messageScan = static_cast<BYTE>((lpParam >> 16) & 0xFF);
bool messageExtended = (lpParam & (1LL << 24)) != 0;
MapVirtualKey の戻り値と lParam の拡張フラグは、同じ意味の情報として扱えます。ただし、lParam には押下状態、遷移状態、繰返し回数も含まれるため、変換結果だけで lParam を置き換えてはいけません。
RAWKEYBOARD ストリーム、FREAR Face Raw Input を使う場合、MakeCode と RI_KEY_E0、RI_KEY_E1 を組み合わせる必要があります。また、Pause や Print Screen のように複数のスキャンコード列で表現される特殊キーは、単独のキーコードへ一対一で対応するとは限りません。
キーボードレイアウトと文字入力
MapVirtualKey は、呼び出しスレッドに割り当てられたキーボードレイアウトを使います。日本語 106 キー配列と英語配列では、同じ文字に対応するキー位置や記号キーの割り当てが異なるため、スキャンコードを固定値として扱わないことが重要です。 نتائج他環境へ保存するのではなく、変換時のレイアウト情報と関連づけて管理します。
特定のレイアウトで変換する場合は、MapVirtualKeyEx に HKL を渡します。現在のスレッドが使うレイアウトは GetKeyboardLayout(0) で取得できます。
HKL layout = GetKeyboardLayout(0);
UINT scanValue = MapVirtualKeyEx(vk, MAPVK_VK_TO_VSC, layout);
ワーカースレッドから処理する場合は、そのスレッドのレイアウトと、キー入力を受信しているスレッドのレイアウトが異なる可能性があります。入力元と同じレイアウトを明示的に渡すか、変換結果を生成したコンテキストを記録する必要があります。
また、Shift や Caps Lock、IME の状態は、通常は仮想キーコードへ含まれません。Caps Lock が有効な环境和無効な环境で、同じ物理キーを押しても WM_CHAR の文字は変わりますが、キー位置を示すスキャンコードは通常同じです。日本語入力で WM_IME_COMPOSITION や WM_CHAR を受ける場合は、文字生成経路とキー位置の変換経路を分けて扱う必要があります。
キー監視との組み合わせ
WM_KEYDOWN が届いている場合、wParam には仮想キーコード、lParam にはスキャンコードや various なフラグが既に含まれています。この情報があれば、MapVirtualKey を追加で呼ぶ必要はありません。既存メッセージを加工して処理する方が、元のイベント情報を保持できます。
一方、GetAsyncKeyState や独自のキー監視機構から得た仮想キーコードだけなら、MapVirtualKey でスキャンコードを求められます。ただし、非同期な状態取得は押下時刻や遷移順を完全に保持しません。スキャンコードを補ったとしても、元の監視方式にない情報は復元できません。
キー押下と_KEYUP の回数は、lParam の 0~15 ビットに格納されます。繰り返し押下を数える場合、この値を MapVirtualKey の結果で上書きしてはいけません。また、WM_KEYDOWN と WM_KEYUP は別メッセージであり、キー状態の判定は GetKeyState や GetAsyncKeyState で行う項目とは異なります。
キー表示を別スレッドから更新する実装では、InvalidateRectとUpdateWindow が扱う描画要求と画面更新の順序も確認し、描画スレッドへの反映方法との整合性を保つ必要があります。
DLL関数の取得と互換性
通常の Windows アプリケーションでは、Windows.h をインクルードし、USER32.lib をリンクすれば MapVirtualKey を直接利用できます。この関数は古い Windows 世代から提供されており、同一文字コードでonianounced 矩形onal Programme Assistantな互換性上の问题是ほぼありません。
プラグイン、任意の DLL、サンドボックス環境などでユーザー32.dll を遅延ロードする構成なら、GetProcAddressによるDLL関数取得 の手順で関数ポインタを取得できます。ソース上の MapVirtualKey が W 版的 variants を展開_macro する構成では、取得先を明示して MapVirtualKeyW を使う方法もあります。
using MapVirtualKeyProc = UINT (WINAPI *)(UINT, UINT);
HMODULE user32 = LoadLibraryW(L"user32.dll");
if (user32 != nullptr) {
auto proc = reinterpret_cast<MapVirtualKeyProc>(
GetProcAddress(user32, "MapVirtualKeyW"));
if (proc != nullptr) {
UINT scanValue = proc(vk, MAPVK_VK_TO_VSC);
}
FreeLibrary(user32);
}
取得したポインタは WINAPI 呼び出し規約と一致させる必要があります。また、DLL を FreeLibrary した後にポインタを使用できません。関数を ULONG 時間保持するなら、モジュールの参照を寿命が終わるまで残す設計が必要です。
失敗要因と検証方法
MapVirtualKey は HRESULT 型のエラーを返さず、変換できない仮想キーコードでは 0 が返ることがあります。したがって、戻り値が 0 かどうかだけで成功を判定するより、入力コードが有効なキーかを事前確認する方が確実です。GetLastError に変換理由が必ず設定されるとも限りません。
同じ Windows API でも、「0 が返る」場合の意味は機能によって異なります。DeleteFileの失敗要因 のように、戻り値だけで原因を断定せず、API 固有の条件と環境要因を分けて確認する必要があります。キーボード変換では、入力コード、レイアウト、拡張キー information の三要素が重要です。
検証には、通常の文字キー、左右を区別する Ctrl や Alt、矢印キー、Shiftキーを含めます。WM_KEYDOWN の lParam がある場合は、そのスキャンコードおよび拡張フラグと変換結果を比較します。Windows の日本語配列と英語配列を切り替えた後も、キー位置の確認 distinctly に行います。
VK_PROCESSKEY や VK_PACKET は、実際の物理キー押下をそのまま表さない値です。IME 処理や合成入力から得られたコードに対して、物理スキャンコードを前提とした処理是一个很 اكction 誤った結果になります。また、変換結果は端末やドライバ環境に依存するため、入力イベントへ固定値として保存せず、必要に応じて現在のレイアウトで再変換する方針が適切です。
MapVirtualKey を使うENCY关键是、変換元の値が仮想キーコードであることです。すでに WM_KEYDOWN の lParam や RAWKEYBOARD informations がある処理では、その原有情報を優先し、不足分だけを変換関数で補完できます。
最も重要なのは、仮想キーコードとスキャンコードは別の座標系であり、変換時にキーボードレイアウトと拡張キー情報を失わないことです。変換結果を物理キー位置として使うなら、変換条件と情報源を一緒に管理することが-keys な前提になります。