jssource/src_files/include/javascript/yui3/build/event/event-synthetic.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('event-synthetic', function(Y) {
   9
  10 /**
  11  * Define new DOM events that can be subscribed to from Nodes.
  12  *
  13  * @module event
  14  * @submodule event-synthetic
  15  */
  16 var DOMMap   = Y.Env.evt.dom_map,
  17     toArray  = Y.Array,
  18     YLang    = Y.Lang,
  19     isObject = YLang.isObject,
  20     isString = YLang.isString,
  21     query    = Y.Selector.query,
  22     noop     = function () {};
  23
  24 /**
  25  * <p>The triggering mechanism used by SyntheticEvents.</p>
  26  *
  27  * <p>Implementers should not instantiate these directly.  Use the Notifier
  28  * provided to the event's implemented <code>on(node, sub, notifier)</code> or
  29  * <code>delegate(node, sub, notifier, filter)</code> methods.</p>
  30  *
  31  * @class SyntheticEvent.Notifier
  32  * @constructor
  33  * @param handle {EventHandle} the detach handle for the subscription to an
  34  *              internal custom event used to execute the callback passed to
  35  *              on(..) or delegate(..)
  36  * @param emitFacade {Boolean} take steps to ensure the first arg received by
  37  *              the subscription callback is an event facade
  38  * @private
  39  * @since 3.2.0
  40  */
  41 function Notifier(handle, emitFacade) {
  42     this.handle     = handle;
  43     this.emitFacade = emitFacade;
  44 }
  45
  46 /**
  47  * <p>Executes the subscription callback, passing the firing arguments as the
  48  * first parameters to that callback. For events that are configured with
  49  * emitFacade=true, it is common practice to pass the triggering DOMEventFacade
  50  * as the first parameter.  Barring a proper DOMEventFacade or EventFacade
  51  * (from a CustomEvent), a new EventFacade will be generated.  In that case, if
  52  * fire() is called with a simple object, it will be mixed into the facade.
  53  * Otherwise, the facade will be prepended to the callback parameters.</p>
  54  *
  55  * <p>For notifiers provided to delegate logic, the first argument should be an
  56  * object with a &quot;currentTarget&quot; property to identify what object to
  57  * default as 'this' in the callback.  Typically this is gleaned from the
  58  * DOMEventFacade or EventFacade, but if configured with emitFacade=false, an
  59  * object must be provided.  In that case, the object will be removed from the
  60  * callback parameters.</p>
  61  *
  62  * <p>Additional arguments passed during event subscription will be
  63  * automatically added after those passed to fire().</p>
  64  *
  65  * @method fire
  66  * @param e {EventFacade|DOMEventFacade|Object|any} (see description)
  67  * @param arg* {any} additional arguments received by all subscriptions
  68  * @private
  69  */
  70 Notifier.prototype.fire = function (e) {
  71     // first arg to delegate notifier should be an object with currentTarget
  72     var args     = toArray(arguments, 0, true),
  73         handle   = this.handle,
  74         ce       = handle.evt,
  75         sub      = handle.sub,
  76         thisObj  = sub.context,
  77         delegate = sub.filter,
  78         event    = e || {};
  79
  80     if (this.emitFacade) {
  81         if (!e || !e.preventDefault) {
  82             event = ce._getFacade();
  83
  84             if (isObject(e) && !e.preventDefault) {
  85                 Y.mix(event, e, true);
  86                 args[0] = event;
  87             } else {
  88                 args.unshift(event);
  89             }
  90         }
  91
  92         event.type    = ce.type;
  93         event.details = args.slice();
  94
  95         if (delegate) {
  96             event.container = ce.host;
  97         }
  98     } else if (delegate && isObject(e) && e.currentTarget) {
  99         args.shift();
 100     }
 101
 102     sub.context = thisObj || event.currentTarget || ce.host;
 103     ce.fire.apply(ce, args);
 104     sub.context = thisObj; // reset for future firing
 105 };
 106
 107
 108 /**
 109  * <p>Wrapper class for the integration of new events into the YUI event
 110  * infrastructure.  Don't instantiate this object directly, use
 111  * <code>Y.Event.define(type, config)</code>.  See that method for details.</p>
 112  *
 113  * <p>Properties that MAY or SHOULD be specified in the configuration are noted
 114  * below and in the description of <code>Y.Event.define</code>.</p>
 115  *
 116  * @class SyntheticEvent
 117  * @constructor
 118  * @param cfg {Object} Implementation pieces and configuration
 119  * @since 3.1.0
 120  * @in event-synthetic
 121  */
 122 function SyntheticEvent() {
 123     this._init.apply(this, arguments);
 124 }
 125
 126 Y.mix(SyntheticEvent, {
 127     Notifier: Notifier,
 128
 129     /**
 130      * Returns the array of subscription handles for a node for the given event
 131      * type.  Passing true as the third argument will create a registry entry
 132      * in the event system's DOM map to host the array if one doesn't yet exist.
 133      *
 134      * @method getRegistry
 135      * @param node {Node} the node
 136      * @param type {String} the event
 137      * @param create {Boolean} create a registration entry to host a new array
 138      *                  if one doesn't exist.
 139      * @return {Array}
 140      * @static
 141      * @protected
 142      * @since 3.2.0
 143      */
 144     getRegistry: function (node, type, create) {
 145         var el     = node._node,
 146             yuid   = Y.stamp(el),
 147             key    = 'event:' + yuid + type + '_synth',
 148             events = DOMMap[yuid] || (DOMMap[yuid] = {});
 149
 150         if (!events[key] && create) {
 151             events[key] = {
 152                 type      : '_synth',
 153                 fn        : noop,
 154                 capture   : false,
 155                 el        : el,
 156                 key       : key,
 157                 domkey    : yuid,
 158                 notifiers : [],
 159
 160                 detachAll : function () {
 161                     var notifiers = this.notifiers,
 162                         i = notifiers.length;
 163
 164                     while (--i >= 0) {
 165                         notifiers[i].detach();
 166                     }
 167                 }
 168             };
 169         }
 170
 171         return (events[key]) ? events[key].notifiers : null;
 172     },
 173
 174     /**
 175      * Alternate <code>_delete()</code> method for the CustomEvent object
 176      * created to manage SyntheticEvent subscriptions.
 177      *
 178      * @method _deleteSub
 179      * @param sub {Subscription} the subscription to clean up
 180      * @private
 181      * @since 3.2.0
 182      */
 183     _deleteSub: function (sub) {
 184         if (sub && sub.fn) {
 185             var synth = this.eventDef,
 186                 method = (sub.filter) ? 'detachDelegate' : 'detach';
 187
 188             this.subscribers = {};
 189             this.subCount = 0;
 190
 191             synth[method](sub.node, sub, this.notifier, sub.filter);
 192             synth._unregisterSub(sub);
 193
 194             delete sub.fn;
 195             delete sub.node;
 196             delete sub.context;
 197         }
 198     },
 199
 200     prototype: {
 201         constructor: SyntheticEvent,
 202
 203         /**
 204          * Construction logic for the event.
 205          *
 206          * @method _init
 207          * @protected
 208          */
 209         _init: function () {
 210             var config = this.publishConfig || (this.publishConfig = {});
 211
 212             // The notification mechanism handles facade creation
 213             this.emitFacade = ('emitFacade' in config) ?
 214                                 config.emitFacade :
 215                                 true;
 216             config.emitFacade  = false;
 217         },
 218
 219         /**
 220          * <p>Implementers MAY provide this method definition.</p>
 221          *
 222          * <p>Implement this function if the event supports a different
 223          * subscription signature.  This function is used by both
 224          * <code>on()</code> and <code>delegate()</code>.  The second parameter
 225          * indicates that the event is being subscribed via
 226          * <code>delegate()</code>.</p>
 227          *
 228          * <p>Implementations must remove extra arguments from the args list
 229          * before returning.  The required args for <code>on()</code>
 230          * subscriptions are</p>
 231          * <pre><code>[type, callback, target, context, argN...]</code></pre>
 232          *
 233          * <p>The required args for <code>delegate()</code>
 234          * subscriptions are</p>
 235          *
 236          * <pre><code>[type, callback, target, filter, context, argN...]</code></pre>
 237          *
 238          * <p>The return value from this function will be stored on the
 239          * subscription in the '_extra' property for reference elsewhere.</p>
 240          *
 241          * @method processArgs
 242          * @param args {Array} parmeters passed to Y.on(..) or Y.delegate(..)
 243          * @param delegate {Boolean} true if the subscription is from Y.delegate
 244          * @return {any}
 245          */
 246         processArgs: noop,
 247
 248         /**
 249          * <p>Implementers MAY override this property.</p>
 250          *
 251          * <p>Whether to prevent multiple subscriptions to this event that are
 252          * classified as being the same.  By default, this means the subscribed
 253          * callback is the same function.  See the <code>subMatch</code>
 254          * method.  Setting this to true will impact performance for high volume
 255          * events.</p>
 256          *
 257          * @property preventDups
 258          * @type {Boolean}
 259          * @default false
 260          */
 261         //preventDups  : false,
 262
 263         /**
 264          * <p>Implementers SHOULD provide this method definition.</p>
 265          *
 266          * Implementation logic for subscriptions done via <code>node.on(type,
 267          * fn)</code> or <code>Y.on(type, fn, target)</code>.  This
 268          * function should set up the monitor(s) that will eventually fire the
 269          * event.  Typically this involves subscribing to at least one DOM
 270          * event.  It is recommended to store detach handles from any DOM
 271          * subscriptions to make for easy cleanup in the <code>detach</code>
 272          * method.  Typically these handles are added to the <code>sub</code>
 273          * object.  Also for SyntheticEvents that leverage a single DOM
 274          * subscription under the hood, it is recommended to pass the DOM event
 275          * object to <code>notifier.fire(e)</code>.  (The event name on the
 276          * object will be updated).
 277          *
 278          * @method on
 279          * @param node {Node} the node the subscription is being applied to
 280          * @param sub {Subscription} the object to track this subscription
 281          * @param notifier {SyntheticEvent.Notifier} call notifier.fire(..) to
 282          *              trigger the execution of the subscribers
 283          */
 284         on: noop,
 285
 286         /**
 287          * <p>Implementers SHOULD provide this method definition.</p>
 288          *
 289          * <p>Implementation logic for detaching subscriptions done via
 290          * <code>node.on(type, fn)</code>.  This function should clean up any
 291          * subscriptions made in the <code>on()</code> phase.</p>
 292          *
 293          * @method detach
 294          * @param node {Node} the node the subscription was applied to
 295          * @param sub {Subscription} the object tracking this subscription
 296          * @param notifier {SyntheticEvent.Notifier} the Notifier used to
 297          *              trigger the execution of the subscribers
 298          */
 299         detach: noop,
 300
 301         /**
 302          * <p>Implementers SHOULD provide this method definition.</p>
 303          *
 304          * <p>Implementation logic for subscriptions done via
 305          * <code>node.delegate(type, fn, filter)</code> or
 306          * <code>Y.delegate(type, fn, container, filter)</code>.  Like with
 307          * <code>on()</code> above, this function should monitor the environment
 308          * for the event being fired, and trigger subscription execution by
 309          * calling <code>notifier.fire(e)</code>.</p>
 310          *
 311          * <p>This function receives a fourth argument, which is the filter
 312          * used to identify which Node's are of interest to the subscription.
 313          * The filter will be either a boolean function that accepts a target
 314          * Node for each hierarchy level as the event bubbles, or a selector
 315          * string.  To translate selector strings into filter functions, use
 316          * <code>Y.delegate.compileFilter(filter)</code>.</p>
 317          *
 318          * @method delegate
 319          * @param node {Node} the node the subscription is being applied to
 320          * @param sub {Subscription} the object to track this subscription
 321          * @param notifier {SyntheticEvent.Notifier} call notifier.fire(..) to
 322          *              trigger the execution of the subscribers
 323          * @param filter {String|Function} Selector string or function that
 324          *              accepts an event object and returns null, a Node, or an
 325          *              array of Nodes matching the criteria for processing.
 326          * @since 3.2.0
 327          */
 328         delegate       : noop,
 329
 330         /**
 331          * <p>Implementers SHOULD provide this method definition.</p>
 332          *
 333          * <p>Implementation logic for detaching subscriptions done via
 334          * <code>node.delegate(type, fn, filter)</code> or
 335          * <code>Y.delegate(type, fn, container, filter)</code>.  This function
 336          * should clean up any subscriptions made in the
 337          * <code>delegate()</code> phase.</p>
 338          *
 339          * @method detachDelegate
 340          * @param node {Node} the node the subscription was applied to
 341          * @param sub {Subscription} the object tracking this subscription
 342          * @param notifier {SyntheticEvent.Notifier} the Notifier used to
 343          *              trigger the execution of the subscribers
 344          * @param filter {String|Function} Selector string or function that
 345          *              accepts an event object and returns null, a Node, or an
 346          *              array of Nodes matching the criteria for processing.
 347          * @since 3.2.0
 348          */
 349         detachDelegate : noop,
 350
 351         /**
 352          * Sets up the boilerplate for detaching the event and facilitating the
 353          * execution of subscriber callbacks.
 354          *
 355          * @method _on
 356          * @param args {Array} array of arguments passed to
 357          *              <code>Y.on(...)</code> or <code>Y.delegate(...)</code>
 358          * @param delegate {Boolean} true if called from
 359          * <code>Y.delegate(...)</code>
 360          * @return {EventHandle} the detach handle for this subscription
 361          * @private
 362          * since 3.2.0
 363          */
 364         _on: function (args, delegate) {
 365             var handles  = [],
 366                 extra    = this.processArgs(args, delegate),
 367                 selector = args[2],
 368                 method   = delegate ? 'delegate' : 'on',
 369                 nodes, handle;
 370
 371             // Can't just use Y.all because it doesn't support window (yet?)
 372             nodes = (isString(selector)) ? query(selector) : toArray(selector);
 373
 374             if (!nodes.length && isString(selector)) {
 375                 handle = Y.on('available', function () {
 376                     Y.mix(handle, Y[method].apply(Y, args), true);
 377                 }, selector);
 378
 379                 return handle;
 380             }
 381
 382             Y.Array.each(nodes, function (node) {
 383                 var subArgs = args.slice(),
 384                     filter;
 385
 386                 node = Y.one(node);
 387
 388                 if (node) {
 389                     if (delegate) {
 390                         filter = subArgs.splice(3, 1)[0];
 391                     }
 392
 393                     // (type, fn, el, thisObj, ...) => (fn, thisObj, ...)
 394                     subArgs.splice(0, 4, subArgs[1], subArgs[3]);
 395
 396                     if (!this.preventDups || !this.getSubs(node, args,null,true)) {
 397                         handle = this._getNotifier(node, subArgs, extra,filter);
 398
 399                         this[method](node, handle.sub, handle.notifier, filter);
 400
 401                         handles.push(handle);
 402                     }
 403                 }
 404             }, this);
 405
 406             return (handles.length === 1) ?
 407                 handles[0] :
 408                 new Y.EventHandle(handles);
 409         },
 410
 411         /**
 412          * Creates a new Notifier object for use by this event's
 413          * <code>on(...)</code> or <code>delegate(...)</code> implementation.
 414          *
 415          * @method _getNotifier
 416          * @param node {Node} the Node hosting the event
 417          * @param args {Array} the subscription arguments passed to either
 418          *              <code>Y.on(...)</code> or <code>Y.delegate(...)</code>
 419          *              after running through <code>processArgs(args)</code> to
 420          *              normalize the argument signature
 421          * @param extra {any} Extra data parsed from
 422          *              <code>processArgs(args)</code>
 423          * @param filter {String|Function} the selector string or function
 424          *              filter passed to <code>Y.delegate(...)</code> (not
 425          *              present when called from <code>Y.on(...)</code>)
 426          * @return {SyntheticEvent.Notifier}
 427          * @private
 428          * @since 3.2.0
 429          */
 430         _getNotifier: function (node, args, extra, filter) {
 431             var dispatcher = new Y.CustomEvent(this.type, this.publishConfig),
 432                 handle     = dispatcher.on.apply(dispatcher, args),
 433                 notifier   = new Notifier(handle, this.emitFacade),
 434                 registry   = SyntheticEvent.getRegistry(node, this.type, true),
 435                 sub        = handle.sub;
 436
 437             handle.notifier   = notifier;
 438
 439             sub.node   = node;
 440             sub.filter = filter;
 441             if (extra) {
 442                 this.applyArgExtras(extra, sub);
 443             }
 444
 445             Y.mix(dispatcher, {
 446                 eventDef     : this,
 447                 notifier     : notifier,
 448                 host         : node,       // I forget what this is for
 449                 currentTarget: node,       // for generating facades
 450                 target       : node,       // for generating facades
 451                 el           : node._node, // For category detach
 452
 453                 _delete      : SyntheticEvent._deleteSub
 454             }, true);
 455
 456             registry.push(handle);
 457
 458             return handle;
 459         },
 460
 461         /**
 462          * <p>Implementers MAY provide this method definition.</p>
 463          *
 464          * <p>Implement this function if you want extra data extracted during
 465          * processArgs to be propagated to subscriptions on a per-node basis.
 466          * That is to say, if you call <code>Y.on('xyz', fn, xtra, 'div')</code>
 467          * the data returned from processArgs will be shared
 468          * across the subscription objects for all the divs.  If you want each
 469          * subscription to receive unique information, do that processing
 470          * here.</p>
 471          *
 472          * <p>The default implementation adds the data extracted by processArgs
 473          * to the subscription object as <code>sub._extra</code>.</p>
 474          *
 475          * @method applyArgExtras
 476          * @param extra {any} Any extra data extracted from processArgs
 477          * @param sub {Subscription} the individual subscription
 478          */
 479         applyArgExtras: function (extra, sub) {
 480             sub._extra = extra;
 481         },
 482
 483         /**
 484          * Removes the subscription from the Notifier registry.
 485          *
 486          * @method _unregisterSub
 487          * @param sub {Subscription} the subscription
 488          * @private
 489          * @since 3.2.0
 490          */
 491         _unregisterSub: function (sub) {
 492             var notifiers = SyntheticEvent.getRegistry(sub.node, this.type),
 493                 i;
 494
 495             if (notifiers) {
 496                 for (i = notifiers.length - 1; i >= 0; --i) {
 497                     if (notifiers[i].sub === sub) {
 498                         notifiers.splice(i, 1);
 499                         break;
 500                     }
 501                 }
 502             }
 503         },
 504
 505         /**
 506          * Removes the subscription(s) from the internal subscription dispatch
 507          * mechanism.  See <code>SyntheticEvent._deleteSub</code>.
 508          *
 509          * @method _detach
 510          * @param args {Array} The arguments passed to
 511          *                  <code>node.detach(...)</code>
 512          * @private
 513          * @since 3.2.0
 514          */
 515         _detach: function (args) {
 516             // Can't use Y.all because it doesn't support window (yet?)
 517             // TODO: Does Y.all support window now?
 518             var target = args[2],
 519                 els    = (isString(target)) ?
 520                             query(target) : toArray(target),
 521                 node, i, len, handles, j;
 522
 523             // (type, fn, el, context, filter?) => (type, fn, context, filter?)
 524             args.splice(2, 1);
 525
 526             for (i = 0, len = els.length; i < len; ++i) {
 527                 node = Y.one(els[i]);
 528
 529                 if (node) {
 530                     handles = this.getSubs(node, args);
 531
 532                     if (handles) {
 533                         for (j = handles.length - 1; j >= 0; --j) {
 534                             handles[j].detach();
 535                         }
 536                     }
 537                 }
 538             }
 539         },
 540
 541         /**
 542          * Returns the detach handles of subscriptions on a node that satisfy a
 543          * search/filter function.  By default, the filter used is the
 544          * <code>subMatch</code> method.
 545          *
 546          * @method getSubs
 547          * @param node {Node} the node hosting the event
 548          * @param args {Array} the array of original subscription args passed
 549          *              to <code>Y.on(...)</code> (before
 550          *              <code>processArgs</code>
 551          * @param filter {Function} function used to identify a subscription
 552          *              for inclusion in the returned array
 553          * @param first {Boolean} stop after the first match (used to check for
 554          *              duplicate subscriptions)
 555          * @return {Array} detach handles for the matching subscriptions
 556          */
 557         getSubs: function (node, args, filter, first) {
 558             var notifiers = SyntheticEvent.getRegistry(node, this.type),
 559                 handles = [],
 560                 i, len, handle;
 561
 562             if (notifiers) {
 563                 if (!filter) {
 564                     filter = this.subMatch;
 565                 }
 566
 567                 for (i = 0, len = notifiers.length; i < len; ++i) {
 568                     handle = notifiers[i];
 569                     if (filter.call(this, handle.sub, args)) {
 570                         if (first) {
 571                             return handle;
 572                         } else {
 573                             handles.push(notifiers[i]);
 574                         }
 575                     }
 576                 }
 577             }
 578
 579             return handles.length && handles;
 580         },
 581
 582         /**
 583          * <p>Implementers MAY override this to define what constitutes a
 584          * &quot;same&quot; subscription.  Override implementations should
 585          * consider the lack of a comparator as a match, so calling
 586          * <code>getSubs()</code> with no arguments will return all subs.</p>
 587          *
 588          * <p>Compares a set of subscription arguments against a Subscription
 589          * object to determine if they match.  The default implementation
 590          * compares the callback function against the second argument passed to
 591          * <code>Y.on(...)</code> or <code>node.detach(...)</code> etc.</p>
 592          *
 593          * @method subMatch
 594          * @param sub {Subscription} the existing subscription
 595          * @param args {Array} the calling arguments passed to
 596          *                  <code>Y.on(...)</code> etc.
 597          * @return {Boolean} true if the sub can be described by the args
 598          *                  present
 599          * @since 3.2.0
 600          */
 601         subMatch: function (sub, args) {
 602             // Default detach cares only about the callback matching
 603             return !args[1] || sub.fn === args[1];
 604         }
 605     }
 606 }, true);
 607
 608 Y.SyntheticEvent = SyntheticEvent;
 609
 610 /**
 611  * <p>Defines a new event in the DOM event system.  Implementers are
 612  * responsible for monitoring for a scenario whereby the event is fired.  A
 613  * notifier object is provided to the functions identified below.  When the
 614  * criteria defining the event are met, call notifier.fire( [args] ); to
 615  * execute event subscribers.</p>
 616  *
 617  * <p>The first parameter is the name of the event.  The second parameter is a
 618  * configuration object which define the behavior of the event system when the
 619  * new event is subscribed to or detached from.  The methods that should be
 620  * defined in this configuration object are <code>on</code>,
 621  * <code>detach</code>, <code>delegate</code>, and <code>detachDelegate</code>.
 622  * You are free to define any other methods or properties needed to define your
 623  * event.  Be aware, however, that since the object is used to subclass
 624  * SyntheticEvent, you should avoid method names used by SyntheticEvent unless
 625  * your intention is to override the default behavior.</p>
 626  *
 627  * <p>This is a list of properties and methods that you can or should specify
 628  * in the configuration object:</p>
 629  *
 630  * <dl>
 631  *   <dt><code>on</code></dt>
 632  *       <dd><code>function (node, subscription, notifier)</code> The
 633  *       implementation logic for subscription.  Any special setup you need to
 634  *       do to create the environment for the event being fired--E.g. native
 635  *       DOM event subscriptions.  Store subscription related objects and
 636  *       state on the <code>subscription</code> object.  When the
 637  *       criteria have been met to fire the synthetic event, call
 638  *       <code>notifier.fire(e)</code>.  See Notifier's <code>fire()</code>
 639  *       method for details about what to pass as parameters.</dd>
 640  *
 641  *   <dt><code>detach</code></dt>
 642  *       <dd><code>function (node, subscription, notifier)</code> The
 643  *       implementation logic for cleaning up a detached subscription. E.g.
 644  *       detach any DOM subscriptions added in <code>on</code>.</dd>
 645  *
 646  *   <dt><code>delegate</code></dt>
 647  *       <dd><code>function (node, subscription, notifier, filter)</code> The
 648  *       implementation logic for subscription via <code>Y.delegate</code> or
 649  *       <code>node.delegate</code>.  The filter is typically either a selector
 650  *       string or a function.  You can use
 651  *       <code>Y.delegate.compileFilter(selectorString)</code> to create a
 652  *       filter function from a selector string if needed.  The filter function
 653  *       expects an event object as input and should output either null, a
 654  *       matching Node, or an array of matching Nodes.  Otherwise, this acts
 655  *       like <code>on</code> DOM event subscriptions.  Store subscription
 656  *       related objects and information on the <code>subscription</code>
 657  *       object.  When the criteria have been met to fire the synthetic event,
 658  *       call <code>notifier.fire(e)</code> as noted above.</dd>
 659  *
 660  *   <dt><code>detachDelegate</code></dt>
 661  *       <dd><code>function (node, subscription, notifier)</code> The
 662  *       implementation logic for cleaning up a detached delegate subscription.
 663  *       E.g. detach any DOM delegate subscriptions added in
 664  *       <code>delegate</code>.</dd>
 665  *
 666  *   <dt><code>publishConfig</code></dt>
 667  *       <dd>(Object) The configuration object that will be used to instantiate
 668  *       the underlying CustomEvent. See Notifier's <code>fire</code> method
 669  *       for details.</dd>
 670  *
 671  *   <dt><code>processArgs</code></dt
 672  *       <dd>
 673  *          <p><code>function (argArray, fromDelegate)</code> Optional method
 674  *          to extract any additional arguments from the subscription
 675  *          signature.  Using this allows <code>on</code> or
 676  *          <code>delegate</code> signatures like
 677  *          <code>node.on(&quot;hover&quot;, overCallback,
 678  *          outCallback)</code>.</p>
 679  *          <p>When processing an atypical argument signature, make sure the
 680  *          args array is returned to the normal signature before returning
 681  *          from the function.  For example, in the &quot;hover&quot; example
 682  *          above, the <code>outCallback</code> needs to be <code>splice</code>d
 683  *          out of the array.  The expected signature of the args array for
 684  *          <code>on()</code> subscriptions is:</p>
 685  *          <pre>
 686  *              <code>[type, callback, target, contextOverride, argN...]</code>
 687  *          </pre>
 688  *          <p>And for <code>delegate()</code>:</p>
 689  *          <pre>
 690  *              <code>[type, callback, target, filter, contextOverride, argN...]</code>
 691  *          </pre>
 692  *          <p>where <code>target</code> is the node the event is being
 693  *          subscribed for.  You can see these signatures documented for
 694  *          <code>Y.on()</code> and <code>Y.delegate()</code> respectively.</p>
 695  *          <p>Whatever gets returned from the function will be stored on the
 696  *          <code>subscription</code> object under
 697  *          <code>subscription._extra</code>.</p></dd>
 698  *   <dt><code>subMatch</code></dt>
 699  *       <dd>
 700  *           <p><code>function (sub, args)</code>  Compares a set of
 701  *           subscription arguments against a Subscription object to determine
 702  *           if they match.  The default implementation compares the callback
 703  *           function against the second argument passed to
 704  *           <code>Y.on(...)</code> or <code>node.detach(...)</code> etc.</p>
 705  *       </dd>
 706  * </dl>
 707  *
 708  * @method Event.define
 709  * @param type {String} the name of the event
 710  * @param config {Object} the prototype definition for the new event (see above)
 711  * @param force {Boolean} override an existing event (use with caution)
 712  * @static
 713  * @return {SyntheticEvent} the subclass implementation instance created to
 714  *              handle event subscriptions of this type
 715  * @for Event
 716  * @since 3.1.0
 717  * @in event-synthetic
 718  */
 719 Y.Event.define = function (type, config, force) {
 720     if (!config) {
 721         config = {};
 722     }
 723
 724     var eventDef = (isObject(type)) ? type : Y.merge({ type: type }, config),
 725         Impl, synth;
 726
 727     if (force || !Y.Node.DOM_EVENTS[eventDef.type]) {
 728         Impl = function () {
 729             SyntheticEvent.apply(this, arguments);
 730         };
 731         Y.extend(Impl, SyntheticEvent, eventDef);
 732         synth = new Impl();
 733
 734         type = synth.type;
 735
 736         Y.Node.DOM_EVENTS[type] = Y.Env.evt.plugins[type] = {
 737             eventDef: synth,
 738
 739             on: function () {
 740                 return synth._on(toArray(arguments));
 741             },
 742
 743             delegate: function () {
 744                 return synth._on(toArray(arguments), true);
 745             },
 746
 747             detach: function () {
 748                 return synth._detach(toArray(arguments));
 749             }
 750         };
 751
 752     }
 753
 754     return synth;
 755 };
 756
 757
 758 }, '3.3.0' ,{requires:['node-base', 'event-custom']});