Touch Develop retirement postponed until June 22, 2019. Sign-in and access to cloud assets to be removed on May 23, 2018.Learn More..


events

Events are actions that your app can detect and handle, such as user touch input, input from device sensors, and code running in other parts of the app. In TouchDevelop each event runs to completion before the next event starts running, therefore events (and actions) never interleave.
Scripts with events automatically enter an event loop at the end of any user-initiated action. The script appears to continue running, but nothing happens until the event is triggered. To stop the event loop in a script, use the time→stop api.
Events are added in the code by calling an on ... action. For example, we can vibrate the phone when it is shaken.
senses → on shake(handler0)
where handler0() is
phone → vibrate(0.1)
end
end

detaching handlers

If you need to detach a handler, store the binding in a variable and call delete to detach it.
var ev := senses → on shake(handler7)
where handler7() is
...
end
end
We call delete to remove the handler.
ev → delete

inline vs global events

In earlier version of TouchDevelop, events were defined as global actions (see shake event below). These types of events are still available although we recommend using their inline counterparts if possible. Inline events are more easily editable and can be used in libraries.
event
shake
()
...
end event

gameloop

time → on every frame(perform)
where perform() is
do something on every frame
end
end
The time→on every frame event is triggered by a timer approximately every 50 milliseconds. It is typically used to put game logic that triggers regularly, in addition to board→evolve and board→update on wall.

accelerometer and inclinometer

The following events require an accelerometer or inclinometer to be available on the device.

shake

senses → on shake(handler)
where handler() is
...
end
end
The senses→on shake event is triggered when the phone is being shaken. If the accelerometer is not available, the inclinometer or the mouse will be used to emulate this sensor.
  • time→on shake replaces the shake global event.

phone face up

senses → on phone face up(handler2)
where handler2() is
...
end
end
The senses→on phone face up is triggered when the phone changes orientation so that the screen now faces up. Requires an inclinometer.

phone face down

senses → on phone face down(handler3)
where handler3() is
...
end
end
The phone face down is triggered when the phone changes orientation so that the screen now faces down. Requires an inclinometer.

phone portrait

senses → on phone portrait(handler4)
where handler4() is
...
end
end
The phone portrait event is triggered when the phone changes orientation so that its screen is in portrait mode. Requires an accelerometer or an inclinometer.

phone landscape left

senses → on phone landscape left(handler5)
where handler5() is
...
end
end
The phone landscape left event is triggered when the phone changes orientation so that its screen is in landscape left mode, meaning the phone's natural left edge is facing down.

phone landscape right

senses → on phone landscape right(handler6)
where handler6() is
...
end
end
The phone landscape right event is triggered when the phone changes orientation so that its screen is in landscape right mode, meaning the phone's natural right edge is facing down.

board events

The following events are available on any state variable named b (under data) of the board type.
data b : Board

tap board

event
tap board: b
(
x : Number,
y : Number)
do
...
end event
The tap board event is triggered when a tap on that board is registered. The parameters provide the coordinate of the registered tap. The tap is reported when the finger is lifted from the screen. Also, the tap is not reported when one of the following occurs:
  • a sprite is touched at that coordinate and that sprite has an enabled tap event.
  • the tap is a swipe, i.e., the finger moves while touching the screen.
To capture these events, either use the swipe board event, or an event on a [Sprite Set](/Sprite Set).

swipe board

event
swipe board: b
(
x : Number,
y : Number,
delta x : Number,
delta y : Number)
do
...
end event
The swipe board event is triggered when a swipe on that board is registered. The parameters provide the coordinate of the registered swipe and the total delta from the initial touch position to the moment the finger is lifted from the screen. The swipe is reported when the finger is lifted from the screen. Also, the swipe is not reported when one of the following occurs:
  • the delta falls under a small threshold, in which case it is a tap.
  • a sprite is touched at the coordinate of the initial touch and that sprite has a swipe event enabled.
To capture these events, either use the tap board event, or an event on a sprite set.

touch down

event
touch down: b
(
x : Number,
y : Number)
do
...
end event
The touch down event is triggered when a touch is first registered on the board. The parameters provide the coordinate of the registered touch point. The event is reported as soon as the finger touches the board. This event is fired regardless of other enabled events.

touch up

event
touch up: b
(
x : Number,
y : Number)
do
...
end event
The touch up event is triggered when touch is removed from the board. The parameters provide the coordinate of the final touch point. The event is reported as soon as the finger is lifted off the board. This event is fired regardless of other enabled events.

sprite events

The following events are available on any state variable named s (under data) of kind sprite.
data s : Sprite

tap sprite

event
tap sprite: s
(
sprite : Sprite,
x : Number,
y : Number)
do
...
end event
The tap sprite event is triggered when a tap on that sprite is registered. The parameters provide the tapped sprite and the coordinate of the registered tap relative to the board origin containing the sprite. The tap is reported when the finger is lifted from the screen. Also, the tap is not reported when the tap is a swipe, i.e., the finger moves while touching the screen. To capture a swipe, use the swipe sprite event.

swipe sprite

event
swipe sprite: s
(
sprite : Sprite,
x : Number,
y : Number,
delta x : Number,
delta y : Number)
do
...
end event
The swipe sprite in set event is triggered when a swipe on that sprite is registered. The parameters provide the swiped sprite, the initial coordinate of the registered swipe, and the total delta of the swipe. The swipe origin is relative to the board origin containing the sprite. The swipe is reported when the finger is lifted from the screen. Also, the swipe is not reported when the swipe is a tap, i.e., the delta falls under a small threshold. To capture a tap, use the tap sprite event.

Sprite Set events

The following events are available on any state variable named set (under data) of kind Sprite Set.
data set : Sprite Set

tap sprite in set

event
tap sprite in set
(
sprite : Sprite,
index in set : Number,
x : Number,
y : Number)
do
...
end event
The tap sprite in set event is triggered when a tap on a sprite in that sprite set is registered. The parameters provide the tapped sprite, the index of that sprite within the set, and the coordinate of the registered tap relative to the board origin containing the sprite. The tap is reported when the finger is lifted from the screen. Also, the tap is not reported when the tap is a swipe, i.e., the finger moves while touching the screen. To capture a swipe, use the swipe sprite in set event.

swipe sprite in set

event
swipe sprite in set
(
sprite : Sprite,
index in set : Number,
x : Number,
y : Number,
delta x : Number,
delta y : Number)
do
...
end event
The swipe sprite in set event is triggered when a swipe on a sprite in that sprite set is registered. The parameters provide the swiped sprite, the index of that sprite within the set, the initial coordinate of the registered swipe, and the total delta of the swipe. The swipe origin is relative to the board origin containing the sprite. The swipe is reported when the finger is lifted from the screen. Also, the swipe is not reported when the swipe is a tap, i.e., the delta falls under a small threshold. To capture a tap, use the tap sprite in set event.

drag sprite in set

event
drag sprite in set
(
sprite : Sprite,
index in set : Number,
x : Number,
y : Number,
delta x : Number,
delta y : Number)
do
...
end event
The drag sprite in set event is triggered repeatedly while dragging a sprite from that sprite set. The parameters provide the dragged sprite, the index of that sprite within the set, the initial coordinate of the drag, and the total delta of the drag. The drag origin is relative to the board origin containing the sprite. The drag is reported at certain intervals during the dragging, while the finger is still on the screen. Drag events are raised in addition to swipe events.

touch over set

event
touch over set
(
sprite : Sprite,
index in set : Number,
x : Number,
y : Number)
do
...
end event
The touch over set event is triggered when the current touch point overlaps with a sprite in that sprite set. The parameters provide the sprite that is under the current touch point, the index of that sprite within the set, and the coordinate of the registered touch relative to the board origin containing the sprite. The event is reported as soon as the finger swipes into the sprite. It may be reported multiple times.