eve/README.md

Eve

Tiny event helping JavaScript library.

eve(name, scope, varargs)

Fires event with given name, given scope and other parameters.

Parameters

• name string name of the event, dot (.) or slash (/) separated
• scope object context for the event handlers
• varargs ... the rest of arguments will be sent to event handlers

Returns: object array of returned values from the listeners. Array has two methods .firstDefined() and .lastDefined() to get first or last not undefined value.

eve.listeners(name)

Internal method which gives you array of all event handlers that will be triggered by the given name.

Parameters

• name string name of the event, dot (.) or slash (/) separated

Returns: array array of event handlers

eve.separator(separator)

If for some reasons you don’t like default separators (. or /) you can specify yours here. Be aware that if you pass a string longer than one character it will be treated as a list of characters.

Parameters

• separator string new separator. Empty string resets to default: . or /.

eve.on(name, f, name, f)

Binds given event handler with a given name. You can use wildcards “*” for the names:

eve.on("*.under.*", f);
eve("mouse.under.floor"); // triggers f

Use eve to trigger the listener.

Parameters

• name string name of the event, dot (.) or slash (/) separated, with optional wildcards
• f function event handler function
• name array if you don’t want to use separators, you can use array of strings
• f function event handler function

Returns: function returned function accepts a single numeric parameter that represents z-index of the handler. It is an optional feature and only used when you need to ensure that some subset of handlers will be invoked in a given order, despite of the order of assignment.

Example:

eve.on("mouse", eatIt)(2);
eve.on("mouse", scream);
eve.on("mouse", catchIt)(1);

This will ensure that catchIt function will be called before eatIt.

If you want to put your handler before non-indexed handlers, specify a negative value. Note: I assume most of the time you don’t need to worry about z-index, but it’s nice to have this feature “just in case”.

eve.f(event, varargs)

Returns function that will fire given event with optional arguments. Arguments that will be passed to the result function will be also concated to the list of final arguments.

el.onclick = eve.f("click", 1, 2);
eve.on("click", function (a, b, c) {
    console.log(a, b, c); // 1, 2, [event object]
});

Parameters

• event string event name
• varargs … and any other arguments

Returns: function possible event handler function

eve.stop()

Is used inside an event handler to stop the event, preventing any subsequent listeners from firing.

eve.nt([subname])

Could be used inside event handler to figure out actual name of the event.

Parameters

• subname string subname of the event

Returns: string name of the event, if subname is not specified or

Returns: boolean true, if current event’s name contains subname

eve.nts()

Could be used inside event handler to figure out actual name of the event.

Returns: array names of the event

eve.off(name, f)

Removes given function from the list of event listeners assigned to given name. If no arguments specified all the events will be cleared.

Parameters

• name string name of the event, dot (.) or slash (/) separated, with optional wildcards
• f function event handler function

eve.unbind()

See eve.off

eve.once(name, f)

Binds given event handler with a given name to only run once then unbind itself.

eve.once("login", f);
eve("login"); // triggers f
eve("login"); // no listeners

Use eve to trigger the listener.

Parameters

• name string name of the event, dot (.) or slash (/) separated, with optional wildcards
• f function event handler function

Returns: function same return function as eve.on

eve.version()

Current version of the library.