/can-event

Event handling utilities

Primary LanguageJavaScript

can-event

Build Status

API

can-event Object

Add event functionality into your objects.

The canEvent object provides a number of methods for handling events in objects. This functionality is best used by mixing the canEvent object into an object or prototype. However, event listeners can still be used even on objects that don't include canEvent.

All methods provided by canEvent assume that they are mixed into an object -- this should be the object dispatching the events.

assign(YourClass.prototype, canEvent)

Adds event functionality to YourClass objects. This can also be applied to normal objects: assign(someObject, canEvent).

The assign function can be any function that assigns additional properties on an object such as Object.assign or lodash's _.assign or [can-util/js/assign/assign].

var assign = require("can-util/js/assign/assign");
var canEvent = require("can-event");

function Thing(){

}

assign(Thing.prototype, canEvent);

// Can not apply event listeners

var thing = new Thing();
thing.addEventListener("prop", function(){ ... });

obj.addEventListener(event, handler)

Add a basic event listener to an object.

var canEvent = require("can-event");

var obj = {};
Object.assign(obj, canEvent);

obj.addEventListener("foo", function(){ ... });
  1. event {String}: The name of the event to listen for.
  2. handler {function}: The handler that will be executed to handle the event.
  • returns {Object}: this

canEvent.addEventListener.call(obj, event, handler)

This syntax can be used for objects that don't include the canEvent mixin.

obj.removeEventListener(event, handler)

Removes a basic event listener from an object.

  1. event {String}: The name of the event to listen for.
  2. handler {function}: The handler that will be executed to handle the event.
  3. __validate {function}: An extra function that can validate an event handler as a match. This is an internal parameter and only used for can-event plugins.
  • returns {Object}: this

canEvent.removeEventListener.call(obj, event, handler)

This syntax can be used for objects that don't include the can-event mixin.

obj.dispatch(event, args)

Dispatches/triggers a basic event on an object.

var canEvent = require("can-event");

var obj = {};
Object.assign(obj, canEvent);

obj.addEventListener("foo", function(){
  console.log("FOO BAR!");
});

obj.dispatch("foo"); // Causes it to log FOO BAR
  1. event {String|Object}: The event to dispatch
  2. args {Array}: Additional arguments to pass to event handlers
  • returns {Object}: event The resulting event object

canEvent.dispatch.call(obj, event, args)

This syntax can be used for objects that don't include the can.event mixin.

obj.on(event, handler)

Add a basic event listener to an object.

This is an alias of addEventListener.

can-event.on.call(obj, event, handler)

This syntax can be used for objects that don't include the can-event mixin.

obj.off(event, handler)

Removes a basic event listener from an object.

This is an alias of removeEventListener.

canEvent.off.call(obj, event, handler)

This syntax can be used for objects that don't include the can-event mixin.

obj.one(event, handler)

Adds a basic event listener that listens to an event once and only once.

  1. event {String}: The name of the event to listen for.
  2. handler {function}: The handler that will be executed to handle the event.
  • returns {Object}: this

obj.listenTo(other, event, handler)

Listens for an event on another object. This is similar to concepts like event namespacing, except that the namespace is the scope of the calling object.

  1. other {Object}: The object to listen for events on.
  2. event {String}: The name of the event to listen for.
  3. handler {function}: The handler that will be executed to handle the event.
  • returns {Object}: this

canEvent.listenTo.call(obj, other, event, handler)

This syntax can be used for objects that don't include the can-event mixin.

obj.stopListening(other, event, handler)

Stops listening for an event on another object.

  1. other {Object}: The object to listen for events on.
  2. event {String}: The name of the event to listen for.
  3. handler {function}: The handler that will be executed to handle the event.
  • returns {Object}: this

canEvent.stopListening.call(obj, other, event, handler)

This syntax can be used for objects that don't include the can-event mixin.

obj.bind(event, handler)

Add a basic event listener to an object.

This is an alias of addEventListener.

canEvent.bind.call(obj, event, handler)

This syntax can be used for objects that don't include the can-event mixin.

obj.unbind(event, handler)

Removes a basic event listener from an object.

This is an alias of removeEventListener.

canEvent.unbind.call(obj, event, handler)

This syntax can be used for objects that don't include the can-event mixin.

obj.delegate(selector, event, handler)

Provides a compatibility layer for adding delegate event listeners. This doesn't actually implement delegates, but rather allows logic that assumes a delegate to still function.

Therefore, this is essentially an alias of addEventListener with the selector ignored.

  1. selector {String}: The ignored selector to use for the delegate.
  2. event {String}: The name of the event to listen for.
  3. handler {function}: The handler that will be executed to handle the event.
  • returns {Object}: this

canEvent.delegate.call(obj, selector, event, handler)

This syntax can be used for objects that don't include the [can.event] mixin.

obj.undelegate(selector, event, handler)

Provides a compatibility layer for removing delegate event listeners. This doesn't actually implement delegates, but rather allows logic that assumes a delegate to still function.

Therefore, this is essentially an alias of removeEventListener with the selector ignored.

  1. selector {String}: The ignored selector to use for the delegate.
  2. event {String}: The name of the event to listen for.
  3. handler {function}: The handler that will be executed to handle the event.
  • returns {Object}: this

canEvent.undelegate.call(obj, selector, event, handler)

This syntax can be used for objects that don't include the can-event mixin.

Contributing

Making a Build

To make a build of the distributables into dist/ in the cloned repository run

npm install
node build

Running the tests

Tests can run in the browser by opening a webserver and visiting the test.html page. Automated tests that run the tests from the command line in Firefox can be run with

npm test