stage:setFocus( )

Description:

Sets displayObject as the target for all future hit events. Pass nil to restore default behavior for hit event dispatches. This is typically used to implement buttons that change appearance when a user initially presses them.

When calling this method when multitouch is enabled (system.active) with the optional parameter (touchID) means that the specified touch has focus on that object, but other touches do not. Using this API, it is possible to create an object that will "own" the first touch it gets, for the lifetime of that touch, and for multiple objects to obtain their own focused touches at the same time. See the "Interface/DragMeMultitouch" sample code for a demonstration of this behavior.

With multitouch enabled, focus will be on a per-object basis. To turn off focus, you must specify the object and pass nil for the touchID.

Syntax:

display.getCurrentStage():setFocus(displayObject [,touchID])

Example:

This example creates a button (rectangle) whose alpha/transparency is reduced when the user touches the button, and returned to its initial alpha when the user ends the touch operation, even if their finger is outside the button's bounds.

local button = display.newRect( 50, 50, 100, 50 )
 
function doTouch( event )
 
    if event.phase == "began" then      
        print("began phase")
        event.target.alpha = 0.5
        display.getCurrentStage():setFocus(event.target)
    elseif event.phase == "ended" or event.phase == "cancelled" then
        event.target.alpha = 1
        print("end phase")
        display.getCurrentStage():setFocus(nil)
    end
    
end
 
button:addEventListener("touch", doTouch)

Parameters:

displayObject
object: Name of an object.

touchID
Userdata: The touch ID passed to the touch event for the touched object (when Multitouch is enabled).

Returns:

Nothing.

Remarks:

Note: When multitouch is not enabled (the default state), stage:setFocus() works as follows:

stage:setFocus( obj, nil ) behaves like stage:setFocus( nil )

stage:setFocus( obj, touchID ) behaves like stage:setFocus( obj )

As a result, library code that supports multitouch (e.g., ui.lua) will work as expected in both multitouch and non-multitouch modes.

Supported on operating systems and platforms for build numbers shown:
  • Mac OS X:
    Corona SDK 1.0
  • Windows:
    Corona SDK 2.0
  • iOS:
    Corona SDK 1.0
  • Android:
    Corona SDK 2.0

Replies

weihua44
User offline. Last seen 7 years 12 weeks ago. Offline
Joined: 7 Feb 2011

I setfocus on one event.id by

display.getCurrentStage():setFocus( self, event.id )

If I want to unfocus it,

Does

display.getCurrentStage():setFocus( nil, event.id )
and
display.getCurrentStage():setFocus( self, nil )

do the same work?

I tested them, it seems that they all work fine.
Are I toughs right?

Tom
User offline. Last seen 4 years 3 weeks ago. Offline
Joined: 13 Jul 2010

The answer depends if Multitouch is enabled: system.activate( "multitouch"). If it's not enabled (the default state), the touchId is not used and both calls will remove the focus. If enabled, you need to call SetFocus with the object.

I'll update the API page to reflect this.

Thanks,
Tom

weihua44
User offline. Last seen 7 years 12 weeks ago. Offline
Joined: 7 Feb 2011

Thanks Tom.

Just to confirm,

So if multi-touch is enabled

I should use
display.getCurrentStage():setFocus( self, nil )

to remove the focus, right?

Tom
User offline. Last seen 4 years 3 weeks ago. Offline
Joined: 13 Jul 2010

That's correct. Just make sure that "self" is a reference to the object and not "nil".