static
Class Event
The event utility provides functions to add and remove event listeners,
event cleansing. It also tries to automatically remove listeners it
registers during the unload event.
Properties
_avail
- private static object
_dri
- private static object
document readystate poll handle
_el_events
- private static object
Custom event wrapper map DOM events. Key is
Element uid stamp. Each item is a hash of custom event
wrappers as provided in the _wrappers collection. This
provides the infrastructure for getListeners.
True after the onload event has fired
_retryCount
- private static object
The number of times to poll after window.onload. This number is
increased if additional late-bound handlers are requested after
the page load.
_wrappers
- private static Y.Event.Custom
Custom event wrappers for DOM events. Key is
'event:' + Element uid stamp + event type
DOMReady
- static boolean
True when the document is initially usable
addListener/removeListener can throw errors in unexpected scenarios.
These errors are suppressed, the method returns false, and this property
is set
The poll interval in milliseconds
The number of times we should look for elements that are not
in the DOM at the time the event is requested after the document
has been loaded. The default is 1000@amp;40 ms, so it will poll
for 40 seconds or until all outstanding handlers are bound
(whichever comes first).
Methods
private
static
boolean
_isValidCollection
(
o
)
We want to be able to use getElementsByTagName as a collection
to attach a group of events to. Unfortunately, different
browsers return different types of collections. This function
tests to determine if the object is array-like. It will also
fail if the object is an array, but is empty.
- Parameters:
-
o
<object>
the object to test
- Returns:
boolean
- true if the object is array-like and populated
Deprecated was not meant to be used directly
private
static
void
_load
(
)
hook up any deferred listeners
private
static
void
_poll
(
)
Polling function that runs before the onload event fires,
attempting to attach to DOM Nodes as soon as they are
available
private
static
void
_unload
(
)
Removes all listeners registered by pe.event. Called
automatically during the unload event.
static
EventHandle
attach
(
type
,
fn
,
el
,
context
,
args
)
Adds an event listener
- Parameters:
-
type
<String>
The type of event to append
-
fn
<Function>
The method the event invokes
-
el
<String|HTMLElement|Array|NodeList>
An id, an element
reference, or a collection of ids and/or elements to assign the
listener to.
-
context
<Object>
optional context object
-
args
<Boolean|object>
0..n arguments to pass to the callback
- Returns:
EventHandle
- an object to that can be used to detach the listener
static
boolean
detach
(
type
,
fn
,
el
)
Removes an event listener. Supports the signature the event was bound
with, but the preferred way to remove listeners is using the handle
that is returned when using Y.on
- Parameters:
-
type
<String>
the type of event to remove.
-
fn
<Function>
the method the event invokes. If fn is
undefined, then all event handlers for the type of event are
removed.
-
el
<String|HTMLElement|Array|NodeList|EventHandle>
An
event handle, an id, an element reference, or a collection
of ids and/or elements to remove the listener from.
- Returns:
boolean
- true if the unbind was successful, false otherwise.
static
void
Event.define
(
type
,
cfg
)
Static method to register a synthetic event definition and implementation
in the DOM Event subsystem.
Pass either a string type
and configuration object as
separate parameters or a configuration object that includes a
type
property as a single parameter.
The configuration object should include implementation methods for
on
and detach
. This is the full list of
configuration properties:
type
- Required if using the
Y.Event.define( config )
signature. The name of the synthetic event. What goes
node.on(HERE, callback )
.
on
function ( node, subscription, fireEvent )
The
implementation logic for subscription. Any special setup you need to
do to create the environment for the event being fired. E.g. native
DOM event subscriptions. Store subscription related objects and
information on the subscription
object. When the
criteria have been met to fire the synthetic event, call
fireEvent.fire()
.
detach
function ( node, subscription, fireEvent )
The
implementation logic for cleaning up a detached subscription. E.g.
detach any DOM subscriptions done in on
.
publishConfig
- (Object) The configuration object that will be used to instantiate
the underlying CustomEvent. By default, the event is defined with
emitFacade: true
so subscribers will receive a DOM-like
event object.
processArgs
function ( argArray )
Optional method to extract any
additional arguments from the subscription signature. Using this
allows on
signatures like node.on(
"hover", overCallback, outCallback )
. Be sure that
the args passed in is pruned of any additional arguments using, for
example, argArray.splice(2,1);
. Data returned from the
function will be stored on the subscription
object passed
to on
and detach
under
subscription._extra
.
-
- Parameters:
-
type
<String>
Name given to the synthetic event
-
cfg
<Object>
configuration object. Pass this as the first
parameter if it includes the type
property.
static
string
generateId
(
el
)
Generates an unique ID for the element if it does not already
have one.
- Parameters:
-
el
<object>
the element to create the id for
- Returns:
string
- the resulting id of the element
static
Event
getEvent
(
e
,
el
)
Finds the event in the window object, the caller's arguments, or
in the arguments of another method in the callstack. This is
executed automatically for events registered through the event
manager, so the implementer should not normally need to execute
this function at all.
- Parameters:
-
e
<Event>
the event parameter from the handler
-
el
<HTMLElement>
the element the listener was attached to
- Returns:
Event
- the event
static
Y.Custom.Event
getListeners
(
el
,
type
)
Returns all listeners attached to the given element via addListener.
Optionally, you can specify a specific type of event to return.
- Parameters:
-
el
<HTMLElement|string>
the element or element id to inspect
-
type
<string>
optional type of listener to return. If
left out, all listeners will be returned
- Returns:
Y.Custom.Event
- the custom event wrapper for the DOM event(s)
private
static
void
nativeAdd
(
el
,
type
,
fn
,
capture
)
Adds a DOM event directly without the caching, cleanup, context adj, etc
- Parameters:
-
el
<HTMLElement>
the element to bind the handler to
-
type
<string>
the type of event handler
-
fn
<function>
the callback to invoke
-
capture
<boolen>
capture or bubble phase
private
static
void
nativeRemove
(
el
,
type
,
fn
,
capture
)
Basic remove listener
- Parameters:
-
el
<HTMLElement>
the element to bind the handler to
-
type
<string>
the type of event handler
-
fn
<function>
the callback to invoke
-
capture
<boolen>
capture or bubble phase
static
void
onAvailable
(
id
,
fn
,
p_obj
,
p_override
,
checkContent
)
Executes the supplied callback when the item with the supplied
id is found. This is meant to be used to execute behavior as
soon as possible as the page loads. If you use this after the
initial page load it will poll for a fixed time for the element.
The number of times it will poll and the frequency are
configurable. By default it will poll for 10 seconds.
The callback is executed with a single parameter:
the custom object parameter, if provided.
- Parameters:
-
id
<string||string[]>
the id of the element, or an array
of ids to look for.
-
fn
<function>
what to execute when the element is found.
-
p_obj
<object>
an optional object to be passed back as
a parameter to fn.
-
p_override
<boolean|object>
If set to true, fn will execute
in the context of p_obj, if set to an object it
will execute in the context of that object
-
checkContent
<boolean>
check child node readiness (onContentReady)
Deprecated Use Y.on("available")
static
void
onContentReady
(
id
,
fn
,
p_obj
,
p_override
)
Works the same way as onAvailable, but additionally checks the
state of sibling elements to determine if the content of the
available element is safe to modify.
The callback is executed with a single parameter:
the custom object parameter, if provided.
- Parameters:
-
id
<string>
the id of the element to look for.
-
fn
<function>
what to execute when the element is ready.
-
p_obj
<object>
an optional object to be passed back as
a parameter to fn.
-
p_override
<boolean|object>
If set to true, fn will execute
in the context of p_obj. If an object, fn will
exectute in the context of that object
Deprecated Use Y.on("contentready")
static
void
purgeElement
(
el
,
recurse
,
type
)
Removes all listeners attached to the given element via addListener.
Optionally, the node's children can also be purged.
Optionally, you can specify a specific type of event to remove.
- Parameters:
-
el
<HTMLElement>
the element to purge
-
recurse
<boolean>
recursively purge this element's children
as well. Use with caution.
-
type
<string>
optional type of listener to purge. If
left out, all listeners will be removed
private
static
void
startInterval
(
)