.watch()

Registers a function to handle events on the selected element(s).

Syntax

neon.watch(string eventname, function callback)

eventname

The name of the event to watch for.

This name should not include the "on" prefix.

callback

The function to be called when the event is triggered. The supplied function will be executed every time the specified event is triggered on the selected element(s).

Requirements

This method should be executed on a selection of elements. Please see the .select() method.

Return value

This method has no return value. It was decided not to make this method chainable to prevent potential confusion, since the method accepts a function that is not executed immediately.

Description

This method provides simple cross-platform event handling. It registers the given callback function as an event handler for each current selected element, for the event named by eventname.

Using the callback function

The callback function will be passed an Event object as its parameter, allowing the function to look up some further information about the event that triggered it. The Event function is implemented to allow for cross-browser development. On all supported browsers, it will have the following properties:

```
function preventDefault()
```
Calling this function will try to prevent the browser executing the default action for this event. For example, if the event is a mouse click on a hyperlink, calling this will prevent the browser taking the normal action for clicking on that hyperlink, which is to load the link.
```
function stopPropagation()
```
Calling this function will stop the event from "bubbling". For most types of events, an event triggered on a particular element will also then be triggered on the parent of that element, and so on, until the event is triggered on the document as a whole. Calling this will prevent the event triggering any further up the document.
```
which
```
For a mouse event, this property will contain 1 for the left mouse button, 2 for the middle mouse button, or 3 for the right mouse button.

For a keyboard event, this property will contain the event's key code or character code. The codes may differ slightly between browsers.
```
pageX, pageY
```
For some events such as mouse events, these properties will contain the coordinates of the mouse cursor, relative to the top left of the current page.

Note: unlike the coordinates returned from the .position() method, this is not relative to the current window, but to the page as a whole.
```
currentTarget
```
A reference to the element on which we were listening to this event.
```
target
```
A reference to the element which originally triggered the event. If the event was originally triggered not on the element you were listening to, but on one of its children or descendents, this will refer to that element.
```
relatedTarget
```
For some event types, this will refer to an element that was related to the event. For example, for the mouseover event, this refers to the element that the mouse has just left. For the focus event, this refers to the element that has just lost focus. This property may sometimes be empty.

The Event object may also have other properties, passed through from the browser's own Event object. These will vary between browsers.

Your callback function may also return a value. If it returns false, this will stop the default browser action for that event, in the same way as calling prevantDefault() on the supplied Event object would.

Cross-browser compatibility

The event subsystem in Neon attempts to provide an interface that can be used across all browsers in much the same way. To that end, many aspects of some browsers are emulated on other browsers.

On browsers which do not support the W3C event registration model, including Internet Explorer 8 and below, many aspects of this model, including its Event object as described above, are emulated.
The mouseenter and mouseleave events, which are traditionally available only on Microsoft browsers, may be used on all browsers. They are emulated on other browsers.
The focusin and focusout events, which are traditionally available only on Microsoft browsers, may be used on all browsers. They are emulated on other browsers.

Follow @neonjs