キー文字マップファイル（.kcm ファイル）は、Android キーコードと修飾子の組み合わせを Unicode 文字にマッピングします。
デバイスが専用のキーボードである（フルキーボードではない）ことをシステムに伝える場合は、キーを持つすべての内部（組み込み）入力デバイスに、デバイス固有のキーレイアウト ファイルが必要です。
外部キーボードの場合、デバイス固有のキーレイアウト ファイルは任意で、ほとんどの場合は必要ありません。多くの外部キーボードに適した汎用キー文字マップが利用可能です。
デバイス固有のキーレイアウト ファイルがない場合、デフォルトが選択されます。
場所
キー文字マップファイルは、USB ベンダー ID とプロダクト ID（オプションでバージョン ID）、または入力デバイス名で指定します。
次のパスが順に参照されます。
/odm/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm/vendor/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm/system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm/data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm/odm/usr/keychars/Vendor_XXXX_Product_XXXX.kcm/vendor/usr/keychars/Vendor_XXXX_Product_XXXX.kcm/system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm/data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm/odm/usr/keychars/DEVICE_NAME.kcm/vendor/usr/keychars/DEVICE_NAME.kcm/system/usr/keychars/DEVICE_NAME.kcm/data/system/devices/keychars/DEVICE_NAME.kcm/odm/usr/keychars/Generic.kcm/vendor/usr/keychars/Generic.kcm/system/usr/keychars/Generic.kcm/data/system/devices/keychars/Generic.kcm/odm/usr/keychars/Virtual.kcm/vendor/usr/keychars/Virtual.kcm/system/usr/keychars/Virtual.kcm/data/system/devices/keychars/Virtual.kcm
デバイス名を含むファイルパスを作成する場合、デバイス名の「0」～「9」、「a」～「z」、「A」～「Z」、「-」、「_」以外のすべての文字は「_」に置き換えられます。
汎用キー文字マップファイル
システムには、Generic.kcm という特別な組み込みキー文字マップファイルが用意されています。
このキー文字マップは、さまざまな標準の外付けキーボードをサポートするためのものです。
汎用キー文字マップは変更しないでください。
仮想キー文字マップファイル
システムには、仮想キーボード デバイスで使用される、Virtual.kcm という特別な組み込みキー文字マップファイルが用意されています。
仮想キーボード デバイスは、ID が -1 の合成入力デバイスです（KeyCharacterMap.VIRTUAL_KEYBOARD を参照）。Android Honeycomb 3.0 以降のすべての Android デバイスで使用できます。仮想キーボード デバイスの目的は、キーボードが組み込まれていないデバイスであっても、既知の組み込み入力デバイスを使用して、IME または試験装置を通じてキー入力をアプリケーションに挿入できるようにすることです。
仮想キーボードは、完全な QWERTY レイアウトを備えており、どのデバイスでも同じレイアウトになるとみなされます。その結果、アプリケーションで仮想キーボード デバイスを使用してキーストロークを挿入し、常に同じ結果を得ることができます。
なお、仮想キー文字マップは変更しないでください。
構文
キー文字マップファイルは、キーボード タイプ宣言とキー宣言セットで構成される書式なしテキスト ファイルです。
キーボード タイプの宣言
キーボード タイプの宣言では、キーボードの全体的な動作を記述します。 文字マップファイルには、キーボード タイプの宣言を含める必要があります。わかりやすくするため、通常はファイルの先頭に配置されます。
type FULL
次のキーボード タイプが認識されます。
-
NUMERIC: 数字キーボード（12 キー）。数字キーボードは、マルチタップ方式のテキスト入力に対応しています。 目的の文字や記号を生成するには、キーを何回かタップする必要があります。
このタイプのキーボードは、通常、親指での入力を前提に設計されています。
KeyCharacterMap.NUMERICに対応しています。 -
PREDICTIVE: すべての文字に対応しており、キー 1 つに 1 文字以上が割り当てられているキーボード。このタイプのキーボードは、通常、親指での入力を前提に設計されています。
KeyCharacterMap.PREDICTIVEに対応しています。 -
ALPHA: すべての文字と一部の数字に対応したキーボード。アルファベット キーボードは直接のテキスト入力をサポートするものですが、フォーム ファクタの小さい集約レイアウトが可能です。
FULLキーボードとは対照的に、一部の記号を使用するには画面上に別に用意した文字選択ツールを使用する必要があります。また、入力速度や精度を改善するために、自動大文字表記、Shift+Alt キーの固定など、アルファベット キーボードのための特別なアフォーダンスが用意されています。このタイプのキーボードは、通常、親指での入力を前提に設計されています。
-
FULL: 完全なパソコン スタイルのキーボードです。フルキーボードは、パソコンのキーボードのように動作します。すべての記号はキーボード上のキーを押すことで直接利用でき、画面上のサポートや自動大文字表記などのアフォーダンスが不要です。
このタイプのキーボードは、通常、両手での入力を前提に設計されています。
-
SPECIAL_FUNCTION: 入力ではなくシステム制御関数を実行するためにのみ使用されるキーボード。専用ファンクション キーボードは、実際には入力に使用されない非印字キー（HOME や POWER など）のみで構成されます。
Generic.kcm キー文字マップと Virtual.kcm キー文字マップは、どちらも FULL キーボードです。
キーの宣言
キーの宣言は、キーワード key の後に Android キーコード名を続け、さらに各プロパティと動作を中かっこで囲む構成で行われます。
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
プロパティ
各キーのプロパティでは、キーと動作のマッピングを定めます。キー文字マップファイルをよりコンパクトにするために、複数のプロパティをカンマで区切って同じ動作にマッピングできます。
上記の例では、label プロパティに 'A' の動作が割り当てられています。
同様に、ctrl、alt、meta のプロパティには、none の動作が一度に割り当てられています。
次のプロパティが認識されます。
-
label: キーの入力により印字されるラベルが 1 文字の場合に、そのラベルを指定します。これは、KeyCharacterMap.getDisplayLabelメソッドによって返される値です。 -
number: ユーザーが電話番号を入力している場合など、数字のテキストビューにフォーカスがあるときの動作（文字の入力動作）を指定します。コンパクト キーボードでは 1 つのキーに複数の記号がまとめられている場合があります（同じキーが
'1'と'a'、'#'と'q'に使われている場合など）。そのようなキーを使用して数字が入力される場合に、どの記号が入力されるべきかをnumberプロパティで設定します。数字に該当する主な記号は、数字の「
'0'」から「'9'」、「'#'」、「'+'」、「'('」、「')'」、「','」、「'.'」です。 -
base: 修飾子が押されていないときの動作（文字の入力動作）を指定します。 -
<修飾子> または <修飾子 1>
+<修飾子 2>+...: : キーが押され、指定された修飾子がすべてアクティブなときの動作（文字の入力動作）を指定します。たとえば、修飾子プロパティ
shiftは、左 Shift 修飾子または右 Shift 修飾子が押されたときに適用される動作を指定します。同様に、修飾子プロパティ
rshift+raltは、右 Shift 修飾子と右 ALT 修飾子の両方が同時に押されたときに適用される動作を指定します。
次の修飾子は、修飾子プロパティで認識されます。
shift: 左 Shift 修飾子または右 Shift 修飾子が押されたときに適用されます。lshift: 左 Shift 修飾子が押されたときに適用されます。rshift: 右 Shift 修飾子が押されたときに適用されます。alt: 左 Alt 修飾子または右 Alt 修飾子が押されたときに適用されます。lalt: 左 Alt 修飾子が押されたときに適用されます。ralt: 右 Alt 修飾子が押されたときに適用されます。ctrl: 左 Control 修飾子または右 Control 修飾子が押されたときに適用されます。lctrl: 左 Control 修飾子が押されたときに適用されます。rctrl: 右 Control 修飾子が押されたときに適用されます。meta: 左 Meta 修飾子または右 Meta 修飾子が押されたときに適用されます。lmeta: 左 Meta 修飾子が押されたときに適用されます。rmeta: 右 Meta 修飾子が押されたときに適用されます。sym: Symbol 修飾子が押されたときに適用されます。fn: Function 修飾子が押されたときに適用されます。capslock: CapsLock 修飾子がロックされている場合に適用されます。numlock: NumLock 修飾子がロックされている場合に適用されます。scrolllock: ScrollLock 修飾子がロックされている場合に適用されます。
プロパティがリストされる順序は重要です。キーを動作にマッピングすると、関連するすべてのプロパティが順番にスキャンされ、最後に見つかった動作が返されます。
そのため、キーに対して後で指定されたプロパティにより、先に指定されたプロパティがオーバーライドされます。
動作
各プロパティは動作にマッピングされます。最も一般的な動作は文字を入力することですが、他にもあります。
認識される動作は次のとおりです。
-
none: 文字を入力しない。文字が指定されていない場合、この動作がデフォルトになります。
noneの指定は任意ですが、指定することでよりわかりやすくできます。 -
'X': 指定した文字リテラルを入力する。この動作により、指定した文字がフォーカスされたテキストビューに入力されます。文字リテラルは、任意の ASCII 文字、または次のエスケープ シーケンスのいずれかです。
'\\': バックスラッシュ文字を入力。'\n': 改行文字を入力。これは Enter キーと Return キーに使用します。'\t': Tab 文字を入力。'\'': アポストロフィ文字を入力。'\"': 引用符を入力。'\uXXXX': Unicode 文字を入力。16 進数 XXXX でコードポイントを指定します。
-
fallback<Android key code name>: キーがアプリケーションで処理されない場合、デフォルトのアクションを実行。アプリケーションが指定されたキーをネイティブで処理しない場合、このキーを押すと、別のキーの押下がシミュレートされます。数字キーパッドで Numlock キーが押されていない場合や、Escape キーなどは、アプリケーションによっては対応していない場合があり、そのようなキーのデフォルトの動作をサポートするために使用されます。
フォールバック動作が実行されると、アプリケーションは 2 つのキーを受け取ります。1 つは元のキーで、もう 1 つは選択されたフォールバック キーです。アプリケーションがキーアップ中に元のキーを処理した場合、フォールバック キーイベントはキャンセルされます（
KeyEvent.isCanceledはtrueを返します）。
特別な機能を実行するため、システムで次の 2 つの Unicode 文字が予約されています。
-
'\uef00': この動作が実行されると、テキストビューはカーソルの直前にある 4 文字を 16 進数として解釈し、この 4 文字を削除したうえで対応する Unicode コードポイントを挿入します。 -
'\uef01': この動作が実行されると、テキストビューにその他の記号を含む文字選択ダイアログが表示されます。
システムでは、文字キーと組み合わせてダイアクリティカル マークを入力するデッドキーとして、次の Unicode 文字が認識されます。
'\u0300': グレーブ アクセント。'\u0301': アキュート アクセント。'\u0302': サーカムフレックス アクセント。'\u0303': チルダ アクセント。'\u0308': ウムラウト アクセント。
デッドキーを入力した後に別の文字を続けると、その文字とデッドキーが組み合わされます。たとえば、ユーザーがグレーブ アクセントを示すデッドキーの後に文字「a」を入力すると、結果は「à」になります。
デッドキー処理の詳細については、KeyCharacterMap.getDeadChar をご覧ください。
コメント
コメント行は「#」で始まり、行末まで続きます。例:
# A comment!
空白行は無視されます。
キーの組み合わせが動作にマッピングされる仕組み
ユーザーがキーを押すと、そのキーと同時に押されている修飾子の組み合わせに関連付けられた動作が検索されます。
Shift+A
ユーザーが A と Shift を同時に押したとします。システムはまず、KEYCODE_A に関連付けられた一連のプロパティと動作を探します。
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
プロパティを最初から最後、左から右にスキャンし、特別な label プロパティと number プロパティは無視します。
最初に検出されるプロパティは base です。どの修飾子が押されたかに関係なく、base プロパティは常にキーに適用され、原則として、後に続くプロパティによってオーバーライドされない限り、キーのデフォルトの動作を指定します。キーが押されると、この base プロパティが適用されるため、システムには動作が 'a' である（文字 a を入力）が記録されます。
次に、システムはプロパティのスキャンを続け、base よりもさらに個別の指定を行うプロパティがある場合はオーバーライドします。スキャンが続き、Shift+A キーが押された場合の動作を適用する shift が検出されます。その結果、システムは base プロパティの動作を無視し、shift プロパティに関連付けられた動作 'A'（文字 A を入力）を選択します。
その後、テーブルのスキャンは続行されますが、他のプロパティは適用されません（CapsLock はロックされておらず、Ctrl キー、Alt キー、Meta キーも押されていません）。
最終的に、Shift+A キーの組み合わせの動作は 'A' になります。
Ctrl+A
ユーザーが A と Ctrl を同時に押すとどうなるかを考えてみます。
前述のように、システムはプロパティのテーブルをスキャンします。システムは base プロパティが適用されていることを認識しますが、最終的に control プロパティが検出されるまでスキャンを続けます。この場合、control プロパティが base プロパティの後になるため、base の動作はオーバーライドされます。
つまり、Ctrl+A キーの組み合わせの動作は none になります。
Esc
ユーザーが Esc を押したとします。
key ESCAPE {
base: fallback BACK
alt, meta: fallback HOME
ctrl: fallback MENU
}
この場合、システムは fallback BACK、つまりフォールバック動作を取得し、
文字リテラルは表示されないため、文字は入力されません。
キーを処理する際、システムは最初に KEYCODE_ESCAPE をアプリケーションに渡します。アプリケーションがそれを処理しない場合、システムは再試行しますが、今回は、フォールバック動作のリクエストに応じて KEYCODE_BACK をアプリケーションに渡します。
アプリケーションが KEYCODE_ESCAPE に対応している場合は、それを認識してそのまま処理しますが、処理できないアプリケーションの場合は、キーを KEYCODE_BACK として処理するフォールバック動作を実行します。
NUMPAD_0 の NumLock のオン / オフによる違い
数字キーパッドの解釈は、NumLock キーがロックされているかどうかによって大きく異なります。
次のキー宣言により、NumLock が押されたときの KEYCODE_NUMPAD_0 タイプが 0 になります。NumLock が押されていない場合、通常どおりキーがアプリケーションに渡され、処理されない場合はフォールバック キー KEYCODE_INSERT が渡されます。
key NUMPAD_0 {
label, number: '0'
base: fallback INSERT
numlock: '0'
ctrl, alt, meta: none
}
古いアプリケーションでは、パソコン スタイルのフルキーボードにあるキーをすべて認識しなかったり、直接サポートしていない場合があります。そのような場合も、上記のように、フォールバック キーを宣言することで互換性が大幅に改善します。
例
フルキーボード
# This is an example of part of a key character map file for a full keyboard
# include a few fallback behaviors for special keys that few applications
# handle themselves.
type FULL
key C {
label: 'C'
base: 'c'
shift, capslock: 'C'
alt: '\u00e7'
shift+alt: '\u00c7'
ctrl, meta: none
}
key SPACE {
label: ' '
base: ' '
ctrl: none
alt, meta: fallback SEARCH
}
key NUMPAD_9 {
label, number: '9'
base: fallback PAGE_UP
numlock: '9'
ctrl, alt, meta: none
}
英数字キーボード
# This is an example of part of a key character map file for an alphanumeric
# thumb keyboard. Some keys are combined, such as `A` and `2`. Here we
# specify `number` labels to tell the system what to do when the user is
# typing a number into a dial pad.
#
# Also note the special character '\uef01' mapped to ALT+SPACE.
# Pressing this combination of keys invokes an on-screen character picker.
type ALPHA
key A {
label: 'A'
number: '2'
base: 'a'
shift, capslock: 'A'
alt: '#'
shift+alt, capslock+alt: none
}
key SPACE {
label: ' '
number: ' '
base: ' '
shift: ' '
alt: '\uef01'
shift+alt: '\uef01'
}
ゲームパッド
# This is an example of part of a key character map file for a game pad.
# It defines fallback actions that enable the user to navigate the user interface
# by pressing buttons.
type SPECIAL_FUNCTION
key BUTTON_A {
base: fallback BACK
}
key BUTTON_X {
base: fallback DPAD_CENTER
}
key BUTTON_START {
base: fallback HOME
}
key BUTTON_SELECT {
base: fallback MENU
}
互換性に関する注意事項
Android Hkeycomb 3.0 より前のバージョンでは、Android キー文字マッピングは大きく異なる構文で指定され、ビルド時にバイナリ ファイル形式（.kcm.bin）にコンパイルされていました。
新しいフォーマットでは同じ拡張機能（.kcm）を使用しますが、構文がかなり異なっており、より機能が充実しています。
Android Honeycomb 3.0 以降では、すべての Android キー文字マップファイルで、このドキュメントで説明する新しい構文と書式なしテキストのファイル形式を使用する必要があります。古い構文はサポートされておらず、古い .kcm.bin ファイルはシステムで認識されません。
言語に関する注意事項
Android は現在、多言語キーボードに対応していません。また、組み込みの汎用キー文字マップはアメリカ英語キーボードのレイアウトを前提としており、
OEM でキーボードを他の言語用に設計する場合は、カスタムキー文字マップの提供が推奨されます。
Android の今後のバージョンでは、多言語キーボードやユーザーが選択できるキーボード レイアウトがサポートされる可能性があります。
検証
キー文字マップファイルを検証するには、キーマップを検証するのツールを使用してください。