Documentation Archive

Developer

WebKit DOM Programming Topics

On This Page

Responding to Force Touch Events

Safari, Dashboard, and WebKit-based applications include support for responding to Force Touch events from within HTML pages. You can use these events to provide custom behaviors in response to actions such as force clicks and changes in pressure. For example, your webpage might open a link in a new window when the user force clicks the link, or play an embedded video faster as the user presses harder.

JavaScript Force Touch Operations

Mouse events occur when the user performs an action with a mouse or trackpad, such as pressing down (mousedown) or releasing (mouseup). Force Touch events complement mouse events and occur when pressure changes on a Force Touch trackpad. Trackpads without Force Touch capability provide a webkitForce click value that is equivalent to MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN on mousedown, mouseup, and click events.

Force Touch Events

The DOM supports the following Force Touch events.

Table 5-1WebKit DOM Force Touch events

Event name

Description

webkitmouseforcewillbegin

This event occurs immediately before the mousedown event. It allows you to prevent the default system behavior, such as displaying a dictionary window when force clicking on a word, in order to perform a custom action instead. To prevent the default system behavior, call the preventDefault() method on the event.

webkitmouseforcedown

This event occurs after the mousedown event, once enough force has been applied to register as a force click. The user receives haptic feedback representing the force click when this event occurs.

webkitmouseforceup

This event occurs after a webkitmouseforcedown event, once enough force has been released to exit the force click operation. The user receives haptic feedback representing the exit from force click when this event occurs.

webkitmouseforcechanged

This event occurs whenever a change in trackpad force is detected between the mousedown and mouseup events.

Force Touch Event Progression

The progression of Force Touch events is as follows. Figure 5-1 shows the progression of events when the user applies enough force to perform a normal click. Figure 5-2 shows the progression of events when the user applies enough force to perform a force click.

Figure 5-1Force Touch events during a normal click image: ../art/force_touch_progression_1_2x.png
Figure 5-2Force Touch events during a force click image: ../art/force_touch_progression_2_2x.png

Listening for Force Touch Events

To listen for Force Touch events, call the addEventListener() method on an element. Pass it the name of the event to listen for, the name of a function to call when the event occurs, and a boolean indicating whether to perform the event at bubbling (false) or capturing (true). See Listing 5-1.

Listing 5-1Listening for and responding to Force Touch events
  1. function prepareForForceClick(event)
  2. {
  3. // Cancel the system's default behavior
  4. event.preventDefault()
  5. // Perform any other operations in preparation for a force click
  6. }
  7. function enterForceClick(event)
  8. {
  9. // Perform operations in response to entering force click
  10. }
  11. function endForceClick(event)
  12. {
  13. // Perform operations in response to exiting force click
  14. }
  15. function forceChanged(event)
  16. {
  17. // Perform operations in response to changes in force
  18. }
  19. function setupForceClickBehavior(someElement)
  20. {
  21. // Attach event listeners in preparation for responding to force clicks
  22. someElement.addEventListener("webkitmouseforcewillbegin", prepareForForceClick, false);
  23. someElement.addEventListener("webkitmouseforcedown", enterForceClick, false);
  24. someElement.addEventListener("webkitmouseforceup", endForceClick, false);
  25. someElement.addEventListener("webkitmouseforcechanged", forceChanged, false);
  26. }

Gauging Levels of Force

The webkitmouseforcechanged event occurs when force changes between mousedown and mouseup events. However, you can determine the level of force at any time from any mouse event—including mousedown, mousemove, and mouseup—by checking the webkitForce property of the event. Compare this number value against the mouse event constants MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN and MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN to determine whether the user has entered or is nearing a regular click or force click, as shown in Table 5-2 and Listing 5-2.

Table 5-2Levels of force

Force level

Description

MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN

Represents the amount of force required to perform a regular click.

MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN

Represents the force required to perform a force click.

Listing 5-2Retrieving the force value of a Force Touch event
  1. function getEventData(event)
  2. {
  3. // Check to see if the event has a force property
  4. if ("webkitForce" in event)
  5. {
  6. // Retrieve the force level
  7. var forceLevel = event["webkitForce"];
  8. // Retrieve the force thresholds for click and force click
  9. var clickForce = MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN;
  10. var forceClickForce = MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN;
  11. // Check for force level within the range of a normal click
  12. if (forceLevel >= clickForce && forceLevel < forceClickForce)
  13. // Perform operations in response to a normal click
  14. // Check for force level within the range of a force click
  15. } else if (forceLevel >= forceClickForce) {
  16. // Perform operations in response to a force click
  17. }
  18. }
  19. }

Other Resources

See WWDC 2015: What's New in Web Development in WebKit and Safari.