Adding Event Handlers

イベントハンドラの追加

Next, we'll find out how to add event handlers to XBL-defined elements.

次は、XBL で定義された要素にイベントハンドラを追加する方法を見ることにしましょう。

Event Handlers

イベントハンドラ

As you might expect, mouse clicks, key presses and other events are passed to each of the elements inside the content. However, you may wish to trap the events and handle them in a special way. You can add event handlers to the elements inside the content if needed. The last example in the previous section demonstrated this. In that example, oncommand handlers were added to some buttons.

ご存知のように、マウスクリックやキーの押し下げ、その他のイベントは、内容の 中にある個々の要素に送られます。イベントをトラップし、特殊な方法で処理したい かもしれません。必要な場合には、内容の中にある要素にイベントハンドラを追加する ことができます。前のセクションの最後の例は、このことを示しています。その例では、 oncommand ハンドラをボタンの幾つかに追加しました。

However, you may want to add an event handler to the entire contents, that is, all the elements defined in the content tag. This could be useful when trapping the focus and blur events. To define an event handler, use the handler element. Each will describe the action taken for a single event handler. You can use more than one handler if necessary. If an event does not match any of the handler events, it is simply passed to the inner content as usual.

しかし、イベントハンドラを内容全体に追加したいかもしれません。つまり、 content タグ内に 定義されたすべての要素に対してです。これができれば、フォーカスイベントや ブラー (blur) イベントをトラップする場合に役立つでしょう。イベントハンドラを 定義するには、handler 要素を使います。その各々には、イベントハンドラそれぞれのためのアクションを 記述します。必要な場合、複数のハンドラを使うことができます。イベントが handler イベントの どれともマッチしない場合、それは単に、いつものように内側の内容に送られるだけです。

The general handler syntax is as follows:

一般的なハンドラの構文は次の通りです。

<binding id="binding-name">
  <handlers>
    <handler event="event-name" action="script"/>
  </handlers>
</binding>

Place all of your handlers within the handlers element. Each handler element defines the action taken for a particular event specified by its event attribute. Valid event types are those supported by XUL and JavaScript, such as click and focus. Use the event name without the 'on' in front of it.

ハンドラはすべて、handlers 要素の中に置きます。個々の handler 要素には、 event 属性で指定した特定のイベントのための アクションを定義します。妥当なイベント型は、 clickfocus など、 XUL と JavaScript がサポートしているものです。始まりに 'on' のないイベント名を使います。

A common reason to set handlers is to modify the custom properties when an event occurs. For example, a custom checkbox might have a checked property which needs to be changed when the user clicks the checkbox:

ハンドラを設定するよくある理由は、イベントが起こったとき、カスタムプロパティを 変更するためです。例えば、カスタムチェックボックスには、ユーザがチェックボックスを クリックしたとき、変更する必要のある checked プロパティがあるかもしれません。

<handlers>
  <handler event="mouseup" action="this.checked=!this.checked"/>
</handlers>

When the user clicks and releases the mouse button over the check box, the mouseup event is sent to it, and the handler defined here is called, causing the state of the checked property to be reversed. Similarly, you may wish to change a property when the element is focused. You will need to add handlers to adjust the properties whenever input from the mouse or keyboard would require it.

ユーザがチェックボックス上でマウスボタンをクリックしてそれを放すと、 mouseup イベントがチェックボックスに送られ、 ここで定義したハンドラが呼び出されます。その結果、checked プロパティの状態が 反転します。同様に、要素がフォーカスされた場合、プロパティを変更したい場合が あるかもしれません。マウスやキーボードからの入力が要求する場合にはいつでも、 プロパティを調整するハンドラを追加する必要があります。

For mouse events, you can use the button attribute to have the handler only trap events that occur from a certain button. Without this attribute, the handler traps all events regardless of the button that was pressed. The button attribute should be set to either 0 for the left mouse button, 1 for the middle mouse button or 2 for the right mouse button.

マウスイベントの場合、あるボタンで起こったイベントだけをトラップするハンドラに するために、button 属性が使えます。この属性がなければ、 ハンドラは、押されたボタンに関わりなくすべてのイベントをトラップします。 button 属性は、左マウスボタンは 0、中央マウスボタンは 1、 右マウスボタンは 2 に設定します。

<handlers>
  <handler event="click" button="0" action="alert('Left button pressed');"/>
  <handler event="mouseup" button="1" action="alert('Middle button pressed')"/>
  <handler event="click" button="2" action="alert('Right button pressed');"/>
</handlers>

For key events, you can use a number of attributes similar to those for the key element to match a specific key and match only when certain modifer keys are pressed. The previous example could be extended so that the checked property of the check box is changed when the space bar is pressed.

キーイベントの場合、指定のキーにマッチさせるためや、ある修飾キー (modifier key) が押された時だけマッチさせるために、 key 要素がもつ属性に似た数多くの 属性が使えます。前の例を拡張して、スペースバーが押されたら、チェックボックスの checked プロパティが変更されるようにすることができます。

<handlers>
  <handler event="keypress" key=" " action="this.checked=!checked"/>
</handlers>

You can also use the keycode attribute to check for non-printable keys. The section on keyboard shortcuts provides more information. The modifier keys can be checked by adding a modifiers attribute. This should be set to one of the values set below:

  • alt
    The user must press the Alt key.
  • control
    The user must press the Control key.
  • meta
    The user must press the Meta key.
  • shift
    The user must press the Shift key.
  • accel
    The user must press the special modifier key that is usually used for keyboard shortcuts on their platform.

文字で表すことのできないキーをチェックするため、 keycode 属性を使うこともできます。 キーボードショートカットに関するセクション には もっと詳しい情報があります。修飾キーは、modifiers 属性を追加することによりチェックできます。これは、以下の値のいずれかに設定します。

  • alt
    ユーザは、Alt キーを押さなければならない。
  • control
    ユーザは、Control キーを押さなければならない。
  • meta
    ユーザは、Meta キーを押さなければならない。
  • shift
    ユーザは、Shift キーを押さなければならない。
  • accel
    ユーザは、使用しているプラットフォームのキーボードショートカットで 通常使われている、特殊な修飾キーを押さなければならない。

If set, the handler is only called when the modifier is pressed. You can require multiple modifier keys by separating them with spaces.

これを設定した場合、ハンドラは修飾キーが押された時だけ呼び出されます。 複数の修飾キーは、スペースで区切ることによって指定できます。

The following alternate syntax can be used when the code in a handler is more complex:

ハンドラ内のコードがもっと複雑な場合は、次のような別の構文を使うことができます。

<binding id="binding-name">
  <handlers>
    <handler event="event-name">
      -- handler code goes here --
    </handler>
  </handlers>
</binding>

Handlers Example

ハンドラの例

The following example adds some key handlers to create a very primitive local clipboard:

次の例は、キーハンドラを幾つか追加して、非常に原始的なローカルクリップボードを 作成しています。

Example 11.6.1: Source
<binding id="clipbox">
  <content>
    <xul:textbox/>
  </content>
  <implementation>
    <field name="clipboard"/>
  </implementation>
  <handlers>
    <handler event="keypress" key="x" modifiers="control"
      action="this.clipboard=document.getAnonymousNodes(this)[0].value; document.getAnonymousNodes(this)[0].value='';"/>
    <handler event="keypress" key="c" modifiers="control"
      action="this.clipboard=document.getAnonymousNodes(this)[0].value;"/>
    <handler event="keypress" key="v" modifiers="control"
      action="document.getAnonymousNodes(this)[0].value=this.clipboard ? this.clipboard : '';"/>
  </handlers>
</binding>

The content is a single textbox. A field clipboard has been added to it to store the clipboard contents. This does mean that the clipboard operations are limited to this single textbox. However, each one will have its own buffer.

内容は、テキストボックスが一つです。 clipboard フィールドを、クリップボードの内容を保存するために追加しました。これは、 クリップボードの操作がこのテキストボックス一つに限られるということです。 しかし、個々のクリップボードには、それ自身のバッファがあります。

Three handlers have been added, one for cut, one for copy and the other for paste. Each has its own keystroke that invokes it. The first handler is the cut operation and is invoked when the Control key is pressed along with the x key. The script within the action attribute is used to cut the text from the textbox and put it into the clipboard field. For simplicity, the entire text is cut and not just the selected text. The code works as follows:

ハンドラを 3 つ追加しました。一つは切り取りのためのもの、もう一つはコピーの ためのもの、最後は貼り付けのためのものです。それぞれには、それを呼び出すための キーストロークがあります。最初のハンドラは切り取り操作のもので、Control キーと ともに x キーが押されると呼び出されます。action 属性内のスクリプトは、テキストボックスのテキストを切り取り、それを clipboard フィールドに入れるのに使われます。簡単にするため、テキスト全体を切り取るだけで、 選択されたテキストを切り取るようにはなっていません。コードは次のように動作します。

  1. this.clipboard=document.getAnonymousNodes(this)[0].value;
    The first element of the anonymous content array is retrieved which gives a reference to the textbox element, which happens to be the first (and only) element within the content element. The value property is retrieved which will provide the text within the textbox. This is then assigned to the clipboard field. The result is copying the text in the textbox into this special clipboard.
  2. document.getAnonymousNodes(this)[0].value=''
    The text of the textbox is then assigned a value of a null string. This effectively clears the text in the textbox.
  1. this.clipboard=document.getAnonymousNodes(this)[0].value;
    無名内容配列の最初の要素が取得される。これは、 content 要素内の最初 (そして、ただ一つ) の要素である textbox 要素への リファレンスを返す。value プロパティが取得され、テキストボックス内の テキストを得る。次に、この値は clipboard フィールドに割り当てられる。 その結果、テキストボックス内のテキストがこの特殊なクリップボードにコピーされる。
  2. document.getAnonymousNodes(this)[0].value=''
    次いで、textbox のテキストにヌル文字列を割り当てる。これにより、実質上、テキストボックスの テキストがクリアされることになる。

A copy operation is similar but does not the clear the text afterwards. Pasting is the opposite where the value of the textbox is assigned from the value in the clipboard field. If we were creating a real implementation of these clipboard keyboard shortcuts, we would probably use the real clipboard interface and handle the current selection as well.

コピー操作も同様ですが、処理後、テキストをクリアしない点が違います。貼り付けは 逆の操作です。テキストボックスの値が、clipboard フィールドの値から割り当てられます。 こうしたクリップボードのキーボードショートカットを実際に実装する場合は、おそらく、 実際のクリップボードインターフェイスを実装し、現在選択されているテキストも同じように 処理することになるでしょう。


(Next) In the next section, we'll see how to extend existing XBL definitions.

(進む) 次のセクションでは、既にある XBL 定義を拡張する方法を見ることにしましょう。

Examples: 11.6.1


Copyright (C) 1999 - 2004 XulPlanet.com
訳者: kmine
このドキュメントのオリジナルは XULPlanet において英語で公布されています。
またドキュメントの管理の言語は現在も英語です。この日本語訳は、
利用者の利便のために Mozilla Japan 翻訳部門によって提供されたものです。
フィードバックは英語で、元の著者に送って下さい。
翻訳された文書の一覧は、現在以下のURLで見ることが出来ます。
http://www.mozilla.gr.jp/jt/xul/progress.html