StageObject:setFocus()

Type Function
Object StageObject
Library display.*
Return value none
Revision Release 2024.3703
Keywords setFocus, focus, touch focus
See also touch
display.getCurrentStage()
display.currentStage
Tap/Touch/Multitouch (guide)

Overview

Sets a specific display object as the target for all future touch events. Pass nil to restore default behavior for touch event dispatches.

Note

The global StageObject can be retrieved at any time via display.getCurrentStage() or display.currentStage.

Multitouch

When calling this method while multitouch is enabled via system.activate(), the optional parameter touchID means that the specified touch has focus on that object, but other touches do not. Using this command, it is possible to create an object that will "own" the first touch it receives for the lifetime of that touch, and for multiple objects to obtain their own focused touches at the same time. Under this same scheme, if you need to release touch focus on a specific object, call this command with reference to the object and pass nil for touchID.

See the examples below for usage details, along with the Tap/Touch/Multitouch guide.

Syntax

StageObject:setFocus( displayObject [, touchID] )
displayObject (required)

DisplayObject. Reference to a display object to set focus on.

touchID (optional)

Userdata. The touch ID passed to the touch event for the touched object. This only applies when multitouch is enabled via system.activate().

Examples

Multitouch Enabled
-- Activate multitouch
system.activate( "multitouch" )

-- Create two display objects on the screen
local newRect1 = display.newRect( display.contentCenterX, 160, 60, 60 )
newRect1:setFillColor( 1, 0, 0.3 )
local newRect2 = display.newRect( display.contentCenterX, 320, 60, 60 )
newRect2:setFillColor( 0.3, 0, 1 )

-- Touch event listener
local function touchListener( event )

    print( "Unique touch ID: " .. tostring(event.id) )

    if ( event.phase == "began" ) then
        event.target.alpha = 0.5
        -- Set focus on object using unique touch ID
        display.getCurrentStage():setFocus( event.target, event.id )

    elseif ( event.phase == "ended" or event.phase == "cancelled" ) then
        event.target.alpha = 1
        -- Release focus on object
        display.getCurrentStage():setFocus( event.target, nil )
    end
    return true
end

-- Add a touch listener to each object
newRect1:addEventListener( "touch", touchListener )
newRect2:addEventListener( "touch", touchListener )
Multitouch Disabled
-- Create two display objects on the screen
local newRect1 = display.newRect( display.contentCenterX, 160, 60, 60 )
newRect1:setFillColor( 1, 0, 0.3 )
local newRect2 = display.newRect( display.contentCenterX, 320, 60, 60 )
newRect2:setFillColor( 0.3, 0, 1 )

-- Touch event listener
local function touchListener( event )

    if ( event.phase == "began" ) then
        event.target.alpha = 0.5
        -- Set focus on object
        display.getCurrentStage():setFocus( event.target )

    elseif ( event.phase == "ended" or event.phase == "cancelled" ) then
        event.target.alpha = 1
        -- Release focus on object
        display.getCurrentStage():setFocus( nil )
    end
    return true
end

-- Add a touch listener to each object
newRect1:addEventListener( "touch", touchListener )
newRect2:addEventListener( "touch", touchListener )