User Tools

Site Tools


manual:tutorial_detect_tap

Tutorial: Detecting a Tap Gesture

In this first tutorial, we will introduce several general FingerGestures concepts though an example showing how to detect tap gestures (a quick press → hold → release finger sequence).

First, we'll learn how to use the TapRecognizer component to detect a simple single-finger tap gesture anywhere on the screen. Then, we'll get a bit more fancy and see how to detect a tap on a specific object in the scene. Finally, we will tweak the gesture settings to detect a three-fingers double-tap!

Initial Setup

Step 1

Ensure your scene is setup properly

Step 2

Create a new GameObject called “Gestures”

Step 3

Add the TapRecognizer component to it and keep the default settings. You can search for it in the Project panel or by clicking the Component > FingerGestures > Gestures > Tap menu item.

The TapRecognizer is one of several types of GestureRecognizers. Its role is to monitor the user inputs and fire an event when a valid tap gesture is detected.

Step 4

Create a new C# script called “TapTutorial” and put it on the “Gestures” object we created in step #2

Tapping Anywhere

Let's start by detecting a basic single-finger tap anywhere on the screen.

Step 1

Click the Copy Event To Clipboard button on the TapGestures component. This will copy to the clipboard the proper event signature required by the TapGesture.

Step 2

Paste the content of the clipboard in the new TapTutorial script and edit it to look like this:

public class TapTutorial : MonoBehaviour
{
    void OnTap( TapGesture gesture ) 
    { 
        /* your code here */ 
    }
}

The name of the method, OnTap, matches the Message Name property specified on the TapRecognizer component. When the recognizer will detect a tap gesture, it will broadcast an “OnTap” message to all the other scripts on the “Gestures” object, using Unity's SendMessage API. Since our TapTutorial component is also located on that object, its OnTap method will be invoked by the gesture recognizer.

Note: for performance reasons, it is also possible to use standard .NET delegate-based events instead of the more expansive SendMessage method, but we won't cover that approach in this tutorial..

Step 3

Modify the TapTutorial's OnTap method in the following way:

void OnTap( TapGesture gesture ) 
{
     Debug.Log( "Tap gesture detected at " + gesture.Position + 
            ". It was sent by " + gesture.Recognizer.name );
}

The “gesture” parameter passed to the OnTap method contains the tap gesture event data. In the code above, we log to the console the tap position and the name of the TapRecognizer that fired the event. There are many more useful properties you can access via the gesture parameter, such as the list of fingers involved in the gesture (gesture.Fingers) or what scene object was tapped (gesture.Selection).

Step 4

Test your changes by hitting the Play button in Unity. A debug message should show up in the console whenever you tap the screen

Tapping An Object

Tapping the screen like a madman is fun for a while, but at some point you might want to also interact with objects in your scene.

Step 1

  • Add a new Sphere object to your scene via the GameObject > Create Other > Sphere menu
  • Make sure it has a collider, otherwise it won't be picked up by the TapRecognizer.
  • Set its position to (0, 1, 0)
  • Set its scale to (4, 4, 4)

Step 2

As mentioned previously, the tap gesture event data passed to the OnTap method contains a “Selection” property that references the scene object being tapped. Let's change our previous code to display the name of the object we're tapping on:

void OnTap( TapGesture gesture ) 
{
    if( gesture.Selection )
        Debug.Log( "Tapped object: " + gesture.Selection.name );
    else
        Debug.Log( "No object was tapped at " + gesture.Position );
}

Step 3

Hit the Play button in the editor and test your changes by tapping on the scene background, and then on the sphere.

“What the…?! It's not working!!!”

Indeed, all you should be seeing at this point is the “No object was tapped” message in the console. This is normal: as things are currently setup, the Selection property will only return a null value because the tap gesture recognizer doesn't know how to pick objects yet.

But fear not! Adding this functionality is very painless: simply add a ScreenRaycaster component to our “Gestures” object:

Try to run the scene again: you should now see a “Tapped object: Sphere” message showing up in the console when you tap on the sphere.

The ScreenRaycaster is used by the TapRecognizer to raycast into the scene in search for a valid object to set as its current Selection. On the ScreenRaycaster, you can specify specify various properties such as the ray thickness to simulate a “fat finger” (watch out: this will not work on colliders setup as triggers) or a layer to ignore.

As another side effect of adding the ScreenRaycaster component, the TapRecognizer will now also forward the tap event to the Sphere object when it is tapped. This default behavior can be changed by modifying the value of the Send Message To Selection property on the TapRecognizer.

Let's Detect a Two-Fingers-Triple-Tap!

Sounds crazy and difficult, uh? Wrong!

A few simple tweaks to the TapRecognizer properties will do the trick:

  • Set Required Finger Count to 2
  • Set Required Taps to 3

Hit play to test the changes. You should see the tap message appear in the console after quickly tapping 3 times in a row with two fingers at the same time, on the same location.

Note: if you are testing on desktop, you can simulate the two simultaneous fingers by pressing the left and right mouse buttons at the same time.

Conclusing

In this tutorial, we have introduced the following concepts:

  • Enabling the use of FingerGestures in your scene
  • Using a TapRecognizer to detect a tap gesture
  • Listening and reacting to gesture events broadcast by a GestureRecognizer
  • Using a ScreenRaycaster to add object-picking capabilities to a GesturRecognizer
  • Detecting a gesture performed with multiple fingers

You should be able to apply most of these concepts to the other types of gesture recognizers included in the library.

If you're having any troubles or would like some clarifications, please stop by the support forum and leave your question there!

manual/tutorial_detect_tap.txt · Last modified: 2013/03/17 09:25 by wravaine