Event.Custom.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.Custom (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.Custom
</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.Custom</b>
<span class="extends">
</span>
<span class="extends">
</span>
</code>
</h2>
<!-- class tree goes here -->
<div class="summary description">
The Event.Custom class lets you define events for your application
that can be subscribed to by one or more independent component.
</div>
<div class="section constructor details">
<h3 id="constructor">Constructor</h3>
<div class="content">
<div class="detail">
<strong>Event.Custom</strong>
<code>
(
type
,
context
,
silent
)
</code>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>type
&lt;String&gt;
</code>
The type of event, which is passed to the callback
when the event fires
</dd>
<dd>
<code>context
&lt;Object&gt;
</code>
The context the event will fire from. "this" will
refer to this object in the callback. Default value:
the window object. The listener can override this.
</dd>
<dd>
<code>silent
&lt;boolean&gt;
</code>
pass true to prevent the event from writing to
the debug system
</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="section field details">
<h3 id="properties">Properties</h3>
<div class="content">
<div class="">
<h4><a name="property_afters">afters</a>
<code>- Event.Subscriber{}</code>
</h4>
<div class="detail">
<div class="description">
'After' subscribers
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_broadcast">broadcast</a>
<code>- int</code>
</h4>
<div class="detail">
<div class="description">
If 0, this event does not broadcast. If 1, the YUI instance is notified
every time this event fires. If 2, the YUI instance and the YUI global
(if event is enabled on the global) are notified every time this event
fires.
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_bubbles">bubbles</a>
<code>- boolean</code>
</h4>
<div class="detail">
<div class="description">
Specifies whether or not a subscriber can stop the event propagation
via stopPropagation(), stopImmediatePropagation(), or halt()
</div>
</div>
<div class="default">
Default Value: true
</div>
<hr />
</div>
<div class="">
<h4><a name="property_context">context</a>
<code>- object</code>
</h4>
<div class="detail">
<div class="description">
The context the the event will fire from by default. Defaults to the YUI
instance.
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_defaultFn">defaultFn</a>
<code>- Function</code>
</h4>
<div class="detail">
<div class="description">
The default function to execute after event listeners
have fire, but only if the default action was not
prevented.
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_fired">fired</a>
<code>- boolean</code>
</h4>
<div class="detail">
<div class="description">
This event has fired if true
</div>
</div>
<div class="default">
Default Value: false;
</div>
<hr />
</div>
<div class="">
<h4><a name="property_fireOnce">fireOnce</a>
<code>- boolean</code>
</h4>
<div class="detail">
<div class="description">
This event should only fire one time if true, and if
it has fired, any new subscribers should be notified
immediately.
</div>
</div>
<div class="default">
Default Value: false;
</div>
<hr />
</div>
<div class="">
<h4><a name="property_host">host</a>
<code>- Event.Target</code>
</h4>
<div class="detail">
<div class="description">
Specifies the host for this custom event. This is used
to enable event bubbling
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_preventable">preventable</a>
<code>- boolean</code>
</h4>
<div class="detail">
<div class="description">
Specifies whether or not this event's default function
can be canceled by a subscriber by executing preventDefault()
on the event facade
</div>
</div>
<div class="default">
Default Value: true
</div>
<hr />
</div>
<div class="">
<h4><a name="property_prevented">prevented</a>
<code>- int</code>
</h4>
<div class="detail">
<div class="description">
Flag for preventDefault that is modified during fire().
if it is not 0, the default behavior for this event
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_preventedFn">preventedFn</a>
<code>- Function</code>
</h4>
<div class="detail">
<div class="description">
The function to execute if a subscriber calls
preventDefault
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_silent">silent</a>
<code>- boolean</code>
</h4>
<div class="detail">
<div class="description">
By default all custom events are logged in the debug build, set silent
to true to disable debug outpu for this event.
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_stopped">stopped</a>
<code>- int</code>
</h4>
<div class="detail">
<div class="description">
Flag for stopPropagation that is modified during fire()
1 means to stop propagation to bubble targets. 2 means
to also stop additional subscribers on this target.
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_stoppedFn">stoppedFn</a>
<code>- Function</code>
</h4>
<div class="detail">
<div class="description">
The function to execute if a subscriber calls
stopPropagation or stopImmediatePropagation
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_subscribers">subscribers</a>
<code>- Event.Subscriber{}</code>
</h4>
<div class="detail">
<div class="description">
The subscribers to this event
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_type">type</a>
<code>- string</code>
</h4>
<div class="detail">
<div class="description">
The type of event, returned to subscribers when the event fires
</div>
</div>
<hr />
</div>
</div>
</div>
<div class="section method details">
<h3 id="methods">Methods</h3>
<div class="content">
<div class="private">
<h4>
<a name="method__delete">_delete</a></h4>
<div class="detail">
<code>
private
void
<strong>_delete</strong>
(
subscriber
)
</code>
<div class="description">
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>subscriber &lt;object&gt;</code>
object
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="private">
<h4>
<a name="method__notify">_notify</a></h4>
<div class="detail">
<code>
private
void
<strong>_notify</strong>
(
s
,
args
)
</code>
<div class="description">
Notify a single subscriber
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>s &lt;Event.Subscriber&gt;</code>
the subscriber
</dd>
<dd>
<code>args &lt;Array&gt;</code>
the arguments array to apply to the listener
</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>
Event.Handle
<strong>after</strong>
(
fn
,
obj
,
args*
)
</code>
<div class="description">
Listen for this event after the normal subscribers have been notified and
the default behavior has been applied. If a normal subscriber prevents the
default behavior, it also prevents after listeners from firing.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>fn &lt;Function&gt;</code>
The function to execute
</dd>
<dd>
<code>obj &lt;Object&gt;</code>
An object to be passed along when the event fires
</dd>
<dd>
<code>args* &lt;object&gt;</code>
1..n params to provide to the listener
</dd>
</dl>
<dl>
<dt>Returns:
<code>
Event.Handle
</code></dt>
<dd>unsubscribe handle</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_applyConfig">applyConfig</a></h4>
<div class="detail">
<code>
void
<strong>applyConfig</strong>
(
o
,
force
)
</code>
<div class="description">
Apply configuration properties. Only applies the CONFIG whitelist
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>o &lt;object&gt;</code>
hash of properties to apply
</dd>
<dd>
<code>force &lt;boolean&gt;</code>
if true, properties that exist on the event
will be overwritten.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_fire">fire</a></h4>
<div class="detail">
<code>
boolean
<strong>fire</strong>
(
arguments
)
</code>
<div class="description">
Notifies the subscribers. The callback functions will be executed
from the context specified when the event was created, and with the
following parameters:
<ul>
<li>The type of event</li>
<li>All of the arguments fire() was executed with as an array</li>
<li>The custom object (if any) that was passed into the subscribe()
method</li>
</ul>
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<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>false if one of the subscribers returned false,
true otherwise</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_log">log</a></h4>
<div class="detail">
<code>
void
<strong>log</strong>
(
msg
,
cat
)
</code>
<div class="description">
Logger abstraction to centralize the application of the silent flag
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>msg &lt;string&gt;</code>
message to log
</dd>
<dd>
<code>cat &lt;string&gt;</code>
log category
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_preventDefault">preventDefault</a></h4>
<div class="detail">
<code>
void
<strong>preventDefault</strong>
(
)
</code>
<div class="description">
Prevents the execution of this event's defaultFn
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_stopImmediatePropagation">stopImmediatePropagation</a></h4>
<div class="detail">
<code>
void
<strong>stopImmediatePropagation</strong>
(
)
</code>
<div class="description">
Stops propagation to bubble targets, and prevents any remaining
subscribers on the current target from executing.
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_stopPropagation">stopPropagation</a></h4>
<div class="detail">
<code>
void
<strong>stopPropagation</strong>
(
)
</code>
<div class="description">
Stop propagation to bubble targets
</div>
<div class="description">
<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>
Event.Handle
<strong>subscribe</strong>
(
fn
,
obj
,
args*
)
</code>
<div class="description">
Listen for this event
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>fn &lt;Function&gt;</code>
The function to execute
</dd>
<dd>
<code>obj &lt;Object&gt;</code>
An object to be passed along when the event fires
</dd>
<dd>
<code>args* &lt;object&gt;</code>
1..n params to provide to the listener
</dd>
</dl>
<dl>
<dt>Returns:
<code>
Event.Handle
</code></dt>
<dd>unsubscribe handle</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_toString">toString</a></h4>
<div class="detail">
<code>
void
<strong>toString</strong>
(
)
</code>
<div class="description">
</div>
<div class="description">
<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>
(
fn
,
obj
)
</code>
<div class="description">
Unsubscribes subscribers.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>fn &lt;Function&gt;</code>
The subscribed function to remove, if not supplied
all will be removed
</dd>
<dd>
<code>obj &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>
int
<strong>unsubscribeAll</strong>
(
)
</code>
<div class="description">
Removes all listeners
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
int
</code></dt>
<dd>The number of listeners unsubscribed</dd>
</dl>
</div>
</div>
<hr />
</div>
</div>
</div>
<div class="section method details">
<h3 id="events">Events</h3>
<div class="content">
<div class="">
<h4>
<a name="event_subscribeEvent">subscribeEvent</a></h4>
<div class="detail">
<code>
<strong>subscribeEvent</strong>
(
fn
,
obj
,
override
)
</code>
<div class="description">
Custom events provide a custom event that fires whenever there is
a new subscriber to the event. This provides an opportunity to
handle the case where there is a non-repeating event that has
already fired has a new subscriber.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>fn &lt;Function&gt;</code>
The function to execute
</dd>
<dd>
<code>obj &lt;Object&gt;</code>
An object to be passed along when the event
fires
</dd>
<dd>
<code>override &lt;boolean|Object&gt;</code>
If true, the obj passed in becomes
the execution context of the listener.
if an object, that object becomes the
the execution context.
</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="selected"><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=""><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>Properties</h4>
<ul class="content">
<li class=""><a href="#property_afters">afters</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_broadcast">broadcast</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_bubbles">bubbles</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_context">context</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_defaultFn">defaultFn</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_fired">fired</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_fireOnce">fireOnce</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_host">host</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_preventable">preventable</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_prevented">prevented</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_preventedFn">preventedFn</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_silent">silent</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_stopped">stopped</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_stoppedFn">stoppedFn</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_subscribers">subscribers</a>
<!--<code>&lt;string&gt;</code>-->
</li>
<li class=""><a href="#property_type">type</a>
<!--<code>&lt;string&gt;</code>-->
</li>
</ul>
</div>
<div class="module">
<h4>Methods</h4>
<ul class="content">
<li class="private"><!--<code>void</code>-->
<a href="#method__delete">_delete</a>
</li>
<li class="private"><!--<code>void</code>-->
<a href="#method__notify">_notify</a>
</li>
<li class=""><!--<code>Event.Handle</code>-->
<a href="#method_after">after</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_applyConfig">applyConfig</a>
</li>
<li class=""><!--<code>boolean</code>-->
<a href="#method_fire">fire</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_log">log</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_preventDefault">preventDefault</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_stopImmediatePropagation">stopImmediatePropagation</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_stopPropagation">stopPropagation</a>
</li>
<li class=""><!--<code>Event.Handle</code>-->
<a href="#method_subscribe">subscribe</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_toString">toString</a>
</li>
<li class=""><!--<code>boolean</code>-->
<a href="#method_unsubscribe">unsubscribe</a>
</li>
<li class=""><!--<code>int</code>-->
<a href="#method_unsubscribeAll">unsubscribeAll</a>
</li>
</ul>
</div>
<div class="module">
<h4>Events</h4>
<ul class="content">
<li class="">
<a href="#event_subscribeEvent">subscribeEvent</a>
</li>
</ul>
</div>
</div>
</div>
</div>
<div id="ft">
<hr />
Copyright &copy; 2008 Yahoo! Inc. All rights reserved.
</div>
</div>
</body>
</html>