Iroha.KeyEquiv

• Necomesi JavaScript Library (Iroha)

概要

キーボード操作による処理呼び出しを簡単に行うための機構を提供します。

動作確認ブラウザ

(fixme)

実装ファイル配置

(fixme)

HTML への組み込み

(fixme)

AutoSetup

(fixme)

動作例

Shift キーを押しながら A キーを押してみてください。

キーコンビネーション指示子

概要

「 Shift キーを押しながら A キーを押す」というようなキーコンビネーションの表記法。あるいはこの表記法を用いた文字列のこと。

この表記法は、同時に押すキーの組み合わせを記述するものであり、 「Q , W , E , R , T , Y の順でキーを押していく」というような事は記述できません。そもそも Iroha.KeyEquiv 自体、そのような逐次キー押下を取り扱う実装が（現時点では）ありません。

記述例

キーコンビネーション指示子中のそれぞれの文字（キー表現記号）は、それぞれが任意のキーに対応します。

• "A" は、「 A キーを押す」ことを表します。
• "$" は、「 Shift キーを押す」ことを表します。
• "$A" は、「 Shift キーを押しながら A キーを押す」ことを表します。
• "$%A" は、「 Shift キー・Ctrl キーを押しながら A キーを押す」ことを表します。
• キー表現記号の出現順に特にルールはありません。つまり、 "$%A" と "A%$" は同じものとして扱われます。
• 同じキー表現記号を複数回含んでいる場合は、それぞれがひとつに集約されて扱われます。つまり、 "$$$%A%AA$" は "$%A" と同じものとして扱われます。

正規化

Iroha.KeyEquiv は、与えられたキーコンビネーション指示子を以下のルールで正規化し、取り扱っています。

1. キーコンビネーション指示子中の重複する文字をひとつに集約
2. キーコンビネーション指示子中の文字をソート

キー表現記号

キーコンビネーション指示子中で使える文字（キー表現記号）は、以下の 4 種類に大別されます。

アルファベットキー

キー表現記号	キー	(Event.keyCode)
A	A	65
B	B	66
C	C	67
:	:	:
Z	Z	90

大文字小文字の区別はありません。

半角数字キー

キー表現記号	キー	(Event.keyCode)
0	0	48
1	1	49
2	2	50
:	:	:
9	9	57

通常の数字キーと、テンキーパッド部の数字キーの区別はありません。

特殊キー

キー表現記号	キー	(Event.keyCode)
|	Tab	9
#	Enter	13
!	Esc	27
<	←	37
{	↑	38
>	→	39
}	↓	40

修飾キー

キー表現記号	キー	(Event.keyCode)
$	Shift	16
%	Ctrl	17
~	Alt , Option	18
&	Windows , Command	(ブラウザ毎に異なる)

注意事項

• ブラウザや OS 本来のキーボード操作を妨げないキーボードコンビネーションを設定するよう、注意してください。
• 加えて、ブラウザ個別の制限事項を考慮すると、修飾キーとして安全に利用できそうなのは Shift キーのみかもしれません。
• 「修飾キー」のみ、他のキーと同時に押されたことを判別できます。例えば、「 Shift キーと A キーが同時に押された」事は判別できますが、「 A と B が同時に押された」事は判別できません。
• ここに挙げた以外のキー（主に記号キーなど）については、サポートされません。動くかもしれませんが、ユーザの使っているキーボードの配列によっては、修飾キーなしには押せないものもあるので、推奨しません。

ブラウザ個別の制限事項

WinIE

Windowsキー の押下を判別することはできません。

MacIE

Command キーの押下を判別することはできません。

Ctrl キーの押下判別（の反応）が鈍く、さらに、単独で押下された時しか判別できません。（ MacIE の GUI に由来する制限）

Gecko 系

Windows キー (Windows) 、 Command キー (Mac) の押下を判別することはできません。

Safari

修飾キーのみの押下を判別することはできません。つまり、修飾キー以外のキーとの組みあわせた時しか判別できません。

Opera

修飾キーのみの押下を判別することはできません。つまり、修飾キー以外のキーとの組みあわせた時しか判別できません。

Shift キー以外の修飾キーは、他ブラウザと比較しても珍妙な取り扱いがされてしまっており、 Iroha.KeyEquiv はそれを吸収しきれません。使用しないほうが良いでしょう。

(fixme) 2009年6月現在、この項の内容は古くなっています。現在は状況が変わっている可能性が大きいです。

コンストラクタ・メソッド解説

Iroha.KeyEquiv(コンストラクタ)

クラスメソッド

Iroha.KeyEquiv.create(node)

引数名	型	説明	任意性
node	jQuery|Element|String	基底要素ノード（キーイベントを拾う要素）。またはそれを見つけるためのセレクタ文字列。無指定時は document.documentElement が与えられたものとみなす。	任意

与えた要素ノードを基底要素ノードとする新規インスタンスを返す。ただしその要素ノードから作られた既存インスタンスがすでにあるなら、それを返す。

返値： Iroha.KeyEquiv インスタンス

Iroha.KeyEquiv.getKeyAlias(keyCode)

引数名	型	説明	任意性
keyCode	Number	特殊キーのキーコード	必須

特殊キーの別名記号をキーコード指定により得る。該当するものがなければ空文字列 "" が返る。

返値： String インスタンス

インスタンスメソッド

Iroha.KeyEquiv#addKey(keys, func, aThisObject)

引数名	型	説明	任意性
keys	String	キーコンビネーション指示子。	必須
func	Iroha.KeyEquiv.callback	keys に指定したキーコンビネーションが押されたときに呼び出される（コールバックされる）関数・メソッド	必須
aThisObject	Object	func 中で "this" キーワードが使用されている場合に、それが指し示すもの（オブジェクト）。 無指定時、 "this" は "window" を指し示すことになります。	任意

何らかの処理と、それを呼び出すためのキー操作（キーコンビネーション）の対応付けを行います。

返値： String（正規化済みのキーコンビネーション指示子）

Iroha.KeyEquiv.fireKey(keys)

引数名	型	説明	任意性
keys	String	キーコンビネーション指示子。	必須

任意のキーコンビネーションに対応付けられている処理の呼び出しを、実際のキーボード操作無しに行います。

返値：なし

Iroha.KeyEquiv.getKeyName(keys)

引数名	型	説明	任意性
keys	String	キーコンビネーション指示子。	必須

キーコンビネーション指示子を与えると、それを人間にとって読みやすい形式へ変換したものが返ります。

たとえば Iroha.KeyEquiv.getKeyName("$%A") とすると、["Shift", "Ctrl", "A"] が得られます。

返値： Array（人間にとって読みやすい形式のキー表記文字列からなる配列）

Iroha.KeyEquiv.callback(Fuction)

Iroha.KeyEquiv.addKeyEquiv() の引数 func に与える関数・メソッド（高階関数）のこと。実際は、引数 func には既存の関数オブジェクトを直接与えることになるので、これをどうこうして使う事は無い。単に（コールバックされた際に与えられる引数の）説明をするためだけの存在。

Iroha.KeyEquiv.callback(e, keys, keyNames)

引数名	型	説明
e	Event	DOM Event オブジェクト ただし Iroha.KeyEquiv.fireKey() によってコールバックされた時は {} です。
keys	String	正規化済みのキーコンビネーション指示子
keyNames	Array	人間にとって読みやすい形式のキー表記文字列からなる配列