CustomEvent Class
yui3/src/event-custom/js/event-custom.js:56
Parent Module: event-custom
The CustomEvent class lets you define events for your application that can be subscribed to by one or more independent component.
Constructor
CustomEvent
-
type -
defaults
Parameters:
-
typeStringThe type of event, which is passed to the callback when the event fires.
-
defaultsObjectconfiguration object.
Index
Methods
- _addFacadeToArgs
- _broadcast
- _createFacade
- _delete
- _fire
- _hasPotentialSubscribers
- _notify
- _on
- _procSubs
- after
- applyConfig
- detach
- detachAll
- fire
- fireSimple
- getSubs
- halt
- hasSubs
- log
- monitor
- on
- preventDefault
- stopImmediatePropagation
- stopPropagation
- subscribe deprecated
- unsubscribe deprecated
- unsubscribeAll deprecated
Properties
- _afters
- _subscribers
- afters deprecated
- async
- broadcast
- bubbles
- context
- defaultFn
- defaultTargetOnly
- emitFacade
- fired
- firedWith
- fireOnce
- host
- keepDeprecatedSubs static deprecated
- monitored
- preventable
- prevented
- preventedFn
- queuable
- signature
- silent
- stopped
- stoppedFn
- subscribers deprecated
- type
Methods
_addFacadeToArgs
-
The
Utility method to manipulate the args array passed in, to add the event facade, if it's not already the first arg.
Parameters:
-
TheArrayarguments to manipulate
_broadcast
-
args
Notifies the YUI instance if the event is configured with broadcast = 1, and both the YUI instance and Y.Global if configured with broadcast = 2.
Parameters:
-
argsArrayArguments sent to fire()
_createFacade
-
fireArgs
Internal utility method to create a new facade instance and insert it into the fire argument list, accounting for any payload merging which needs to happen.
This used to be called _getFacade, but the name seemed inappropriate
when it was used without a need for the return value.
Parameters:
-
fireArgsArrayThe arguments passed to "fire", which need to be shifted (and potentially merged) when the facade is added.
Returns:
The event facade created.
_delete
-
s -
subs -
index
Deletes the subscriber from the internal store of on() and after() subscribers.
Parameters:
-
sObjectsubscriber object.
-
subsObject(optional) on or after subscriber array
-
indexObject(optional) The index found.
_fire
-
args
Private internal implementation for fire, which is can be used directly by
EventTarget and other event module classes which have already converted from
an arguments list to an array, to avoid the repeated overhead.
Parameters:
-
argsArrayThe array of arguments passed to be passed to handlers.
Returns:
false if one of the subscribers returned false, true otherwise.
_hasPotentialSubscribers
()
Boolean
private
Returns:
Whether the event has potential subscribers or not
_notify
-
s -
args
Notify a single subscriber
Parameters:
-
sSubscriberthe subscriber.
-
argsArraythe arguments array to apply to the listener.
_on
-
fn -
[context] -
[args] -
[when]
Create the Subscription for subscribing function, context, and bound arguments. If this is a fireOnce event, the subscriber is immediately notified.
Parameters:
-
fnFunctionSubscription callback
-
[context]Object optionalOverride
thisin the callback -
[args]Array optionalbound arguments that will be passed to the callback after the arguments generated by fire()
-
[when]String optional"after" to slot into after subscribers
Returns:
_procSubs
-
subs -
args -
ef
Notifies a list of subscribers.
Parameters:
-
subsArrayList of subscribers
-
argsArrayArguments passed to fire()
-
efObject
Returns:
Boolean false if a subscriber returns false or stops the event propagation via e.stopPropagation(), e.stopImmediatePropagation(), or e.halt()
after
-
fn -
context -
arg
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.
Parameters:
-
fnFunctionThe function to execute.
-
contextObjectoptional execution context.
-
argMixed multiple0..n additional arguments to supply to the subscriber when the event fires.
Returns:
handle Unsubscribe handle.
applyConfig
-
o -
force
Apply configuration properties. Only applies the CONFIG whitelist
Parameters:
-
oObjecthash of properties to apply.
-
forceBooleanif true, properties that exist on the event will be overwritten.
detach
-
fn -
context
Detach listeners.
Parameters:
-
fnFunctionThe subscribed function to remove, if not supplied all will be removed.
-
contextObjectThe context object passed to subscribe.
Returns:
returns the number of subscribers unsubscribed.
fire
-
arguments
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>
Parameters:
-
argumentsObjectan arbitrary set of parameters to pass to the handler.
Returns:
false if one of the subscribers returned false, true otherwise.
fireSimple
-
args
Set up for notifying subscribers of non-emitFacade events.
Parameters:
-
argsArrayArguments passed to fire()
Returns:
Boolean false if a subscriber returned false
getSubs
()
Array
Get all of the subscribers to this event and any sibling event
Returns:
first item is the on subscribers, second the after.
halt
-
immediate
Stops the event propagation and prevents the default event behavior.
Parameters:
-
immediateBooleanif true additional listeners on the current target will not be executed
hasSubs
()
Returns the number of subscribers for this event as the sum of the on() subscribers and after() subscribers.
Returns:
Number
log
-
msg -
cat
Logger abstraction to centralize the application of the silent flag
Parameters:
-
msgStringmessage to log.
-
catStringlog category.
monitor
-
what
Monitor the event state for the subscribed event. The first parameter is what should be monitored, the rest are the normal parameters when subscribing to an event.
Parameters:
-
whatStringwhat to monitor ('detach', 'attach', 'publish').
Returns:
return value from the monitor event subscription.
on
-
fn -
context -
arg
Listen for this event
Parameters:
-
fnFunctionThe function to execute.
-
contextObjectoptional execution context.
-
argMixed multiple0..n additional arguments to supply to the subscriber when the event fires.
Returns:
An object with a detach method to detch the handler(s).
preventDefault
()
Prevents the execution of this event's defaultFn
stopImmediatePropagation
()
Stops propagation to bubble targets, and prevents any remaining subscribers on the current target from executing.
stopPropagation
()
Stop propagation to bubble targets
subscribe
-
fn
Listen for this event
Parameters:
-
fnFunctionThe function to execute.
Returns:
Unsubscribe handle.
unsubscribe
-
fn -
context
Detach listeners.
Parameters:
-
fnFunctionThe subscribed function to remove, if not supplied all will be removed.
-
contextObjectThe context object passed to subscribe.
Returns:
returns the number of subscribers unsubscribed.
Properties
_afters
Subscriber
private
'After' subscribers
_subscribers
Subscriber
private
The subscribers to this event
async
Boolean
fireOnce listeners will fire syncronously unless async is set to true
Default: false
broadcast
Int
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.
bubbles
Boolean
Specifies whether or not a subscriber can stop the event propagation via stopPropagation(), stopImmediatePropagation(), or halt()
Events can only bubble if emitFacade is true.
Default: true
context
Object
The context the the event will fire from by default. Defaults to the YUI instance.
defaultFn
Function
The default function to execute after event listeners have fire, but only if the default action was not prevented.
defaultTargetOnly
Boolean
Flag for the default function to execute only if the
firing event is the current target. This happens only
when using custom event delegation and setting the
flag to true mimics the behavior of event delegation
in the DOM.
Default: false
emitFacade
Boolean
If set to true, the custom event will deliver an EventFacade object that is similar to a DOM event object.
Default: false
fired
Boolean
This event has fired if true
Default: false;
firedWith
Array
An array containing the arguments the custom event was last fired with.
fireOnce
Boolean
This event should only fire one time if true, and if it has fired, any new subscribers should be notified immediately.
Default: false;
keepDeprecatedSubs
Boolean
deprecated
static
Static flag to enable population of the <a href="#property_subscribers">subscribers</a>
and <a href="#property_subscribers">afters</a> properties held on a CustomEvent instance.
These properties were changed to private properties (_subscribers and _afters), and
converted from objects to arrays for performance reasons.
Setting this property to true will populate the deprecated subscribers and afters
properties for people who may be using them (which is expected to be rare). There will
be a performance hit, compared to the new array based implementation.
If you are using these deprecated properties for a use case which the public API does not support, please file an enhancement request, and we can provide an alternate public implementation which doesn't have the performance cost required to maintiain the properties as objects.
Default: false
monitored
Boolean
Monitor when an event is attached or detached.
preventable
Boolean
Specifies whether or not this event's default function can be cancelled by a subscriber by executing preventDefault() on the event facade
Default: true
prevented
Int
Flag for preventDefault that is modified during fire(). if it is not 0, the default behavior for this event
preventedFn
Function
The function to execute if a subscriber calls preventDefault
queuable
Boolean
Specifies whether this event should be queued when the host is actively processing an event. This will effect exectution order of the callbacks for the various events.
Default: false
signature
Int
Supports multiple options for listener signatures in order to port YUI 2 apps.
Default: 9
silent
Boolean
By default all custom events are logged in the debug build, set silent to true to disable debug outpu for this event.
stopped
Int
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.
stoppedFn
Function
The function to execute if a subscriber calls stopPropagation or stopImmediatePropagation
type
String
The type of event, returned to subscribers when the event fires