Partial flash.events.IEventDispatcher implementation #394
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The following changes allow starling.events.EventDispatcher to implement flash.events.IEventDispatcher.
A few important warnings:
The capture phase is not implemented. addEventListener() and removeEventListener() name the argument
notSupported
to try to make this clear. Currently, it is completely ignored, but we might consider throwing a runtime error if this argument is set to true.Priorities are not supported. addEventListener() and removeEventListener() name the argument
notSupported2
to try to make this clear. Currently, it is completely ignored, but we might consider throwing a runtime error if this argument is set to any value but 0.Weak references are not supported. addEventListener() and removeEventListener() name the argument notSupported3 to try to make this clear. Currently, it is completely ignored, but we might consider throwing a runtime error if this argument is set to true.
For all three of the "notSupported" arguments, a quick line in the documentation should also help make it abundantly clear that they're not supported.
The following new features have been added:
Events may be cancelable. I added a cancelable argument at the end of the constructor, fromPool() function and reset() function. preventDefault() and isDefaultPrevented() are also implemented. dispatchEvent() and dispatchEventWith() return a Boolean to indicate if the event was cancelled, since IEventDispatcher defines that in the signature for dispatchEvent().
I exposed the eventPhase getter to indicate if its "at target" or bubbling.
Events are not cloned when they bubble, but starling.events.Event overrides the clone() function properly. I've heard that some people like to call clone() to redispatch events sometimes, so it makes sense to have it implemented since flash.events.Event defines it.
This change offers the following additional advantages:
Event listeners can simply accept flash.events.Event instead of starling.events.Event. If someone needs the data property, they can use the two-argument signature on their listeners:
The data argument can be strongly typed too, so it's better than calling the data getter on the event since that's always typed as Object.
For dispatching pooled events with dispatchEventWith(), the type constants on flash.events.Event work just as well as the constants on starling.events.Event since they're simply Strings. There shouldn't be any reason to call dispatchEvent() with a starling.events.Event, since you lose the advantages of pooling, so no one should need to import starling.events.Event for that either.
If someone continues to import starling.events.Event in new or existing code, it will continue to work the same way as before. That change won't break anything, and new code can benefit from importing flash.events.Event instead.
I feel like advantage 1 is the big one, but advantage 2 will make many Feathers users happy.
This should not break most existing code. If someone overrides addEventListener(), removeEventListener(), dispatchEvent(), or dispatchEventWith(), they will need to change the signature. I do this in a couple of places in Feathers, but it's an easy change. I doubt that many other people are adding overrides as such a low level.
What do you think?