org.w3c.dom.events

インタフェース EventTarget

public interface EventTarget

EventTarget インタフェースは、DOM イベントモデルをサポートする実装では、すべての Nodes によって実装されます。そのため、このインタフェースは、Node インタフェースのインスタンスに対してバインディング固有のキャストメソッドを使用して取得できます。このインタフェースでは、EventTarget への EventListeners の登録と削除、およびその EventTarget へのイベントのディスパッチが可能になります。

「Document Object Model (DOM) Level 2 Events Specification」も参照してください。

導入されたバージョン:

DOM Level 2

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
void	addEventListener(String type, EventListener listener, boolean useCapture) このメソッドでは、イベントターゲットにイベントリスナーを登録できます。
boolean	dispatchEvent(Event evt) このメソッドでは、実装イベントモデルにイベントをディスパッチできます。
void	removeEventListener(String type, EventListener listener, boolean useCapture) このメソッドでは、イベントターゲットからイベントリスナーを削除できます。

メソッドの詳細

addEventListener

void addEventListener(String type,
                    EventListener listener,
                    boolean useCapture)

このメソッドでは、イベントターゲットにイベントリスナーを登録できます。EventListener は、イベント処理中に EventTarget に追加された場合、現在のアクションによってはトリガーされませんが、イベントフローのあとの段階 (バブルフェーズなど) でトリガーされることがあります。
複数の同じ EventListener が同じパラメータで同じ EventTarget に登録されている場合は、重複するインスタンスが破棄されます。これによって EventListener が 2 回呼び出されることはなく、またこれらは破棄されるため、removeEventListener メソッドを使用して削除する必要はありません。

パラメータ:

type - ユーザーが登録しているイベントの型

listener - listener パラメータには、イベントが発生したときに呼び出されるメソッドを含む、ユーザーによって実装されたインタフェースを指定する。

useCapture - true の場合、useCapture はユーザーがキャプチャーを開始することを示す。キャプチャーを開始したあとは、指定された型のすべてのイベントが、ツリー内で自身の下にある EventTargets にディスパッチされる前に、登録された EventListener にディスパッチされる。ツリーを介して上方へ向かってバブルしているイベントは、キャプチャーを使用するように指定された EventListener をトリガーしない。

removeEventListener

void removeEventListener(String type,
                       EventListener listener,
                       boolean useCapture)

このメソッドでは、イベントターゲットからイベントリスナーを削除できます。EventListener は、イベント処理中に EventTarget から削除された場合、現在のアクションによってはトリガーされません。EventListener を、削除されたあとに呼び出すことはできません。
現在 EventTarget に登録されているどの EventListener も識別しない引数で removeEventListener を呼び出しても効果はありません。

パラメータ:

type - 削除される EventListener のイベントの型を指定する。

listener - EventListener パラメータは削除される EventListener を示す。

useCapture - 削除される EventListener がキャプチャーリスナーとして登録されたかどうかを指定する。リスナーを 2 回登録した場合、1 回はキャプチャーとして、もう 1 回はキャプチャーとしてではなく登録したのであれば、それぞれのリスナーを別々に削除しなければならない。また、そのような場合、キャプチャーリスナーを削除しても、非キャプチャーリスナーには影響が及ばない。その逆の削除でも同様である。

dispatchEvent

boolean dispatchEvent(Event evt)
                      throws EventException

このメソッドでは、実装イベントモデルにイベントをディスパッチできます。このようにディスパッチされたイベントは、実装によって直接ディスパッチされたイベントと同じようにキャプチャーとバブリングを実行します。イベントのターゲットは、dispatchEvent が呼び出される EventTarget です。

パラメータ:

evt - イベントの処理で使用されるイベントの型、動作、およびコンテキスト情報を指定する。

戻り値:

dispatchEvent の戻り値は、イベントを処理したいずれかのリスナーが preventDefault を呼び出したかどうか示す。preventDefault が呼び出された場合、この値は false。それ以外の場合、この値は true。

例外:

EventException - UNSPECIFIED_EVENT_TYPE_ERR: dispatchEvent が呼び出される前に、イベントを初期化することによって Event の型が指定されなかった場合に発生します。Event の型を null または空の文字列として指定した場合も、この例外がトリガーされます。