relativeTouch

Type Event
Revision Release 2024.3703
Keywords touch, relativeTouch
See also MFi Controller (guide)

Overview

When the user interacts with certain touch-sensitive devices, a relative touch event is generated and dispatched. While a normal touch event represents an interaction with the screen or a display object you can physically touch, a relativeTouch event is for devices where touch sensitivity is not related to the display area.

Gotchas

Relative touch events are currently only supported on tvOS as an alternative to using axis events from the InputDevice (Apple TV remote).

Properties

Examples

Function Listener 1
-- Create text object to monitor relative touch
local touchData = display.newText( "-,- []", display.contentCenterX, display.contentCenterY, native.systemFont, 16 )
local tapCounter = display.newText( "0", display.contentCenterX, display.contentCenterY+24, native.systemFont, 16 )

-- Text update function
local function updateText( event )
    touchData.text = event.x .. "," .. event.y .. " [" .. event.phase .. "]"
    if ( event.phase == "ended" ) then
        tapCounter.text = event.tapCount
    end
end

-- Add relative touch runtime listener
Runtime:addEventListener( "relativeTouch", updateText )
Function Listener 2
-- Create a circle
local circle = display.newCircle( display.contentCenterX, display.contentCenterY, 100 )
circle:setFillColor( 0, 1, 0 )

-- Movement data
local moveX = 0
local moveY = 0
local moveScale = 0.05

-- Update movement rates when we get a new relative touch event
local function setCircleMovement( event )
    if ( event.phase == "moved" ) then
        moveX = event.x * moveScale
        moveY = event.y * moveScale
    elseif ( event.phase == "ended" or event.phase == "cancelled" ) then
        moveX = 0
        moveY = 0
        circle.x = display.contentCenterX
        circle.y = display.contentCenterY
    end
end

-- Add relative touch runtime listener
Runtime:addEventListener( "relativeTouch", setCircleMovement )

-- Update the circle's movement based on the last touch's data
local function updateCirclePosition( event )
    circle.x = circle.x + moveX
    circle.y = circle.y + moveY
end
Runtime:addEventListener( "enterFrame", updateCirclePosition )