"Warning: 1090: Migration issue" despite explicitly registering event handlers - actionscript-3

Question

I have a game engine class that inherits from MovieClip and handles mouseDown events in a private instance method. For the sake of simplicity, I name the event handler onMouseDown. It looks like this:
private function onMouseDown(e:MouseEvent):void
{
if (_isEnginePlaying)
{
_player.attack();
}
}
I register it in the engine class's init method (itself an addedToStage handler) that looks like this:
private function init(e:Event):void
{
removeEventListener(Event.ADDED_TO_STAGE, init);
// ...
stage.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown);
// ...
}
This compiles and works correctly, but the compiler warns:
Warning: 1090: Migration issue: The onMouseDown event handler is not triggered automatically by Flash Player at run time in ActionScript 3.0. You must first register this handler for the event using addEventListener ( 'mouseDown', callback_handler).
But, as shown, I did register the handler using addEventListener(). Why does the compiler still emit this warning and what can I do to make the warning go away?

Answer 1

This is because the handler was registered with a different instance and not the game engine instance (this). Remember that event handlers in AS2 were registered simply by specifying them as properties on the instances that should handle the respective events and will automatically fire when needed. The warning is there to inform the developer that they do not automatically fire in AS3.
So the compiler errs on the side of caution, assumes I'm trying to register a click handler with the game engine instance (even though I've already registered it with the stage) and warns me to that effect.
There are a number of ways to make the warning go away:
Just rename the onMouseDown handler. The "on-" convention is a holdover from AS2 and the compiler only emits warnings for handlers following this naming convention; if you're comfortable settling for a different convention, this is the recommended solution. The convention used at Adobe is "-Handler" (sources 1 2 3), so onMouseDown becomes mouseDownHandler:
private function init(e:Event):void
{
removeEventListener(Event.ADDED_TO_STAGE, init);
// ...
stage.addEventListener(MouseEvent.MOUSE_DOWN, mouseDownHandler);
// ...
}
private function mouseDownHandler(e:MouseEvent):void
{
if (_isEnginePlaying)
{
_player.attack();
}
}
If this can listen for the event, register the event with this instead:
private function init(e:Event):void
{
removeEventListener(Event.ADDED_TO_STAGE, init);
// ...
addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown);
// ...
}
If the intention was for this to listen for the event, then registering the handler with a different instance was inappropriate.
If you need to register the handler with a different instance, but you're sure that the definition is where it should be, you'll have to rename the handler. If for whatever reason changing the naming convention across all of your event handlers is not an option, the least you should do is prefix the name of whatever you're registering it with, so it's clear that this handler is not intended to be registered with this, but with a different instance:
private function stage_onMouseDown(e:MouseEvent):void
{
if (_isEnginePlaying)
{
_player.attack();
}
}
If you insist on keeping things the way they are, you can suppress the warning altogether, but obviously this is not something you should be doing unless you have a very good reason to.