Ah, I figured out how to fix up my one issue with controllers:

The default behavior of an event is determined by the entity that calls
into the event dispatcher, so the solution was to unify the dispatch of
these events. Created a utility method in CommandEvent to do that, and
did some singlton-like hackery on the constructor to prevent folks from
thinking they can just dispatch these themselves and have it work correctly.


git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@4317 542714f4-19e9-0310-aa3c-eee0fc999fb1

src/as/com/threerings/mx/controls/CommandButton.as

@@ -37,7 +37,7 @@ public class CommandButton extends Button
             // stop the click event
             event.stopImmediatePropagation();
             // dispatch the command event
-            dispatchEvent(new CommandEvent(_cmd, _arg));
+            CommandEvent.dispatch(this, _cmd, _arg);
         }
     }
 

src/as/com/threerings/mx/controls/CommandMenu.as

@@ -45,8 +45,9 @@ public class CommandMenu extends Menu
     {
         event.stopImmediatePropagation();
         var element :Array = (event.item as Array);
-        mx_internal::parentDisplayObject.dispatchEvent(
-            new CommandEvent(String(element[2]), element[3]));
+
+        CommandEvent.dispatch(mx_internal::parentDisplayObject,
+            String(element[2]), element[3]);
     }
 
     // our function for retrieving a label for a menu entry

src/as/com/threerings/mx/events/CommandEvent.as

@@ -1,30 +1,78 @@
 package com.threerings.mx.events {
 
+import flash.errors.IllegalOperationError;
+
 import flash.events.Event;
+import flash.events.IEventDispatcher;
 
 public class CommandEvent extends Event
 {
     /** The event type for all controller events. */
     public static const TYPE :String = "commandEvt";
 
+    /**
+     * Use this method to dispatch CommandEvents.
+     */
+    public static function dispatch (
+            disp :IEventDispatcher, cmd :String, arg :Object = null) :void
+    {
+        // Create the event
+        var event :CommandEvent = create(cmd, arg);
+
+        // Dispatch it. A return value of true means that the event was
+        // never cancelled, so we complain.
+        if (disp == null || disp.dispatchEvent(event)) {
+            Log.getLog(CommandEvent).warning("Unhandled controller command " +
+                "[cmd=" + cmd + ", arg=" + arg + "].");
+        }
+    }
+
+    /** The command. */
     public var command :String;
+
+    /** An optional argument. */
     public var arg :Object;
 
-    public function CommandEvent (command :String, arg :Object = null)
+    /**
+     * Command events may not be directly constructed, use the dispatch
+     * method to do your work.
+     */
+    public function CommandEvent (command :String, arg :Object)
     {
         super(TYPE, true);
+        if (_blockConstructor) {
+            throw new IllegalOperationError();
+        }
         this.command = command;
         this.arg = arg;
     }
 
     override public function clone () :Event
     {
-        return new CommandEvent(command, arg);
+        return create(command, arg);
     }
 
     override public function toString () :String
     {
         return "CommandEvent[" + command + " (" + arg + ")]";
     }
+
+    /**
+     * A factory method for privately creating command events.
+     */
+    protected static function create (cmd :String, arg :Object) :CommandEvent
+    {
+        var event :CommandEvent;
+        _blockConstructor = false;
+        try {
+            event = new CommandEvent(cmd, arg);
+        } finally {
+            _blockConstructor = true;
+        }
+        return event;
+    }
+
+    /** Used to prevent unauthorized construction. */
+    protected static var _blockConstructor :Boolean = true;
 }
 }

src/as/com/threerings/util/Controller.as

@@ -22,6 +22,15 @@ public class Controller
         }
     }
 
+    /**
+     * Post an action so that it can be handled by this controller or
+     * another controller above it in the display list.
+     */
+    public final function postAction (cmd :String, arg :Object = null) :void
+    {
+        CommandEvent.dispatch(_panel, cmd, arg);
+    }
+
     /**
      * Handle an action that was generated by our panel or some child.
      *
@@ -52,10 +61,6 @@ public class Controller
             // suppress, and fall through
         }
 
-        // TODO: This warning should really be inside the CommandEvent
-        // somewhere, and only generated if the event never gets cancelled
-        Log.getLog(this).warning("Unhandled controller command " +
-            "[cmd=" + cmd + ", arg=" + arg + "].");
         return false; // not handled
     }
 
@@ -68,6 +73,7 @@ public class Controller
         if (handleAction(event.command, event.arg)) {
             // if we handle the event, stop it from moving outward to another
             // controller
+            event.preventDefault();
             event.stopImmediatePropagation();
         }
     }

src/as/com/threerings/util/MenuUtil.as

@@ -21,7 +21,7 @@ public class MenuUtil
             new ContextMenuItem(caption, separatorBefore, enabled, visible);
         item.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT,
             function (event :ContextMenuEvent) :void {
-                event.mouseTarget.dispatchEvent(new CommandEvent(cmd, arg));
+                CommandEvent.dispatch(event.mouseTarget, cmd, arg);
             });
         return item;
     }