Class: SC.Touch

SC.Touch Represents a touch. Single touch objects are passed to touchStart, touchEnd and touchCancelled event handlers; a specialized multitouch event object is sent to touchesDragged, which include access to all in-flight touches (see "The touchesDragged Multitouch Event Object" below).

SC.Touch exposes a number of properties, including pageX/Y, clientX/Y, screenX/Y, and startX/Y (the values that pageX/Y had when the touch began, useful for calculating how far the touch has moved). It also exposes the touch's target element at target, its target SC.View at targetView, and the touch's unique identifier at identifier, which may be relied upon to identify a particular touch for the duration of its lifecycle.

A touch object exists for the duration of the touch – literally for as long as your finger is on the screen – and is sent to a number of touch events on your views. Touch events are sent to the touch's current responder, set initially by checking the responder chain for views which implement touchStart (or captureTouch, see "Touch Events" below), and can be passed to other views as needed (see "Touch Responders" below).

Touch Events

You can use the following methods on your views to capture and handle touch events:

• captureTouch -- Sometimes, a touch responder part way up the chain may need to capture the touch and prevent it from being made available to its childViews. The canonical use case for this behavior is SC.ScrollView, which by default captures touches and holds onto them for 150ms to see if the user is scrolling, only passing them on to children if not. (See SC.ScrollView#delaysContentTouches for more.) In order to support this use case, captureTouch bubbles the opposite way as usual: beginning with the target's pane and bubbling down towards the target itself. captureTouch is passed a single instance of SC.Touch, and must return YES if it wishes to capture the touch and become its responder. (If your view doesn't want to immediately capture the touch, but instead wants to suggest itself as a fallback handler in case the child view resigns respondership, it can do so by passing itself to the touch's stackCandidateTouchResponder method.) - touchStart -- When a touch begins, or when a new view responder is first given access to it (see "Touch Responders" below), the touch is passed to this method.
• touchesDragged -- Whenever any touches move, the touchesDragged method is called on the current view responder for any touches that have changed. The method is provided two arguments: a special multitouch event object (see "The touchesDragged Multitouch Event Object" below), and an array containing all of the touches on that view. (This is the same as calling touch.touchesForView(this).)
• touchEnd -- When a touch is complete, its current responder's touchEnd handler is invoked, if present, and passed the touch object which is ending.
• touchCancelled -- This method is generally only called if you have changed the touch's responder. See "Touch Responders" below; in brief, if you pass the touch to another responder via makeTouchResponder, fully resigning your touch respondership, you will receive a touchCancelled call for the next event; if you pass the touch to another responder via stackNextTouchResponder, and never receive it back, you will receive a touchCancelled call when the touch finishes. (Note that because RootResponder must call touchStart to determine if a view will accept respondership, touchStart is called on a new responder before touchCancelled is called on the outgoing one.)

The touchesDragged Multitouch Event Object

The specialized event object sent to touchesDragged includes access to all touches currently in flight. You can access the touches for a specific view from the touchesForView method, or get an average position of the touches on a view from the convenient averagedTouchesForView method. For your convenience when dealing with the common single-touch view, the touchesDragged event object also exposes the positional page, client, screen and start X/Y values from the first touch. If you are interested in handling more than one touch, or in handling an average of in-flight touches, you should ignore these values. (Note that this event object exposes an array of touch events at touches. These are the browser's raw touch events, and should be avoided or used with care.)

Touch Responders: Passing Touches Around

The touch responder is the view which is currently handling events for that touch. A touch may only have one responder at a time, though a view with acceptsMultitouch: YES may respond to more than one touch at a time.

A view becomes a touch responder by implementing touchStart (and not returning NO). (Out-of-order views can capture touch responder status by implementing captureTouch and returning YES.) Once a view is a touch responder, only that view will receive subsequent touchesDragged and touchEnd events; these events do not bubble like mouse events, and they do not automatically switch to other views if the touch moves outside of its initial responder.

In some situations, you will want to pass control on to another view during the course of a touch, for example if it goes over another view. To permanently pass respondership to another view:

if (shouldPassTouch) {
  touch.makeTouchResponder(nextView);
}

This will trigger touchStart on the new responder, and touchCancel on the outgoing one. The new responder will begin receiving touchesDragged events in place of the outgoing one.

If you want to pass respondership to another view, but are likely to want it back – for example, when a ScrollView passes respondership to a child view but expects that the child view will pass it back if it moves more than a certain amount:

if (shouldTemporarlyPassTouch) { touch.stackNextTouchResponder(nextView); }

This will trigger touchStart on the new responder, and it will start receiving touchesDragged and touchEnd events. Note that the previous responder will not receive touchCancelled immediately, since the touch may return to it before the end; instead, it will only receive touchCancelled when the touch is ended.

(If you would like to add a view as a fallback responder without triggering unnecessary calls to its touchStart and touchCancelled events, for example as an alternative to returning YES from captureTouch, you can call stackCandidateTouchResponder instead.)

When the child view decides that the touch has moved enough to be a scroll, it should pass touch respondership back to the scroll view with:

if (Math.abs(touch.pageX - touch.startX) > 4) { touch.restoreLastTouchResponder(); }

This will trigger touchCancelled on the second responder, and the first one will begin receiving touchDragged events again.

Defined in: touch.js

Field Summary

Instance Methods

• allowDefault()
• array(key, val, func)
• averagedTouchesForView(view, addSelf)
• begin(object)
• bool(key, val)
• captureTouch(startingPoint, shouldStack)
• destroy()
• didCreateObject(object, attrs)
• didLoadDesign(designedObject, sourceObject, attrs)
• didLoadLocalization(designedObject, attrs)
• displayBody()
• emit()
• encode(key, val, func)
• end()
• fetch(store, query)
• fetchTargets(store, query)
• fetchTargetsDidComplete(request, opts)
• fetchTests(store, query)
• fetchTestsDidComplete(request, opts)
• find(nameOrUrl)
• hasAcceleratedLayer()
• hash(key, val, func)
• hreflang()
• includeSlices(dataSource, context, slices)
• init()
• js(key, val, transform)
• makeTouchResponder(responder, shouldStack, bubblesTo)
• mouseDown(evt)
• mouseDragged(evt)
• mouseMoved(evt)
• mouseUp(evt)
• number(key, val)
• object(key, val)
• preventDefault()
• render(context, firstTime)
• restoreLastTouchResponder()
• spaces()
• stackCandidateTouchResponder(responder)
• stackNextTouchResponder(view, upChain)
• stop()
• stopPropagation()
• string(key, val)
• toString()
• touchesForResponder(responder)
• touchesForView(view)
• transform(val, func)

//...

// The linked resource (/students/2013/list-copy.xml) will be downloaded
// with the name 'Student List.xml' by default.
fileName: 'Student List.xml',

href: '/students/2013/list-copy.xml'

//...

//...

// The download file name is computed from the linked resource URL.
fileName: function () {
  var href = this.get('href'),
    linkedYear,
    ret;

  if (href) {
    // ex. href == "/reports/2012/annual-report.pdf"
    linkedYear = href.match(/\/(\d*)\//)[1];
    ret = "Annual Report " + linkedYear + '.pdf';
  }

  return ret;
}.property('href').cacheable(),

hrefBinding: SC.Binding.oneWay('MyApp.reportController.hardlink'),

//...

//...

// Whenever anyone downloads this resource, we ping our analytics site.
ping: ['http://tracker.my-app.com/?action="Downloaded PDF Version"'],

//...

//...

// This link is to the author of the article and the result should be loaded in the browser's sidebar if it has one.
rel: ['author', 'sidebar'],

//...

function convert(value, rootObject, key);

var ss = SC.CSSStyleSheet.find('style.css') ;
var ss2 = SC.CSSStyleSheet.find('style') ; // same thing
sc_assert(ss === ss2) ; // SC.CSSStyleSheet objects are stable

touchesDragged: function(evt, viewTouches) {
  if (Math.abs(evt.pageY - evt.startY) > this.MAX_SWIPE) {
    viewTouches.invoke('restoreLastTouchResponder');
  }
}

touchesDragged: function(evt) {
  var myTouches = evt.touchesForView(this);
}