Version 3.18.1
Show:

CustomEvent Class

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:

  • type String

    The type of event, which is passed to the callback when the event fires.

  • defaults Object

    configuration object.

Methods

_addFacadeToArgs

(
  • The
)
private

Provided by the event-custom-complex module.

Defined in event-custom/js/event-facade.js:420

Utility method to manipulate the args array passed in, to add the event facade, if it's not already the first arg.

Parameters:

  • The Array

    arguments to manipulate

_broadcast

(
  • args
)
private

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:

  • args Array

    Arguments sent to fire()

_createFacade

(
  • fireArgs
)
EventFacade private

Provided by the event-custom-complex module.

Defined in event-custom/js/event-facade.js:360

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:

  • fireArgs Array

    The arguments passed to "fire", which need to be shifted (and potentially merged) when the facade is added.

Returns:

EventFacade:

The event facade created.

_delete

(
  • s
  • subs
  • index
)
private

Deletes the subscriber from the internal store of on() and after() subscribers.

Parameters:

  • s Object

    subscriber object.

  • subs Object

    (optional) on or after subscriber array

  • index Object

    (optional) The index found.

_fire

(
  • args
)
Boolean private

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:

  • args Array

    The array of arguments passed to be passed to handlers.

Returns:

Boolean:

false if one of the subscribers returned false, true otherwise.

_hasPotentialSubscribers

() Boolean private

Provided by the event-custom-complex module.

Defined in event-custom/js/event-facade.js:350

Returns:

Boolean:

Whether the event has potential subscribers or not

_notify

(
  • s
  • args
)
protected

Notify a single subscriber

Parameters:

  • s Subscriber

    the subscriber.

  • args Array

    the arguments array to apply to the listener.

_on

(
  • fn
  • [context]
  • [args]
  • [when]
)
EventHandle protected

Create the Subscription for subscribing function, context, and bound arguments. If this is a fireOnce event, the subscriber is immediately notified.

Parameters:

  • fn Function

    Subscription callback

  • [context] Object optional

    Override this in the callback

  • [args] Array optional

    bound 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
)
private

Notifies a list of subscribers.

Parameters:

  • subs Array

    List of subscribers

  • args Array

    Arguments passed to fire()

  • ef Object

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
)
EventHandle

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:

  • fn Function

    The function to execute.

  • context Object

    optional execution context.

  • arg Mixed multiple

    0..n additional arguments to supply to the subscriber when the event fires.

Returns:

EventHandle:

handle Unsubscribe handle.

applyConfig

(
  • o
  • force
)

Apply configuration properties. Only applies the CONFIG whitelist

Parameters:

  • o Object

    hash of properties to apply.

  • force Boolean

    if true, properties that exist on the event will be overwritten.

detach

(
  • fn
  • context
)
Number

Detach listeners.

Parameters:

  • fn Function

    The subscribed function to remove, if not supplied all will be removed.

  • context Object

    The context object passed to subscribe.

Returns:

Number:

returns the number of subscribers unsubscribed.

detachAll

() Number

Removes all listeners

Returns:

Number:

The number of listeners unsubscribed.

fire

(
  • arguments
)
Boolean

Notifies the subscribers. The callback functions will be executed from the context specified when the event was created, and with the following parameters:

  • The type of event
  • All of the arguments fire() was executed with as an array
  • The custom object (if any) that was passed into the subscribe() method

Parameters:

  • arguments Object*

    an arbitrary set of parameters to pass to the handler.

Returns:

Boolean:

false if one of the subscribers returned false, true otherwise.

fireSimple

(
  • args
)
protected

Set up for notifying subscribers of non-emitFacade events.

Parameters:

  • args Array

    Arguments 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:

Array:

first item is the on subscribers, second the after.

halt

(
  • immediate
)

Provided by the event-custom-complex module.

Defined in event-custom/js/event-facade.js:480

Stops the event propagation and prevents the default event behavior.

Parameters:

  • immediate Boolean

    if 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:

monitor

(
  • what
)
EventHandle

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:

  • what String

    what to monitor ('detach', 'attach', 'publish').

Returns:

EventHandle:

return value from the monitor event subscription.

on

(
  • fn
  • context
  • arg
)
EventHandle

Listen for this event

Parameters:

  • fn Function

    The function to execute.

  • context Object

    optional execution context.

  • arg Mixed multiple

    0..n additional arguments to supply to the subscriber when the event fires.

Returns:

EventHandle:

An object with a detach method to detch the handler(s).

preventDefault

()

Provided by the event-custom-complex module.

Defined in event-custom/js/event-facade.js:467

Prevents the execution of this event's defaultFn

stopImmediatePropagation

()

Provided by the event-custom-complex module.

Defined in event-custom/js/event-facade.js:452

Stops propagation to bubble targets, and prevents any remaining subscribers on the current target from executing.

stopPropagation

()

Provided by the event-custom-complex module.

Defined in event-custom/js/event-facade.js:437

Stop propagation to bubble targets

subscribe

(
  • fn
)
EventHandle deprecated

Defined in event-custom/js/event-custom.js:497

Deprecated: use on.

Listen for this event

Parameters:

Returns:

EventHandle:

Unsubscribe handle.

unsubscribe

(
  • fn
  • context
)
Int | Undefined deprecated

Defined in event-custom/js/event-custom.js:588

Deprecated: use detach.

Detach listeners.

Parameters:

  • fn Function

    The subscribed function to remove, if not supplied all will be removed.

  • context Object

    The context object passed to subscribe.

Returns:

Int | Undefined:

returns the number of subscribers unsubscribed.

unsubscribeAll

() Number deprecated

Defined in event-custom/js/event-custom.js:780

Deprecated: use detachAll.

Removes all listeners

Returns:

Number:

The number of listeners unsubscribed.

Properties

_afters

Subscriber private

'After' subscribers

_subscribers

Subscriber private

The subscribers to this event

afters

Subscriber deprecated

'After' subscribers

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;

host

EventTarget

Specifies the host for this custom event. This is used to enable event bubbling

keepDeprecatedSubs

Boolean deprecated static

Static flag to enable population of the subscribers and afters 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

subscribers

Subscriber deprecated

The subscribers to this event

type

String

The type of event, returned to subscribers when the event fires