WebKit DOM Programming Topics: 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-1**WebKit 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.

image: ../art/force_touch_progression_1_2x.png

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

function prepareForForceClick(event)
{
// Cancel the system's default behavior
event.preventDefault()
// Perform any other operations in preparation for a force click
}
function enterForceClick(event)
{
// Perform operations in response to entering force click
}
function endForceClick(event)
{
// Perform operations in response to exiting force click
}
function forceChanged(event)
{
// Perform operations in response to changes in force
}
function setupForceClickBehavior(someElement)
{
// Attach event listeners in preparation for responding to force clicks
someElement.addEventListener("webkitmouseforcewillbegin", prepareForForceClick, false);
someElement.addEventListener("webkitmouseforcedown", enterForceClick, false);
someElement.addEventListener("webkitmouseforceup", endForceClick, false);
someElement.addEventListener("webkitmouseforcechanged", forceChanged, false);
}

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-2**Levels 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

function getEventData(event)
{
// Check to see if the event has a force property
if ("webkitForce" in event)
{
// Retrieve the force level
var forceLevel = event["webkitForce"];
// Retrieve the force thresholds for click and force click
var clickForce = MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN;
var forceClickForce = MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN;
// Check for force level within the range of a normal click
if (forceLevel >= clickForce && forceLevel < forceClickForce)
// Perform operations in response to a normal click
// Check for force level within the range of a force click
} else if (forceLevel >= forceClickForce) {
// Perform operations in response to a force click
}
}
}

Other Resources

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