Getting Started with dmc-touchmanager

Get quickly up-and-running with dmc-touchmanager.

This module was created because the current implementation of multi-touch in the Corona SDK only lets a single touch (out of many) retain focus on a single display object. So if you set focus from one touch on an object, NO OTHER TOUCHES CAN BE RECEIVED BY THAT OBJECT.

Obviously this behavior won't work if you are writing an application intended to have true multi-touch gestures like pinch or rotate simply because, in these situations, many touches are required to be focused on a single object at the same time.

dmc-touchmanager Basics

Here is a short overview of the Touch Manager

Setup

You import the Touch Manager library like any other using the require()statement.

Import dmc-touchmanager

local TouchMgr = require 'dmc_touchmanager'
The Touch Manager will automatically start multi-touch behavior, so there's no need to call system.activate("multitouch")

API

There are four different API calls to use the Touch Manager, each corresponds to matching calls within Corona SDK.

Note that the following calls to TouchMgr are made using a period ., not a colon :
Touch Manager Corona SDK Notes
TouchMgr.register( obj, handler )
TouchMgr.register( obj, obj2 )
TouchMgr.register( obj )
obj:addEventListener('touch', handler)
obj:addEventListener('touch', obj2)
first is Function listener style
second is Table listener style
TouchMgr.setFocus( obj, event.id ) stage:setFocus(obj, event.id)  
TouchMgr.unsetFocus( obj, event.id ) stage:setFocus(obj, nil) The big difference here is that you must call a different method (unset()) and send in the event.id.
(This is main reason why the Corona multitouch system is broken, you can't unset a particular event.)
TouchMgr.unregister( obj, handler )
TouchMgr.unregister( obj, obj2 )
obj:removeEventListener( 'touch', touchhandler )
obj:removeEventListener( 'touch', obj )
first is Function listener style
second is Table listener style

Reference: http://docs.coronalabs.com/guide/events/detectEvents/index.html#listeners

Event Handlers

Touch-event handlers for dmc-touchmanager should be written just like any other touch handler example you've seen. The Touch Manager works with both Function-type and Table-type touch handlers.

Function Listener

local button = display.newImage("button.png") |

local function listener(event)
    print( event.name.." occurred" )
    return true
end

TouchMgr.register( button, listener )

Table Listener

local button = display.newImage("button.png") |

function button:touch(event)
    print( event.name.." occurred" )
    return true
end

TouchMgr.register( button )

Touch Event

The touch event received by the listener is the same event created by the Corona SDK with the following additions:

Event Property Notes
event.isFocused
(boolean)
When focus is placed on a touch event (to an object) via setFocus(), it is flagged with event.isFocused=true to indicate that it "belongs" to a given display object.

Thus if isFocused is set, the handler receiving the event is the one that is supposed to have it. So make sure that you unsetFocus() in the event phase 'ended'.

event.isFocused

When you specify focus via TouchMgr.setFocus() a "focus flag" is automatically set on the event for you. So there's no need to add one in your code. (This is seen in many Touch Handler examples as self.isFocus.

Simple Function Handler Example

local TouchMgr = require 'dmc_touchmanager'

-- setup our function-type event call
--
local handler = function( event )

    if event.phase == 'began' then

        -- set focus if the object (target) wants to
        -- always receive this event (blocking all others)
        TouchMgr:setFocus( event.target, event.id )

        return true
    end

    if not event.isFocused then return end

    if event.phase == 'moved' then 
        -- handle 'moved' event

    elseif event.phase=='cancelled' or event.phase=='ended' then
        -- handle 'ended'/'cancelled' event

        -- be sure to unset focus
        TouchMgr:unsetFocus( event.target, event.id )

    end

    return true
end

local o = display.newRect( 350, 700, 300, 300 )
o:setFillColor( 1, 1, 1 )

TouchMgr:register( o, handler )