Event.define()

Define an event...

Syntax

// Basic definition
Event.define(shortName[, context]);
 
// Setting default parameters
Event.define(shortName[, context])(params...);

Parameters

Parameter

Type

Mandatory

Notes

API Version

shortName

String

The short name of the event to define.

For example, "myEvent".

0.1

context

Object

The context to which the event listener will be added.

Default: global

0.1

params...

List of Variant

Optionally specify default parameter values for future invocations of the event listener.

If called without any parameters, any existing defaults will be removed.

0.1

Return values

Value	Type	Notes	API Version
<function>	Function	A function which if called will use store its arguments and use them as default values for future invocations of the event.	0.1
<error>	Error	The shortName specified was a reserved keyword (eg. you can't define an event called "define" because that's a method of the Event object).	0.1

Notes

All standard JS API Events are automatically defined by the Events API.

If the event is already defined, defining it again won't change anything other than the default parameters (if specified).

When an event is defined, an accessor property is added to the specified context (defaults to global scope). The accessor will return undefined if there are no handlers attached to the event. To enable the event, either set the property to a function (multiple handlers can be defined by setting the property multiple times) or use Event.enable().

Examples

Basic usage...

// define a custom event
Event.define("myEvent");
 
// add a handler function to it (note case sensitivity)
function eventMyEvent(str) {
	console(str);
}
 
// trigger it
eventMyEvent("hello world"); // "hello world" sent to console

Specifying default parameters...

// define a custom event with default parameter
Event.define("myEvent")("hello world");
 
// add a handler function to it (note case sensitivity)
function eventMyEvent(str) {
	console(str);
}
 
// trigger it
eventMyEvent(); // "hello world" sent to console
eventMyEvent("foo"); // "foo" sent to console
 
// remove defaults
Event.define("myEvent")();
eventMyEvent(); // "undefined" sent to console

Custom context...

var foo = {};
 
// define a custom event on 'foo' object
Event.define("myEvent", foo);
 
// add a handler function to it (note case sensitivity)
foo.eventMyEvent = function(str) {
	console(str);
}
 
// trigger it
eventMyEvent("hello world"); // ReferenceError - not defined on global object
foo.eventMyEvent("hello world"); // "hello world" sent to console