View comments | RSS feed

Dispatching events

If you want your component to broadcast events other than the events it may inherit from a parent class, you must call the dispatchEvent() method in the component's class file.

The dispatchEvent() method is defined in the mx.events.EventDispatcher class and is inherited by all components that extend UIObject. (See EventDispatcher class.)

You should also add an Event metadata tag at the top of the class file for each new event. For more information, see About the Event tag.

Note: For information about handling component events in a Flash application, see Handling Component Events.

Using the dispatchEvent() method

In the body of your component's ActionScript class file, you broadcast events using the dispatchEvent() method. The dispatchEvent() method has the following syntax:

dispatchEvent(eventObj)

The eventObj parameter is an ActionScript object that describes the event (see the example later in this section).

You must declare the dispatchEvent function in your code before you call it, as follows:

private var dispatchEvent:Function;

You must also create an event object to pass to dispatchEvent(). The event object contains information about the event that the listener can use to handler the event.

You can explicitly build an event object before dispatching the event, as the following example shows:

var eventObj = new Object();
eventObj.type = "myEvent";
eventObj.target = this;
dispatchEvent(eventObj);

You can also use a shortcut syntax that sets the value of the type property and the target property and dispatches the event in a single line:

ancestorSlide.dispatchEvent({type:"revealChild", target:this});

In the preceding example, setting the target property is optional, because it is implicit.

The description of each event in the Flash MX 2004 documentation lists the event properties that are optional and required. For example, the ScrollBar.scroll event takes a detail property in addition to the type and target properties. For more information, see the event descriptions in Components Dictionary.

Common events

The following table lists the common events that are broadcast by various classes. Every component should broadcast these events if they make sense for that component. This is not a complete list of events for all components, just ones that are likely to be reused by other components. Even though some events specify no parameters, all events have an implicit parameter: a reference to the object broadcasting the event.

Event Use

click

Used by the Button component, or whenever a mouse click has no other meaning.

change

Used by List, ComboBox, and other text-entry components.

scroll

Used by ScrollBar and other controls that cause scrolling (scroll "bumpers" on a scrolling pop-up menu).

In addition, because of inheritance from the base classes, all components broadcast the following events:

UIComponent event Description

load

The component is creating or loading its subobjects.

unload

The component is unloading its subobjects.

focusIn

The component now has the input focus. Some HTML-equivalent components (ListBox, ComboBox, Button, Text) might also broadcast focus, but all broadcast DOMFocusIn.

focusOut

The component has lost the input focus.

move

The component has been moved to a new location.

resize

The component has been resized.

The following table describes common key events:

Key events Description

keyDown

A key is pressed. The code property contains the key code and the ascii property contains the ASCII code of the key pressed. Do not check with the low-level Key object, because the event might not have been generated by the Key object.

keyUp

A key is released.


Comments


murk379 said on Oct 10, 2004 at 8:51 PM :
I found that even when inheriting from UIComponent it was still necessary to import mx.events.EventDispatcher and call EventDispatcher.initialize(this) in my constructor to dispatch custom events.

Perhaps this indicates a problem with my code, but if not this should really be added to the docs.
larsendaniel said on Oct 31, 2004 at 12:02 AM :
i had no problem getting this to work. once i figured it out, it is quite simple! this is all it takes to get it to work:

[Event("newRandomEvent")]
class myComponent extends UIComponent {
.....
//place this in your code where you want it to fire.
dispatchEvent({type:"newRandomEvent"});
.....
}

the biggest hold up for me was that i was out of scope for a while. so if you are in the definition of a function on a button, you might have to do something like this:
this._parent.dispatchEvent({type:"newRandomEvent"}); //where this points to the button
in my case i was in another listener on an object in my component, so i had to say:
eventObj.target._parent.dispatchEvent({type:"newRandomEvent"});

in other words, the dispatchEvent is ON the component itself, make sure that is where you call it from.

good luck to all!
No screen name said on Dec 18, 2004 at 7:21 PM :
I had a tricky time getting anything to work. BUT lets have you learn from my trails. I (finally) got the check mark to say: "No errors!"

I had to include these items:

import Subject.as; //my custom subject definition
import mx.core.UIComponent; //Trial 1
import mx.events.EventDispatcher; //someone suggested this!
import mx.events.UIEvent; //website said this!

[event("ResponseReady")] // website said this too!

class SubjectAcquisition{
public var vSubject:Subject;

function SubjectAcquisition(SubjID:String, URL:String){
EventDispatcher.initialize(this); //some guys comments said that!
var vvSubject:Subject;
vSubject = vvSubject;
}
function Request(){
_parent.dispatchEvent({type:"ResponseReady", target:this});
//NOTE: SubjectAcquisition.dispatchEvent... DID NOT WORK. _parent finally did..
//It keeps saying "dispatchEvent is Not a method
}
}
Fallfish said on Jan 13, 2005 at 1:50 AM :
That's because you didn't extend UIObject or UIComponent.
Of course, you don't have to do so just for direct use of dispatchEvent call.
When not extending UIObject or UIComponent(or their subclasses), try the following:
import Subject.as; //my custom subject definition
import mx.events.EventDispatcher; //someone suggested this!

[event("ResponseReady")] // website said this too!

class SubjectAcquisition{
public var vSubject:Subject;
//--------------------------------------
//just define empty functions here
function dispatchEvent() {};
function addEventListener() {};
function removeEventListener() {};
//--------------------------------------

function SubjectAcquisition(SubjID:String, URL:String){
EventDispatcher.initialize(this); //some guys comments said that!
var vvSubject:Subject;
vSubject = vvSubject;
}
function Request(){
dispatchEvent({type:"ResponseReady", target:this});
}
}
//
Hope it works for you.
Good luck!
No screen name said on Jun 2, 2005 at 5:54 AM :
For larsendaniel and other people who've noticed that their events are fired within the scope of the child object (for example, a button component) rather than the base component class, there is a better way than saying this._parent.dispatchEvent({type:"newRandomEvent"})

You can use an event delegate to define the object scope that you want the event dispatcher to send the event to, something like:

myButton.dispatchEvent({"click", Delegate.create(this, checkFields)});

In the above case, if this were placed on a button, the "click" event would be sent to the calling class (this) rather than myButton. More info on this can be found in the actionscript dictionary under "delegates", or at http://actionscript-toolbox.com/sampleemail_mx.php
jepo said on Jun 9, 2005 at 2:41 PM :
Thank you for your comments. This site is for documentation feedback only. Some comments with general questions about how to use components, bug reports, or feature requests for the Flash product, have been removed. Please use the Flash webforums for questions about how to use components: http://webforums.macromedia.com/flash. Please use this form for feature requests or suspected bugs: www.macromedia.com/support/email/wishform/.
www_amirrocker_de said on Sep 1, 2005 at 7:17 AM :
Why can I only catch events at root level ? I dispatch an event in a label class
and if i add a Eventlistener on root > file it works I get the event
however if i wish to handle it inside a class i just dont seem to receive it .

Where is my mistake ?

<code>
// this clas is supposed to receive
import mx.events.*;
class LoginManager {
//var className:Function = de.allmediastreams.application.login.LoginManager;
//var symbol:String = "LogInWindow";

var addEventListener:Function;
var removeEventListener:Function;
var dispatchEvent:Function;
//var dispatchQueue:Function;

/** the grafical members */
private var _userMailInputLabel:TextField;
private var _userPasswordInput:TextField;
private var _doLoginButton:MovieClip;
private var _cancelLoginButton:MovieClip;

function LoginManager() {
trace("loginManager constructed > but not inited");
EventDispatcher.initialize(this);
init();
}

function init():Void {
_userMailInputLabel.addEventListener("onChanged", Delegate.create(this, inputHandler));

}

function inputHandler(evt){
trace("evt.target: "+evt.target);
}


}//end LoginManager

// the sending class
import mx.events.*;
class InputLabel {

var addEventListener:Function;
var removeEventListener:Function;
var dispatchEvent:Function;
//var dispatchQueue:Function;

private var _ilabel:TextField;

function InputLabel() {
trace("InputLabel constructed");
EventDispatcher.initialize(this);
init();
handleTextFieldEvents();
}

function init() {
//some init
}

private function handleTextFieldEvents():Void {
_ilabel.onChanged = function(evt) {
this._parent.onChanged(evt);
}

}
function onChanged(evt){
//trace("evt: "+evt);
//trace("_label changed event in InputLabel received");
dispatchEvent({type:"onChanged", target:evt});
}

}//end class
</code>

It doesnt get any simpler but it still doesnt work > do I have to extend MovieClip or Object explicitly and call super() ?

Please help ...
thanx
amir
No screen name said on Sep 12, 2005 at 4:31 AM :
this works out very well, no complex coding!! easy GO!

import mx.core.UIComponent;
import mx.events.*;
class MyBtn_cls extends UIComponent {
private var dispatchEvent:Function;
//------------------------------------------------------
public function init() {
super.init();
mx.events.EventDispatcher.initialize(this);
}
//------------------------------------------------------

public function draw() {
super.draw();
Bounding_box_mc._visible = false;
}
//------------------------------------------------------
function onRelease() {
dispatchEvent({type:"pressCheyi"});
}
//------------------------------------------------------
}


Enjoy!

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flash/mx2004/main_7_2/00003105.html