Bind an event to an element.

This method will cause the passed handler to be executed whenever a relevant event occurs on the named element. This method supports a variety of handler types, depending on the kind of support you need.

Simple Function Handlers

SC.Event.add(anElement, "click", myClickHandler) ;

The most basic type of handler you can pass is a function. This function will be executed every time an event of the type you specify occurs on the named element. You can optionally pass an additional context object which will be included on the event in the event.data property.

When your handler function is called, the function's "this" property will point to the element the event occurred on.

The click handler for this method must have a method signature like:

function(event) { return YES|NO; }

Method Invocations

SC.Event.add(anElement, "click", myObject, myObject.aMethod) ;

Optionally you can specify a target object and a method on the object to be invoked when the event occurs. This will invoke the method function with the target object you pass as "this". The method should have a signature like:

function(event, targetElement) { return YES|NO; }

Like function handlers, you can pass an additional context data paramater that will be included on the event in the event.data property.

Handler Return Values

Both handler functions should return YES if you want the event to continue to propagate and NO if you want it to stop. Returning NO will both stop bubbling of the event and will prevent any default action taken by the browser. You can also control these two behaviors separately by calling the stopPropagation() or preventDefault() methods on the event itself, returning YES from your method.

Limitations

Although SproutCore's event implementation is based on jQuery, it is much simpler in design. Notably, it does not support namespaced events and you can only pass a single type at a time.

If you need more advanced event handling, consider the SC.ClassicResponder functionality provided by SproutCore or use your favorite DOM library.

Standard method to create a new event. Pass the native browser event you wish to wrap if needed.

This method will handle the passed event, finding any registered listeners and executing them. If you have an event you want handled, you can manually invoke this method. This function expects it's "this" value to be the element the event occurred on, so you should always call this method like:

SC.Event.handle.call(element, event) ;

Note that like other parts of this library, the handle function does not support namespaces.

Removes a specific handler or all handlers for an event or event+type.

To remove a specific handler, you must pass in the same function or the same target and method as you passed into SC.Event.add(). See that method for full documentation on the parameters you can pass in.

If you omit a specific handler but provide both an element and eventType, then all handlers for that element will be removed. If you provide only and element, then all handlers for all events on that element will be removed.

Limitations

Although SproutCore's event implementation is based on jQuery, it is much simpler in design. Notably, it does not support namespaced events and you can only pass a single type at a time.

If you need more advanced event handling, consider the SC.ClassicResponder functionality provided by SproutCore or use your favorite DOM library.

Generates a simulated event object. This is mostly useful for unit testing. You can pass the return value of this property into the trigger() method to actually send the event.

Trigger an event execution immediately. You can use this method to simulate arbitrary events on arbitrary elements.

Limitations

Note that although this is based on the jQuery implementation, it is much simpler. Notably namespaced events are not supported and you cannot trigger events globally.

If you need more advanced event handling, consider the SC.Responder functionality provided by SproutCore or use your favorite DOM library.

Example

SC.Event.trigger(view.get('layer'), 'mousedown');

This method is called just before the window unloads to unhook all registered events.

Indicates that you want to allow the normal default behavior. Sets the hasCustomEventHandling property to YES but does not cancel the event.

Returns average data--x, y, and d (distance)--for the touches owned by the supplied view.

Returns characters with command codes for the event.

The first value is a normalized command code identifying the modifier keys that are pressed in combination with a character key. Command codes can be used to map key combinations to an action in the application. A basic example of a normalized command code would be ctrl_x, which corresponds to the combination of the command key with the x key being pressed on OS X or the ctrl key with the x key in Windows.

The second value is the character string by itself. So for ctrl_x, this would be simply x. However, for alt_x it would be ≈ and for alt_shift_x, it would be ˛.

Considerations for Different OS's

At this time, the meta (command) key in OS X is mapped to the ctrl_ command code prefix. This means that on OS X, command + s, and on Windows, ctrl + s, both become the same command code, ctrl_s.

Note that the order of command code prefixes is important and goes in the order: ctrl_, alt_, shift_. The following are examples of command codes: ctrl_x alt_x ctrl_shift_x ctrl_alt_shift_x alt_shift_x

Returns the pressed character as a String.

Implements W3C standard. Will prevent the browser from performing its default action on this event.

Stops both the default action and further propagation. This is more convenient than calling both.

Implements W3C standard. Prevents further bubbling of the event.

Same as touchesForView, but sounds better for responders.

Returns the touches owned by the supplied view.