Class: SC.RootResponder

The RootResponder captures events coming from a web browser and routes them to the correct view in the view hierarchy. Usually you do not work with a RootResponder directly. Instead you will work with Pane objects, which register themselves with the RootResponder as needed to receive events.

RootResponder and Platforms

RootResponder contains core functionality common among the different web platforms. You will likely be working with a subclass of RootResponder that implements functionality unique to that platform.

The correct instance of RootResponder is detected at runtime and loaded transparently.

Event Types

RootResponders can route four types of events:

Defined in: root_responder.js

Field Summary

Class Methods

Instance Methods

Field Detail

currentWindowSize Rect
The last known window size.
defaultResponder SC.Object

Set this to a delegate object that can respond to actions as they are sent down the responder chain.

hasFocus

Indicates whether or not the window currently has focus. If you need to do something based on whether or not the window is in focus, you can setup a binding or observer to this property. Note that the SproutCore automatically adds an sc-focus or sc-blur CSS class to the body tag as appropriate. If you only care about changing the appearance of your controls, you should use those classes in your CSS rules instead.

keyPane SC.Pane

The current key pane. This pane receives keyboard events, shortcuts, and actions first, unless a menu is open. This pane is usually the highest ordered pane or the mainPane.

mainPane SC.MainPane

The main pane. This pane receives shortcuts and actions if the focusedPane does not respond to them. There can be only one main pane. You can swap main panes by calling makeMainPane() here.

Usually you will not need to edit the main pane directly. Instead, you should use a MainPane subclass, which will automatically make itself main when you append it to the document.

menuPane SC.MenuPane

The current menu pane. This pane receives keyboard events before all other panes, but tends to be transient, as it is only set when a pane is open.

panes

Contains a list of all panes currently visible on screen. Every time a pane attaches or detaches, it will update itself in this array.

Class Method Detail

ready()

Instance Method Detail

animationend(evt)
Parameters:
evt
animationiteration(evt)
Parameters:
evt
animationstart(evt)
Parameters:
evt
assignTouch(touch, view)
Parameters:
touch
view
attemptKeyEquivalent(evt)

Invoked on a keyDown event that is not handled by any actual value. This will get the key equivalent string and then walk down the keyPane, then the focusedPane, then the mainPane, looking for someone to handle it. Note that this will walk DOWN the view hierarchy, not up it like most.

Parameters:
evt
Returns:
Object
Object that handled evet or null
averagedTouchesForView(view, additionalTouch)

Computes a hash with x, y, and d (distance) properties, containing the average position of all touches, and the average distance of all touches from that average. This is useful for implementing scaling.

This method is also available on SC.Touch objects, and you will usually call it from there.

Parameters:
view SC.View
The view whose touches should be averaged.
additionalTouch SC.Touch
This method uses touchesForView; if you call it from touchStart, that touch will not yet be included in touchesForView. To accommodate this, you should pass the view to this method (or pass YES to SC.Touch#averagedTouchesForView's `addSelf` argument).
beforedeactivate(evt)

IE's default behavior to blur textfields and other controls can only be blocked by returning NO to this event. However we don't want to block its default behavior otherwise textfields won't lose focus by clicking on an empty area as it's expected. If you want to block IE from blurring another control set blockIEDeactivate to true on the specific view in which you want to avoid this. Think of an autocomplete menu, you want to click on the menu but don't loose focus.

Parameters:
evt
blur(evt)

Handle window focus. Change hasFocus and add sc-focus CSS class (removing sc-blur). Also notify panes.

Parameters:
evt
captureTouch(touch, startingPoint, shouldStack)

Before the touchStart event is sent up the usual responder chain, the views along that same responder chain are given the opportunity to capture the touch event, preventing child views (including the target) from hearing about it. This of course proceeds in the opposite direction from a usual event bubbling, starting at the target's first ancestor and proceeding towards the target. This method implements the capture phase.

If no view captures the touch, this method will return NO, and makeTouchResponder is then called for the target, proceeding with standard target-to-pane event bubbling for touchStart.

For an example of captureTouch in action, see SC.ScrollView's touch handling, which by default captures the touch and holds it for 150ms to allow it to determine whether the user is tapping or scrolling.

You will usually not call this method yourself, and if you do, you should call the corresponding convenience method on the touch itself.

Parameters:
touch SC.Touch
The touch to offer up for capture.
startingPoint ?SC.Responder
The view whose children should be given an opportunity to capture the event. (The starting point itself is not asked.)
shouldStack Boolean
Whether any capturing responder should stack with existing responders. Stacked responders are easy to revert via `SC.Touch#restoreLastTouchResponder`.
Returns:
Boolean

Whether or not the touch was captured. If it was not, you should pass it to makeTouchResponder for standard event bubbling.

cleanUpAnimationListeners()

Cleans up the additional animation event listeners.

NOTE: requires that SC.RootResponser.responder.animationstartEventName, SC.RootResponser.responder.animationendEventName and SC.RootResponser.responder.animationiterationEventName have been determined.

Returns:
void
cleanUpTransitionListeners()

Cleans up the additional transition event listeners.

NOTE: requires that SC.RootResponser.responder.transitionendEventName has been determined.

Returns:
void
click(evt)

Certain browsers ignore us overriding mouseup and mousedown events and still allow default behavior (such as navigating away when the user clicks on a link). To block default behavior, we store whether or not the last mouseup or mousedown events resulted in us calling preventDefault() or stopPropagation(), in which case we make the same calls on the click event.

Parameters:
evt Event
the click event
Returns:
Boolean
whether the event should be propagated to the browser
computeWindowSize()
Computes the window size from the DOM.
Returns:
Rect
contextmenu(evt)
Parameters:
evt
dblclick(evt)
Parameters:
evt
drag()
dragDidStart(drag)
Parameters:
drag
focus(evt)

Handle window focus. Change hasFocus and add sc-focus CSS class (removing sc-blur). Also notify panes.

Parameters:
evt
focusin(evt)

Handle window focus event for IE. Listening to the focus event is not reliable as per every focus event you receive you immediately get a blur event (Only on IE of course ;)

Parameters:
evt
focusout(evt)

Handle window blur event for IE. Listening to the focus event is not reliable as per every focus event you receive you immediately get a blur event (Only on IE of course ;)

Parameters:
evt
init()
keyup(evt)
Parameters:
evt
listenFor(keyNames, target, receiver, useCapture)

Default method to add an event listener for the named event. If you simply need to add listeners for a type of event, you can use this method as shorthand. Pass an array of event types to listen for and the element to listen in. A listener will only be added if a handler is actually installed on the RootResponder (or receiver) of the same name.

Parameters:
keyNames Array
target Element
receiver Object
- optional if you don't want 'this'
useCapture Boolean
Returns:
SC.RootResponder
receiver
makeKeyPane(pane)

Makes the passed pane the new key pane. If you pass null or if the pane does not accept key focus, then key focus will transfer to the previous key pane (if it is still attached), and so on down the stack. This will notify both the old pane and the new root View that key focus has changed.

Parameters:
pane SC.Pane
Returns:
SC.RootResponder
receiver
makeMainPane(pane)

Swaps the main pane. If the current main pane is also the key pane, then the new main pane will also be made key view automatically. In addition to simply updating the mainPane property, this method will also notify the panes themselves that they will lose/gain their mainView status.

Note that this method does not actually change the Pane's place in the document body. That will be handled by the Pane itself.

Parameters:
pane SC.Pane
Returns:
SC.RootResponder
makeMenuPane(pane)

Sets a pane as the menu pane. All key events will be directed to this pane, but the current key pane will not lose focus.

Usually you would not call this method directly, but allow instances of SC.MenuPane to manage the menu pane for you. If your pane does need to become menu pane, you should relinquish control by calling this method with a null parameter. Otherwise, key events will always be delivered to that pane.

Parameters:
pane SC.MenuPane
Returns:
SC.RootResponder
receiver
makeTouchResponder(touch, responder, shouldStack, bubblesTo)

This method attempts to change the responder for a particular touch. The touch's responder is the view which will receive touch events for that touch.

You will usually not call this method directly, instead calling one of the convenience methods on the touch itself. See documentation for SC.Touch for more.

Possible gotchas:

  • Because this method must search for a view which implements touchStart (without returning NO), touchStart is called on the new responder before touchCancelled is called on the old one.
  • While a touch exposes its current responder at touchResponder and any previous stacked one at nextTouchResponder, their relationship is ad hoc and arbitrary, and so are not chained by nextResponder like in a standard responder chain. To query the touch's current responder stack (or, though it's not recommended, change it), check touch.touchResponders.
Parameters:
touch SC.Touch
responder SC.Responder
The view to assign to the touch. (It, or if bubbling then an ancestor, must implement touchStart.)
shouldStack Boolean
Whether the new responder should replace the old one, or stack with it. Stacked responders are easy to revert via `SC.Touch#restoreLastTouchResponder`.
bubblesTo Boolean|SC.Responder
If YES, will attempt to find a `touchStart` responder up the responder chain. If NO or undefined, will only check the passed responder. If you pass a responder for this argument, the attempt will bubble until it reaches the passed responder, allowing you to restrict the bubbling to a portion of the responder chain. ((Note that this responder will not be given an opportunity to respond to the event.)
Returns:
Boolean
Whether a valid touch responder was found and assigned.
mousedown(evt)
Parameters:
evt
mousemove(evt)

This will send mouseEntered, mouseExited, mousedDragged and mouseMoved to the views you hover over. To receive these events, you must implement the method. If any subviews implement them and return true, then you won't receive any notices.

If there is a target mouseDown view, then mouse moved events will also trigger calls to mouseDragged.

Parameters:
evt
mouseup(evt)

mouseUp only gets delivered to the view that handled the mouseDown evt. we also handle click and double click notifications through here to ensure consistant delivery. Note that if mouseDownView is not implemented, then no mouseUp event will be sent, but a click will be sent.

Parameters:
evt
mousewheel(evt)
Parameters:
evt
resize()
On window resize, notifies panes of the change.
Returns:
Boolean
selectstart(evt)
Parameters:
evt
sendAction(action, target, sender, pane, context, firstResponder)

Route an action message to the appropriate responder. This method will walk the responder chain, attempting to find a responder that implements the action name you pass to this method. Set 'target' to null to search the responder chain. IMPORTANT*: This method's API and implementation will likely change significantly after SproutCore 1.0 to match the version found in SC.ResponderContext.

You generally should not call or override this method in your own applications.

Parameters:
action String
The action to perform - this is a method name.
target SC.Responder
object to set method to (can be null)
sender Object
The sender of the action
pane SC.Pane
optional pane to start search with
context Object
optional. only passed to ResponderContexts
firstResponder
Returns:
Boolean
YES if action was performed, NO otherwise
sendEvent(action, evt, target)

Attempts to send an event down the responder chain. This method will invoke the sendEvent() method on either the keyPane or on the pane owning the target view you pass in. It will also automatically begin and end a new run loop.

If you want to trap additional events, you should use this method to send the event down the responder chain.

Parameters:
action String
evt SC.Event
target Object
Returns:
Object
object that handled the event or null if not handled
setup()

Called when the document is ready to begin handling events. Setup event listeners in this method that you are interested in observing for your particular platform. Be sure to call sc_super().

Returns:
void
targetForAction(target, method, sender, optional, a)

Attempts to determine the initial target for a given action/target/sender tuple. This is the method used by sendAction() to try to determine the correct target starting point for an action before trickling up the responder chain.

You send actions for user interface events and for menu actions.

This method returns an object if a starting target was found or null if no object could be found that responds to the target action.

Passing an explicit target or pane constrains the target lookup to just them; the defaultResponder and other panes are not searched.

Parameters:
target Object|String
or null if no target is specified
method String
name for target
sender Object
optional sender
optional SC.Pane
pane
a firstResponder
first responder to use
Returns:
Object
target object or null if none found
targetViewForEvent(evt)

Finds the view that appears to be targeted by the passed event. This only works on events with a valid target property.

Parameters:
evt SC.Event
Returns:
SC.View
view instance or null
touchend(evt)
Parameters:
evt
touchesForView(view)

Returns the touches that are registered to the specified view or responder; undefined if none.

When views receive a touch event, they have the option to subscribe to it. They are then mapped to touch events and vice-versa. This returns touches mapped to the view.

This method is also available on SC.Touch objects, and you will usually call it from there.

Parameters:
view
transitionend(evt)
Parameters:
evt
unassignTouch(touch)
Parameters:
touch
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)