event-target.js revision 7b604197509a71120a1d0a11e3619d2cf12ae7e5
/**
* Custom event engine, DOM event listener abstraction layer, synthetic DOM
* events.
* @module event-custom
* @submodule event-custom-base
*/
(function() {
/**
* EventTarget provides the implementation for any object to
* publish, subscribe and fire to custom events, and also
* alows other EventTargets to target the object with events
* sourced from the other object.
* EventTarget is designed to be used with Y.augment to wrap
* EventCustom in an interface that allows events to be listened to
* and fired by name. This makes it possible for implementing code to
* subscribe to an event that either has not been created yet, or will
* not be created at all.
* @class EventTarget
* @param opts a configuration object
* @config emitFacade {boolean} if true, all events will emit event
* facade payloads by default (default false)
* @config prefix {string} the prefix to apply to non-prefixed event names
* chaining, otherwise they return an EventHandle (default false)
*/
var L = Y.Lang,
PREFIX_DELIMITER = ':',
CATEGORY_DELIMITER = '|',
AFTER_PREFIX = '~AFTER~',
}),
/**
* If the instance has a prefix attribute and the
* event type is not prefixed, the instance prefix is
* applied to the supplied type.
* @method _getType
* @private
*/
return type;
}
}),
/**
* Returns an array with the detach key (if provided),
* and the prefixed event name from _getType
* Y.on('detachcategory| menu:click', fn)
* @method _parseType
* @private
*/
if (!L.isString(t)) {
return t;
}
i = t.indexOf(AFTER_PREFIX);
if (i > -1) {
after = true;
// Y.log(t);
}
i = t.indexOf(CATEGORY_DELIMITER);
if (i > -1) {
t = t.substr(i+1);
if (t == '*') {
t = null;
}
}
// detach category, full type with instance prefix, is this an after listener, short type
}),
// Y.log('EventTarget constructor executed: ' + this._yuid);
events: {},
targets: {},
config: o,
defaults: {
host: this,
emitFacade: o.emitFacade,
}
};
};
/**
* Subscribe to a custom event hosted by this object
* @method on
* @param type {string} The type of the event
* @param fn {Function} The callback
* @return the event target or a detach handle per 'chain' config
*/
if (L.isFunction(type)) {
}
f = fn;
c = context;
ret = {};
if (v) {
c = v.context || c;
}
args[1] = f;
args[2] = c;
}, this);
}
// extra redirection so we catch adaptor events too. take a look at this.
// Y.log("Node detected, redirecting with these args: " + args);
}
if (this instanceof YUI) {
if (Node) {
n = args[2];
if (n instanceof Y.NodeList) {
n = Y.NodeList.getDOMNodes(n);
} else if (n instanceof Node) {
n = Node.getDOMNode(n);
}
// Captures both DOM events and event plugins.
if (domevent) {
args[2] = n;
}
}
// check for the existance of an event adaptor
if (adapt) {
}
}
if (!handle) {
handle = ce._on(fn, context, (arguments.length > 3) ? Y.Array(arguments, 3, true) : null, (after) ? 'after' : true);
}
if (detachcategory) {
}
},
/**
* subscribe to an event
* @method subscribe
* @deprecated use on
*/
subscribe: function() {
},
/**
* Detach one or more listeners the from the specified event
* @method detach
* @param type {string|Object} Either the handle to the subscriber or the
* type of event. If the type
* is not specified, it will attempt to remove
* the listener from all hosted events.
* @param fn {Function} The subscribed function to unsubscribe, if not
* supplied, all subscribers will be removed.
* @param context {Object} The custom object passed to subscribe. This is
* optional, but if supplied will be used to
* disambiguate multiple listeners that are the same
* (e.g., you subscribe many object using a function
* that lives on the prototype)
* @return {EventTarget} the host
*/
// detachAll disabled on the Y instance.
if (!type && (this !== Y)) {
for (i in evts) {
if (evts.hasOwnProperty(i)) {
}
}
if (isNode) {
}
return ret;
}
ce,
if (handles) {
}
}
};
if (detachcategory) {
if (cat) {
if (type) {
} else {
for (i in cat) {
if (cat.hasOwnProperty(i)) {
keyDetacher(cat, i);
}
}
}
}
// If this is an event handle, use it to detach
// extra redirection so we catch adaptor events too. take a look at this.
}
// The YUI instance handles DOM events and adaptors
if (this instanceof YUI) {
// use the adaptor specific detach code if
// DOM event fork
}
}
if (ce) {
}
},
/**
* detach a listener
* @method unsubscribe
* @deprecated use detach
*/
unsubscribe: function() {
},
/**
* Removes all listeners from the specified event. If the event type
* is not specified, all listeners from all hosted custom events will
* be removed.
* @method detachAll
* @param type {string} The type, or name of the event
*/
},
/**
* Removes all listeners from the specified event. If the event type
* is not specified, all listeners from all hosted custom events will
* be removed.
* @method unsubscribeAll
* @param type {string} The type, or name of the event
* @deprecated use detachAll
*/
unsubscribeAll: function() {
},
/**
* Creates a new custom event of the specified type. If a custom event
* by that name already exists, it will not be re-created. In either
* case the custom event is returned.
*
* @method publish
*
* @param type {string} the type, or name of the event
* @param opts {object} optional config params. Valid properties are:
*
* <ul>
* <li>
* 'broadcast': whether or not the YUI instance and YUI global are notified when the event is fired (false)
* </li>
* <li>
* 'bubbles': whether or not this event bubbles (true)
* </li>
* <li>
* 'context': the default execution context for the listeners (this)
* </li>
* <li>
* 'defaultFn': the default function to execute when this event fires if preventDefault was not called
* </li>
* <li>
* 'emitFacade': whether or not this event emits a facade (false)
* </li>
* <li>
* 'prefix': the prefix for this targets events, e.g., 'menu' in 'menu:click'
* </li>
* <li>
* 'fireOnce': if an event is configured to fire once, new subscribers after
* the fire will be notified immediately.
* </li>
* <li>
* 'preventable': whether or not preventDefault() has an effect (true)
* </li>
* <li>
* 'preventedFn': a function that is executed when preventDefault is called
* </li>
* <li>
* 'queuable': whether or not this event can be queued during bubbling (false)
* </li>
* <li>
* 'silent': if silent is true, debug messages are not provided for this event.
* </li>
* <li>
* 'stoppedFn': a function that is executed when stopPropagation is called
* </li>
* <li>
* 'type': the event type (valid option if not provided as the first parameter to publish)
* </li>
* </ul>
*
* @return {CustomEvent} the custom event
*
*/
ret = {};
}, this);
return ret;
}
if (ce) {
// ce.log("publish applying new config to published event: '"+type+"' exists", 'info', 'event');
if (opts) {
}
} else {
// apply defaults
}
// make sure we turn the broadcast flag off if this
// event was published as a result of bubbling
// if (opts instanceof Y.CustomEvent) {
// events[type].broadcast = false;
// }
},
/**
* Registers another EventTarget as a bubble target. Bubble order
* is determined by the order registered. Multiple targets can
* be specified.
* @method addTarget
* @param o {EventTarget} the target to add
*/
addTarget: function(o) {
this._yuievt.hasTargets = true;
},
/**
* Removes a bubble target
* @method removeTarget
* @param o {EventTarget} the target to remove
*/
removeTarget: function(o) {
},
/**
* Fire a custom event by name. The callback functions will be executed
* from the context specified when the event was created, and with the
* following parameters.
*
* If the custom event object hasn't been created, then the event hasn't
* been published and it has no subscribers. For performance sake, we
* immediate exit in this case. This means the event won't bubble, so
* if the intention is that a bubble target be notified, the event must
* be published on this object first.
*
* The first argument is the event type, and any additional arguments are
* passed to the listeners as parameters. If the first of these is an
* object literal, and the event is configured to emit an event facade,
* that object is mixed into the event facade and the facade is provided
* in place of the original object.
*
* @method fire
* @param type {String|Object} The type of the event, or an object that contains
* a 'type' property.
* @param arguments {Object*} an arbitrary set of parameters to pass to
* the handler. If the first of these is an object literal and the event is
* configured to emit an event facade, the event facade will replace that
* parameter after the properties the object literal contains are copied to
* the event facade.
* @return {EventTarget} the event host
*
*/
}
// this event has not been published or subscribed to
if (!ce) {
if (this._yuievt.hasTargets) {
}
// otherwise there is nothing to be done
ret = true;
} else {
// if (ret) { }
// clear target for next fire()
}
},
var ce2;
// delegate to *:type events if there are subscribers
// console.log(type);
if (ce2) {
// console.log("GOT ONE: " + type);
// ret = ce2.fire.apply(ce2, a);
}
}
return ce2;
},
/**
* Returns the custom event of the provided type has been created, a
* falsy value otherwise
* @method getEvent
* @param type {string} the type, or name of the event
* @param prefixed {string} if true, the type is prefixed already
* @return {CustomEvent} the custom event or null
*/
var pre, e;
if (!prefixed) {
}
return e[type] || null;
},
/**
* Subscribe to a custom event hosted by this object. The
* supplied callback will execute after any listeners add
* via the subscribe method, and after the default function,
* if configured for the event, has executed.
* @method after
* @param type {string} The type of the event
* @param fn {Function} The callback
* @return the event target or a detach handle per 'chain' config
*/
var a = Y.Array(arguments, 0, true);
case 'function':
case 'object':
a[0]._after = true;
break;
default:
}
},
/**
* Executes the callback before a DOM event, custom event
* or method. If the first argument is a function, it
* is assumed the target is a method. For DOM and custom
* events, this is an alias for Y.on.
*
* For DOM and custom events:
* type, callback, context, 0-n arguments
*
* For methods:
* callback, object (method host), methodName, context, 0-n arguments
*
* @method before
* @return detach handle
* @deprecated use the on method
*/
before: function() {
}
};
Y.EventTarget = ET;
// make Y an event target
bubbles: false
});
/**
* Hosts YUI page level events. This is where events bubble to
* when the broadcast config is set to 2. This property is
* only available if the custom event module is loaded.
* @property Global
* @type EventTarget
* @for YUI
*/
// @TODO implement a global namespace function on Y.Global?
})();
/**
* <code>YUI</code>'s <code>on</code> method is a unified interface for subscribing to
* most events exposed by YUI. This includes custom events, DOM events, and
* function events. <code>detach</code> is also provided to remove listeners
* serviced by this function.
*
* The signature that <code>on</code> accepts varies depending on the type
* of event being consumed. Refer to the specific methods that will
* service a specific request for additional information about subscribing
* to that type of event.
*
* <ul>
* <li>Custom events. These events are defined by various
* modules in the library. This type of event is delegated to
* <code>EventTarget</code>'s <code>on</code> method.
* <ul>
* <li>The type of the event</li>
* <li>The callback to execute</li>
* <li>An optional context object</li>
* <li>0..n additional arguments to supply the callback.</li>
* </ul>
* Example:
* <code>Y.on('domready', function() { // start work });</code>
* </li>
* <li>DOM events. These are moments reported by the browser related
* to browser functionality and user interaction.
* This type of event is delegated to <code>Event</code>'s
* <code>attach</code> method.
* <ul>
* <li>The type of the event</li>
* <li>The callback to execute</li>
* <li>The specification for the Node(s) to attach the listener
* refereces.</li>
* <li>An optional context object</li>
* <li>0..n additional arguments to supply the callback.</li>
* </ul>
* Example:
* <code>Y.on('click', function(e) { // something was clicked }, '#someelement');</code>
* </li>
* <li>Function events. These events can be used to react before or after a
* function is executed. This type of event is delegated to <code>Event.Do</code>'s
* <code>before</code> method.
* <ul>
* <li>The callback to execute</li>
* <li>The object that has the function that will be listened for.</li>
* <li>The name of the function to listen for.</li>
* <li>An optional context object</li>
* <li>0..n additional arguments to supply the callback.</li>
* </ul>
* Example <code>Y.on(function(arg1, arg2, etc) { // obj.methodname was executed }, obj 'methodname');</code>
* </li>
* </ul>
*
* <code>on</code> corresponds to the moment before any default behavior of
* the event. <code>after</code> works the same way, but these listeners
* execute after the event's default behavior. <code>before</code> is an
* alias for <code>on</code>.
*
* @method on
* @param type** event type (this parameter does not apply for function events)
* @param fn the callback
* @param target** a descriptor for the target (applies to custom events only).
* For function events, this is the object that contains the function to
* execute.
* @param extra** 0..n Extra information a particular event may need. These
* will be documented with the event. In the case of function events, this
* is the name of the function to execute on the host. In the case of
* delegate listeners, this is the event delegation specification.
* @param context optionally change the value of 'this' in the callback
* @param args* 0..n additional arguments to pass to the callback.
* @return the event target or a detach handle per 'chain' config
* @for YUI
*/
/**
* after() is a unified interface for subscribing to
* most events exposed by YUI. This includes custom events,
* DOM events, and AOP events. This works the same way as
* the on() function, only it operates after any default
* behavior for the event has executed. @see <code>on</code> for more
* information.
* @method after
* @param type event type (this parameter does not apply for function events)
* @param fn the callback
* @param target a descriptor for the target (applies to custom events only).
* For function events, this is the object that contains the function to
* execute.
* @param extra 0..n Extra information a particular event may need. These
* will be documented with the event. In the case of function events, this
* is the name of the function to execute on the host. In the case of
* delegate listeners, this is the event delegation specification.
* @param context optionally change the value of 'this' in the callback
* @param args* 0..n additional arguments to pass to the callback.
* @return the event target or a detach handle per 'chain' config
* @for YUI
*/