Class: SC.Event

Defined in: event.js

Since:
SproutCore 1.0

Field Summary

Class Methods

Instance Methods

Field Detail

SC.Event.fire
Alias for trigger() method. This provides a Prototype-like API
hasCustomEventHandling Boolean

Set to YES if you have called either preventDefault() or stopPropagation(). This allows a generic event handler to notice if you want to provide detailed control over how the browser handles the real event.

SC.Event.MOUSE_WHEEL_DELTA_LIMIT Number

This represents the limit in the delta before a different multiplier will be applied. Because we can't generated an accurate mouse wheel event ahead of time, and browsers deliver differing values for mouse wheel deltas, this is necessary to ensure that browsers that scale their values largely are dealt with correctly in the future.

Default value:
1000
SC.Event.MOUSE_WHEEL_MULTIPLIER Number

We need this because some browsers deliver different values for mouse wheel deltas. Once the first mouse wheel event has been run, this value will get set.

Default value:
1
normalized Boolean
Always YES to indicate the event was normalized.
SC.Event.observe
Alias for add() method. This provides a Prototype-like API.
SC.Event.special

This hash contains handlers for special or custom events. You can add your own handlers for custom events here by simply naming the event and including a hash with the following properties:

  • setup: this function should setup the handler or return NO
  • teardown: this function should remove the event listener
SC.Event.stopObserving
Alias for remove() method. This provides a Prototype-like API

Class Method Detail

add(elem, eventType, target, method, context, useCapture)

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.

Parameters:
elem Element
a DOM element, window, or document object
eventType String
the event type you want to respond to
target Object
The target object for a method call or a function.
method Object
optional method or method name if target passed
context Object
optional context to pass to the handler as event.data
useCapture
Returns:
Object
receiver
create(e)

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

Parameters:
e
handle(event)

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.

Parameters:
event
{DOMEvent} the event to handle
Returns:
Boolean
remove(elem, eventType, target, method)

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.

Parameters:
elem Element
a DOM element, window, or document object
eventType String
the event type to remove
target Object
The target object for a method call. Or a function.
method Object
optional name of method
Returns:
Object
receiver
simulateEvent(elem, eventType, attrs)

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.

Parameters:
elem Element
the element the event targets
eventType String
event type. mousedown, mouseup, etc
attrs Hash
optional additional attributes to apply to event.
Returns:
Hash
simulated event object
trigger(elem, eventType, event, donative)

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');
Parameters:
elem
{Element} the target element
eventType
{String} the event type
event
{SC.Event} [event] pre-normalized event to pass to handler
donative
??
Returns:
Boolean
Return value of trigger or undefined if not fired
unload()

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

Instance Method Detail

allowDefault()

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

Returns:
SC.Event
receiver
averagedTouchesForView()

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

Parameters:
SC.View
Returns:
Array
touches an array of SC.Touch objects
commandCodes()

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:
Array
getCharString()
Returns the pressed character as a String.
Returns:
String
preventDefault()

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

Returns:
SC.Event
receiver
stop()

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

Returns:
SC.Event
receiver
stopPropagation()
Implements W3C standard. Prevents further bubbling of the event.
Returns:
SC.Event
receiver
touchesForResponder()
Same as touchesForView, but sounds better for responders.
Parameters:
SC.RootResponder
Returns:
Array
touches an array of SC.Touch objects
touchesForView()
Returns the touches owned by the supplied view.
Parameters:
SC.View
Returns:
Array
touches an array of SC.Touch objects
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)