Event.Target.html revision 62e7a7d39cc0c6d25fec20964c26bc35b9fa116a
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>API: event Event.Target (YUI Library)</title>
<link rel="stylesheet" type="text/css" href="assets/api.css">
<script type="text/javascript" src="assets/api-js"></script>
<script type="text/javascript" src="assets/ac-js"></script>
</head>
<body id="yahoo-com">
<div id="doc3" class="yui-t2">
<div id="hd">
<a href="http://developer.yahoo.com/yui/"><h1>Yahoo! UI Library</h1></a>
<h3>event&nbsp; <span class="subtitle">3.00PR1</span></h3>
<p>
<a href="/index.html">Yahoo! UI Library</a>
&gt; <a href="/module_event.html">event</a>
&gt; Event.Target
</p>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<form name="yui-classopts-form">
<span id="classopts"><input type="checkbox" name="showprivate" id="showprivate" /> Show Private</span>
<span id="classopts"><input type="checkbox" name="showprotected" id="showprotected" /> Show Protected</span>
<span id="classopts"><input type="checkbox" name="showdeprecated" id="showdeprecated" /> Show Deprecated</span>
</form>
<h2>
Class <b>Event.Target</b>
<span class="extends">
</span>
<span class="extends">
</span>
</code>
</h2>
<!-- class tree goes here -->
<div class="summary description">
Event.Target is designed to be used with Y.augment to wrap
Event.Custom in an interface that allows events to be subscribed 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.
</div>
<div class="section method details">
<h3 id="methods">Methods</h3>
<div class="content">
<div class="">
<h4>
<a name="method_addTarget">addTarget</a></h4>
<div class="detail">
<code>
void
<strong>addTarget</strong>
(
o
)
</code>
<div class="description">
Registers another Event.Target as a bubble target. Bubble order
is determined by the order registered. Multiple targets can
be specified.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>o &lt;Event.Target&gt;</code>
the target to add
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_after">after</a></h4>
<div class="detail">
<code>
void
<strong>after</strong>
(
type
,
fn
,
context
,
args*
)
</code>
<div class="description">
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.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>type &lt;string&gt;</code>
The type of the event
</dd>
<dd>
<code>fn &lt;Function&gt;</code>
The callback
</dd>
<dd>
<code>context &lt;object&gt;</code>
The execution context
</dd>
<dd>
<code>args* &lt;object&gt;</code>
1..n params to supply to the callback
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_before">before</a></h4>
<div class="detail">
<code>
void
<strong>before</strong>
(
)
</code>
<div class="description">
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:
type, callback, context, 1-n arguments
For methods:
callback, object (method host), methodName, context, 1-n arguments
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd>unsubscribe handle</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_bubble">bubble</a></h4>
<div class="detail">
<code>
boolean
<strong>bubble</strong>
(
evt
)
</code>
<div class="description">
Propagate an event
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>evt &lt;Event.Custom&gt;</code>
the custom event to propagate
</dd>
</dl>
<dl>
<dt>Returns:
<code>
boolean
</code></dt>
<dd>the aggregated return value from Event.Custom.fire</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_detach">detach</a></h4>
<div class="detail">
<code>
YUI
<strong>detach</strong>
(
type
,
f
,
o
)
</code>
<div class="description">
Detach an event listener (either a custom event or a
DOM event
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>type &lt;object&gt;</code>
the type of event, or a Event.Handle to
for the subscription. If the Event.Handle is passed
in, the other parameters are not used.
</dd>
<dd>
<code>f &lt;Function&gt;</code>
the subscribed function
</dd>
<dd>
<code>o &lt;object&gt;</code>
the object or element the listener is subscribed
to.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
YUI
</code></dt>
<dd>the YUI instance</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_fire">fire</a></h4>
<div class="detail">
<code>
boolean
<strong>fire</strong>
(
type
,
arguments
)
</code>
<div class="description">
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.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>type &lt;String|Object&gt;</code>
The type of the event, or an object that contains
a 'type' property.
</dd>
<dd>
<code>arguments &lt;Object*&gt;</code>
an arbitrary set of parameters to pass to
the handler.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
boolean
</code></dt>
<dd>the return value from Event.Custom.fire</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_getEvent">getEvent</a></h4>
<div class="detail">
<code>
Event.Target
<strong>getEvent</strong>
(
type
)
</code>
<div class="description">
Returns the custom event of the provided type has been created, a
falsy value otherwise
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>type &lt;string&gt;</code>
the type, or name of the event
</dd>
</dl>
<dl>
<dt>Returns:
<code>
Event.Target
</code></dt>
<dd>the custom event or a falsy value</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_on">on</a></h4>
<div class="detail">
<code>
Event.Handle
<strong>on</strong>
(
type
,
f
,
o
,
context
,
args*
)
</code>
<div class="description">
Attach an event listener, either to a DOM object
or to an Event.Target.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>type &lt;string&gt;</code>
the event type
</dd>
<dd>
<code>f &lt;Function&gt;</code>
the function to execute
</dd>
<dd>
<code>o &lt;object&gt;</code>
the Event.Target or element to attach to
</dd>
<dd>
<code>context &lt;object&gt;</code>
Optional execution context
</dd>
<dd>
<code>args* &lt;object&gt;</code>
0..n additional arguments to append
to the signature provided when the event fires.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
Event.Handle
</code></dt>
<dd>a handle object for
unsubscribing to this event.</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_publish">publish</a></h4>
<div class="detail">
<code>
Event.Custom
<strong>publish</strong>
(
type
,
opts
)
</code>
<div class="description">
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.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>type &lt;string&gt;</code>
the type, or name of the event
</dd>
<dd>
<code>opts &lt;object&gt;</code>
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>
'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>
</dd>
</dl>
<dl>
<dt>Returns:
<code>
Event.Custom
</code></dt>
<dd>the custom event</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_ready">ready</a></h4>
<div class="detail">
<code>
YUI
<strong>ready</strong>
(
f
,
c
,
args*
)
</code>
<div class="description">
Subscribes to the yui:load event, which fires when a Y.use operation
is complete.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>f &lt;Function&gt;</code>
the function to execute
</dd>
<dd>
<code>c &lt;object&gt;</code>
Optional execution context
</dd>
<dd>
<code>args* &lt;object&gt;</code>
0..n Additional arguments to append
to the signature provided when the event fires.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
YUI
</code></dt>
<dd>the YUI instance</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_removeTarget">removeTarget</a></h4>
<div class="detail">
<code>
void
<strong>removeTarget</strong>
(
o
)
</code>
<div class="description">
Removes a bubble target
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>o &lt;Event.Target&gt;</code>
the target to remove
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_subscribe">subscribe</a></h4>
<div class="detail">
<code>
void
<strong>subscribe</strong>
(
type
,
fn
,
context
,
args*
)
</code>
<div class="description">
Subscribe to a custom event hosted by this object
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>type &lt;string&gt;</code>
The type of the event
</dd>
<dd>
<code>fn &lt;Function&gt;</code>
The callback
</dd>
<dd>
<code>context &lt;object&gt;</code>
The execution context
</dd>
<dd>
<code>args* &lt;object&gt;</code>
1..n params to supply to the callback
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_unsubscribe">unsubscribe</a></h4>
<div class="detail">
<code>
boolean
<strong>unsubscribe</strong>
(
type
,
fn
,
context
)
</code>
<div class="description">
Unsubscribes one or more listeners the from the specified event
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>type &lt;string|Object&gt;</code>
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.
</dd>
<dd>
<code>fn &lt;Function&gt;</code>
The subscribed function to unsubscribe, if not
supplied, all subscribers will be removed.
</dd>
<dd>
<code>context &lt;Object&gt;</code>
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)
</dd>
</dl>
<dl>
<dt>Returns:
<code>
boolean
</code></dt>
<dd>true if the subscriber was found and detached.</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_unsubscribeAll">unsubscribeAll</a></h4>
<div class="detail">
<code>
void
<strong>unsubscribeAll</strong>
(
type
)
</code>
<div class="description">
Removes all listeners from the specified event. If the event type
is not specified, all listeners from all hosted custom events will
be removed.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>type &lt;string&gt;</code>
The type, or name of the event
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
</div>
</div>
</div>
</div>
<div class="yui-b">
<div class="nav">
<div class="module">
<h4>Modules</h4>
<ul class="content">
<li class=""><a href="module_anim.html">anim</a></li>
<li class=""><a href="module_anim-color.html">anim-color</a></li>
<li class=""><a href="module_anim-curve.html">anim-curve</a></li>
<li class=""><a href="module_anim-easing.html">anim-easing</a></li>
<li class=""><a href="module_anim-scroll.html">anim-scroll</a></li>
<li class=""><a href="module_anim-xy.html">anim-xy</a></li>
<li class=""><a href="module_attribute.html">attribute</a></li>
<li class=""><a href="module_base.html">base</a></li>
<li class=""><a href="module_dd-plugin.html">dd-plugin</a></li>
<li class="selected"><a href="module_event.html">event</a></li>
<li class=""><a href="module_io.html">io</a></li>
<li class=""><a href="module_json.html">json</a></li>
<li class=""><a href="module_loader.html">loader</a></li>
<li class=""><a href="module_node.html">node</a></li>
<li class=""><a href="module_node-class.html">node-class</a></li>
<li class=""><a href="module_node-region.html">node-region</a></li>
<li class=""><a href="module_node-screen.html">node-screen</a></li>
<li class=""><a href="module_queue.html">queue</a></li>
<li class=""><a href="module_yui.html">yui</a></li>
</ul>
</div>
<div class="module">
<h4>Classes</h4>
<ul class="content">
<li class=""><a href="Do.html">Do</a></li>
<li class=""><a href="Do.AlterArgs.html">Do.AlterArgs</a></li>
<li class=""><a href="Do.AlterReturn.html">Do.AlterReturn</a></li>
<li class=""><a href="Do.Error.html">Do.Error</a></li>
<li class=""><a href="Do.Method.html">Do.Method</a></li>
<li class=""><a href="Event.html">Event</a></li>
<li class=""><a href="Event.Custom.html">Event.Custom</a></li>
<li class=""><a href="Event.Facade.html">Event.Facade</a></li>
<li class=""><a href="Event.Handle.html">Event.Handle</a></li>
<li class=""><a href="Event.Subscriber.html">Event.Subscriber</a></li>
<li class="selected"><a href="Event.Target.html">Event.Target</a></li>
</ul>
</div>
<div class="module">
<h4>Files</h4>
<ul class="content">
<li class=""><a href="event-custom.js.html">event-custom.js</a></li>
<li class=""><a href="event-do.js.html">event-do.js</a></li>
<li class=""><a href="event-dom.js.html">event-dom.js</a></li>
<li class=""><a href="event-facade.js.html">event-facade.js</a></li>
<li class=""><a href="event-ready.js.html">event-ready.js</a></li>
<li class=""><a href="event-target.js.html">event-target.js</a></li>
<li class=""><a href="event.js.html">event.js</a></li>
</ul>
</div>
<div class="module">
<h4>Methods</h4>
<ul class="content">
<li class=""><!--<code>void</code>-->
<a href="#method_addTarget">addTarget</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_after">after</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_before">before</a>
</li>
<li class=""><!--<code>boolean</code>-->
<a href="#method_bubble">bubble</a>
</li>
<li class=""><!--<code>YUI</code>-->
<a href="#method_detach">detach</a>
</li>
<li class=""><!--<code>boolean</code>-->
<a href="#method_fire">fire</a>
</li>
<li class=""><!--<code>Event.Target</code>-->
<a href="#method_getEvent">getEvent</a>
</li>
<li class=""><!--<code>Event.Handle</code>-->
<a href="#method_on">on</a>
</li>
<li class=""><!--<code>Event.Custom</code>-->
<a href="#method_publish">publish</a>
</li>
<li class=""><!--<code>YUI</code>-->
<a href="#method_ready">ready</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_removeTarget">removeTarget</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_subscribe">subscribe</a>
</li>
<li class=""><!--<code>boolean</code>-->
<a href="#method_unsubscribe">unsubscribe</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_unsubscribeAll">unsubscribeAll</a>
</li>
</ul>
</div>
</div>
</div>
</div>
<div id="ft">
<hr />
Copyright &copy; 2008 Yahoo! Inc. All rights reserved.
</div>
</div>
</body>
</html>