jssource/src_files/include/javascript/yui3/build/node/node-event-delegate.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('node-event-delegate', function(Y) {
   9
  10 /**
  11  * Functionality to make the node a delegated event container
  12  * @module node
  13  * @submodule node-event-delegate
  14  */
  15
  16 /**
  17  * <p>Sets up a delegation listener for an event occurring inside the Node.
  18  * The delegated event will be verified against a supplied selector or
  19  * filtering function to test if the event references at least one node that
  20  * should trigger the subscription callback.</p>
  21  *
  22  * <p>Selector string filters will trigger the callback if the event originated
  23  * from a node that matches it or is contained in a node that matches it.
  24  * Function filters are called for each Node up the parent axis to the
  25  * subscribing container node, and receive at each level the Node and the event
  26  * object.  The function should return true (or a truthy value) if that Node
  27  * should trigger the subscription callback.  Note, it is possible for filters
  28  * to match multiple Nodes for a single event.  In this case, the delegate
  29  * callback will be executed for each matching Node.</p>
  30  *
  31  * <p>For each matching Node, the callback will be executed with its 'this'
  32  * object set to the Node matched by the filter (unless a specific context was
  33  * provided during subscription), and the provided event's
  34  * <code>currentTarget</code> will also be set to the matching Node.  The
  35  * containing Node from which the subscription was originally made can be
  36  * referenced as <code>e.container</code>.
  37  *
  38  * @method delegate
  39  * @param type {String} the event type to delegate
  40  * @param fn {Function} the callback function to execute.  This function
  41  *              will be provided the event object for the delegated event.
  42  * @param spec {String|Function} a selector that must match the target of the
  43  *              event or a function to test target and its parents for a match
  44  * @param context {Object} optional argument that specifies what 'this' refers to.
  45  * @param args* {any} 0..n additional arguments to pass on to the callback function.
  46  *              These arguments will be added after the event object.
  47  * @return {EventHandle} the detach handle
  48  * @for Node
  49  */
  50 Y.Node.prototype.delegate = function(type) {
  51
  52     var args = Y.Array(arguments, 0, true),
  53         index = (Y.Lang.isObject(type) && !Y.Lang.isArray(type)) ? 1 : 2;
  54
  55     args.splice(index, 0, this._node);
  56
  57     return Y.delegate.apply(Y, args);
  58 };
  59
  60
  61 }, '3.3.0' ,{requires:['node-base', 'event-delegate']});