Platform: All
Version: Flash 9 and above
シンタックス[*1]
public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
|
[訳者注*1] EventDispatcherクラスのパッケージと継承、およびサブクラスはつぎのとおりです。
| パッケージ |
flash.events |
| 継承 |
EventDispatcher > Object |
| サブクラス |
Camera、ContextMenu、ContextMenuItem、DisplayObject、FileReference、FileReferenceList、IME、LoaderInfo、LocalConnection、Microphone、NetConnection、NetStream、PrintJob、SharedObject、Socket、Sound、SoundChannel、StyleSheet、Timer、URLLoader、URLStream、XMLSocket |
なお、EventDispatcherクラスについては、akihiro kamijo「EventDispatcherクラス」をご参照ください。
|
引数
type:String ― イベントのタイプ。
listener:Function ― イベントを処理するリスナー関数(function)。この関数は、唯一の引数としてイベントオブジェクトを受取る必要があります。そして、値を返すことはできません。以下の例のとおりです。
function(evt:Event):void
関数(function)名は、任意です。
useCapture:Boolean (デフォルト = false) ― リスナーがキャプチャーフェーズとターゲットおよびバブリングフェーズのどちらで動作するのかを指定します。useCaptureをtrueに設定すると、リスナーはイベントをキャプチャーフェーズのみで処理し、ターゲットおよびバブリングフェーズでは扱いません。useCaptureがfalseですと、リスナーはイベントをターゲットおよびバブリングフェーズのみで処理します。3つのフェーズすべてでイベントを受取るには、addEventListenerを2度呼出します。最初はuseCaptureをtrueに設定し、つぎにuseCaptureはfalseに設定します。
priority:int (デフォルト = 0) ― イベントリスナーの優先順位。優先度は、32ビット符号つき整数で指定します。数値が大きいほど、優先度は高くなります。優先度nのすべてのリスナーは、優先度n-1のリスナーより先に処理されます。複数のリスナーが同じ優先度をともにもっているときは、リスナーとして追加された順序で処理されます。デフォルトの優先度は0です。
useWeakReference:Boolean (デフォルト = false) ― リスナーへの参照が強いか弱いかを指定します。強い参照(デフォルト)は、リスナーがガーベジコレクションの対象になりません。弱い参照は、ガーベジコレクションが働きます[*2]。
例外のスロー
ArgumentError ― 指定されたリスナーが、functionではありません。
説明
イベントリスナーオブジェクトをEventDispatcherオブジェクトに登録し、リスナーがイベントの通知を受取れるようにします[*3]。イベントリスナーは、ディスプレイリストのすべてのノードについて、指定したイベントとフェーズ、優先度で登録することができます。
イベントリスナーを正しく登録した後は、addEventListener()をさらに呼出して優先度を変えることはできません。リスナーの優先度を変更するには、まずremoveListener()を呼出さなければなりません。そのうえで、リスナーを再度登録して、新たな優先順位を指定します。
リスナーを登録した後、さらに続けてaddEventListener()を呼出し、異なったtypeやuseCaptureの値を指定すると、別個のリスナー登録が行われる結果になりますので、ご注意ください。たとえば、まずリスナーをuseCaptureがtrueの設定で登録すると、リスナーはキャプチャーフェーズでのみイベントを検知します。そこで再度同じリスナーオブジェクトを用いてaddEventListener()を呼出し、ただしuseCaptureをfalseに設定したとします。すると、ふたつの異なったリスナーが存在することになります。ひとつはキャプチャーフェーズで検知し、もうひとつはターゲットおよびバブリングフェーズを検知します。
イベントリスナーを、ターゲットフェーズまたはバブリングフェーズのどちらかのみに登録することはできません。これらのフェーズは、登録時に結びつけられています。なぜなら、バブリングというのが、ターゲットノードの上位ノードに対してのみ適用されるものだからです。
もし、イベントリスナーがもはや不要になったときは、removeEventListener()を呼出して削除します。そうしないと、メモリの問題が生じるかもしれません。イベントリスナーが登録されたオブジェクトは、メモリから自動的に削除されることはありません。なぜなら、ガーベジコレクションは、参照を保持しているオブジェクトは削除しないからです。
EventDispatcherインスタンスを複製しても、インスタンスに加えたイベントリスナーは複製されません(新規に作成したノードがイベントリスナーを必要とする場合は、ノード作成後にリスナーを追加しなければなりません)。しかしながら、EventDispatcherインスタンスを移動したときは、設定されたイベントリスナーもインスタンスとともに移動します。
イベントリスナーがノードに登録されたとき、そのノードのイベントが処理中だった場合には、そのイベントリスナーは現行フェーズ中は呼出しされません。バブリングフェーズのような、イベントフローの次回のフェーズから呼出されることになります。
イベントリスナーがノードから削除されたとき、そのノードのイベントが処理中だった場合には、現行のアクションはまだ通知されます。削除後は、イベントリスナーが2度と呼出されることはありません(後の処理に備えて再度登録されないかぎりは)。
|
[訳者注*3] EventDispatcher.addEventListener()メソッドを用いた実用的なサンプルをご紹介します。以下のクラスMyButton(スクリプト001)は、MovieClipシンボルのリンケージに[Class]として設定します。そのMovieClipインスタンスに対しては、ActionScript 1.0/2.0と同じスタイルで、onPressやonRelease、そしてonReleaseOutsideイベントハンドラメソッドが記述できます(後述スクリプト002がその例です)。
MovieClipに[Class]を設定するには、[Library]でMovieClipシンボルをクリックしてから、オプションポップアップメニューで[Linkage]を選択し、[Linkage Properties]ダイアログボックスを開きます。[Linkage]の[Export for ActionScript]のオプションにチェックをつけ、[Class]のテキストボックスにクラス名MyButtonを入力します(図001)。
図001■[Linkage Properties]ダイアログボックスで[Class]を設定
[Linkage]の[Export for ActionScript]のオプションにチェックをつける
スクリプト001■クラスMyButton
|
// ActionScript 3.0クラス定義ファイル: MyButton.as
// MovieClipシンボルの[Class]に設定
package {
import flash.display.MovieClip;
import flash.events.MouseEvent;
public class MyButton extends MovieClip {
public var onPress:Function;
public var onRelease:Function;
public var onReleaseOutside:Function;
function MyButton() {
addEventListener(MouseEvent.MOUSE_DOWN, press);
}
function press(eventObject:MouseEvent):void {
callEvent(onPress, eventObject);
setMouseUp();
}
function release(eventObject:MouseEvent):void {
clearMouseUp();
callEvent(onRelease, eventObject);
}
function releaseOutside(eventObject:MouseEvent):void {
clearMouseUp();
callEvent(onReleaseOutside, eventObject);
}
function setMouseUp():void {
addEventListener(MouseEvent.MOUSE_UP, release);
stage.addEventListener(MouseEvent.MOUSE_UP, releaseOutside);
}
function clearMouseUp():void {
removeEventListener(MouseEvent.MOUSE_UP, release);
stage.removeEventListener(MouseEvent.MOUSE_UP, releaseOutside);
}
function callEvent(eventFunction:Function, eventObject:MouseEvent):void {
if (eventFunction is Function) {
// インスタンスへの参照を保持するためFunction.apply()メソッドを使用
eventFunction.apply(this, [eventObject]);
}
}
}
}
|
クラスMyButtonをテストするには、たとえばフレームアクションとして以下のスクリプトを記述します(スクリプト002)。タイムラインには、クラスMyButtonを設定したMovieClipインスタンスmy_mcを配置しておきます。[Control] > [Test Movie]を実行して、MovieClipインスタンスにマウス操作を行うと、それに対応してonPressやonRelease、onReleaseOutsideのコールバック関数が呼出され、[Output]パネルに結果が表示されます。
スクリプト002■MyButtonクラスのテスト例
|
// タイムライン: _level0
// フレームアクション
// MyButtonクラスを設定したインスタンスmy_mcを配置
import flash.events.MouseEvent;
my_mc.onPress = function (eventObject:MouseEvent):void {
trace("onPress", eventObject);
}
my_mc.onRelease = function (eventObject:MouseEvent):void {
trace("onRelease", eventObject);
}
my_mc.onReleaseOutside = function (eventObject:MouseEvent):void {
trace("onReleaseOutside", eventObject);
}
|
|
Player
ActionScript 3.0/Flash Player 9以降。
出典
[ActionScript 3.0 Language Reference] > [Class EventDispatcher] > [addEventListener () method]
参考
akihiro kamijo「EventDispatcherクラス」
作成者: 野中文雄
更新日: 2006年11月14日 スクリプト001のコールバック関数呼出しにFunction.apply()メソッドを使用する処理に変更
更新日: 2006年9月19日 スクリプト001のクラスMyButton定義で、イベントハンドラメソッド設定用のプロパティに、パッケージ外からアクセスできるようpublic属性を指定。
作成日: 2006年8月21日
