Skip to content

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:

FieldTypeMeaning
locationCGPoint or nullThe finger's position, in this control's own coordinate system, in pt. null when fired by sendActionsForControlEvents()
tapCountnumberThe 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 touchdown twice).
  • Callbacks run after the touch, so isHighlighted read in the callback may already be false; see When callbacks run. To change the appearance on press, change it directly in the callback, and restore it in touchupinside, touchupoutside, and touchcancel.
  • 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 → touchupinside

Pressing, 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)
→ touchupoutside

Sliding out, sliding back in, then releasing: after touchdragoutside come touchdragenter and touchdraginside, and finally touchupinside. Not verified in the simulator.

Examples ​

js
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 ​