UIControl: touchdown event
The touchdown event fires when a finger presses down on the control. It is the first event of a touch.
Syntax
addEventListener('touchdown', (event) => { })Event object
The event object's type is UIControlTouchEvent. Besides type and target, it carries two read-only fields:
| Field | Type | Meaning |
|---|---|---|
location | CGPoint or null | The finger's position, in this control's own coordinate system, in pt. null when fired by sendActionsForControlEvents() |
tapCount | number | The number of consecutive taps, counted in taps. 0 when fired by sendActionsForControlEvents() |
The callback parameter is declared as Event; to read these two fields, cast it to UIControlTouchEvent, as shown in the example.
It cannot be canceled: cancelable is false, and preventDefault() has no effect.
When it fires
- Fires the moment the finger touches the control, before release. Once per touch.
- Fired by all controls.
- Two taps by the user are two touches, each firing it once (measured: two taps in a row received
touchdowntwice). - Callbacks run after the touch, so
isHighlightedread in the callback may already befalse; see When callbacks run. To change the appearance on press, change it directly in the callback, and restore it intouchupinside,touchupoutside, andtouchcancel. - A disabled control does not fire it. Not verified in the simulator.
Event sequence of a touch
A plain tap (press, no movement, release), measured on a UIControl created directly:
touchdown → touchupinsidePressing, sliding out, then releasing: the first four steps are measured; the last step, touchupoutside, is not verified in the simulator:
touchdown
→ touchdraginside (fires once per finger movement inside)
→ touchdragexit (once)
→ touchdragoutside (fires once per finger movement outside)
→ touchupoutsideSliding out, sliding back in, then releasing: after touchdragoutside come touchdragenter and touchdraginside, and finally touchupinside. Not verified in the simulator.
Examples
const card = new UIControl();
card.backgroundColor = 'systemGreen';
card.addEventListener('touchdown', (e) => {
const { location } = /** @type {UIControlTouchEvent} */ (e);
card.alpha = 0.6;
if (location !== null) {
console.log('Pressed at', location.x, location.y);
}
});
card.addEventListener('touchupinside', () => {
card.alpha = 1;
});Effect: When a finger presses down, card fades and the console prints the finger's coordinates within card. When the finger is lifted inside card, it returns to fully opaque. The opacity change is not verified in the simulator.
Corresponding iOS API
UIControlEventTouchDown. Natively it is registered with addTarget:action:forControlEvents:; here, use addEventListener().
See also
touchupinside,touchupoutside,touchcancel: the three ways a touch ends- Touch location
- When callbacks run