Usage

Gestouch Framework. Usage

Adding a gesture

The common usage is simple as one line:
GestureClass.add(target, {optional: configuration, properties: here});
this is just a syntax sugar, because internally it does nothing but:

public static function add(target:InteractiveObject, settings:Object = null):GestureClass

{

	return new GestureClass(target, settings);

}

After registering gesture on target, that target (of type flash.display.InteractiveObject) will dispatch gesture events once gesture is detected:

LongPressGesture.add(myButton);

myButton.addEventListener(LongPressGestureEvent.GESTURE_LONG_PRESS, myButton_gestureLongPressHandler);
…
private function myButton_gestureLongPressHandler(event:LongPressGestureEvent):void

{

	// button was held for some time
if (event.phase == GesturePhase.BEGIN)

	{

		// at this point finger/mouse is still down

	}

	else if (event.phase == GesturePhase.END)

	{

		// at this point finger has been released (anywhere on the screen)

	}

}

Customizing gesture

Gestures should be customizable. Default values should be adjust by gesture developer to provide best average user experience.

// press should last at least 200ms and cursor/finger should not be moved more then 0.5 inches

LongPressGesture.add(myButton, {timeThreshold: 200, slop: 0.5 * GestureUtils.IPS_TO_PPMS});

Some gestures (eg: RotateGesture, ZoomGesture) requires exactly 2 touch points. Other can (for existing) and should (for those, which will be written by community later) be customized for any amount of points.

// DragGesture will be calculated around single touch point when we use one finger,

// and around middle (central) point when we use more then one finger.

// Once one finger is release, central point will be recalculated and drag should

// be smoothly continued.

DragGesture.add(myImage, {minTouchPointsCount: 1, maxTouchPointsCount: 3});
// You should double-tap with exactly two fingers.

// maxTouchPointsCount property is automatically set not to be greater then minTouchPointsCount 

DoubleTapGesture.add(myImage, {minTouchPointsCount: 2});

Handling gesture events

Gesture dispatches events through target, so you should addEventListener to target (just like with native gestures). Events are gesture-specific (for loose coupling and clear extention possibility). Event classes extends flash.events.GestureEvent and flash.events.TransformGestureEvent

@see examples for more info.

Cancelling gesture

There can be a situation when you have two gestures and once started, the other one should be terminated(prevented/stopped). For example, LongPressGesture and DragGesture:

longPressGesture = LongPressGesture.add(listItem);

dragGesture = DragGesture.add(list);
// handler for LongPressGesture triggered on list item

private function listItem_gestureLongPressHandler():void

{

	// cancel dragGesture on list to prevent from (possible) scrolling

	// dragGesture is not removed, but just stops processing

	// and won’t fire anymore within this interaction cycle

	dragGesture.cancel();

	someTouchScrollManager.stop();
// do something with listItem, eg highlight or start drag-n-drop reordering

	// …

}

Removing gesture

If you want target to stop dispatching gesture events, you should remove gesture. You should also remove gesture of you want it and target to be GC’ed (Garbage Collected).

swipeGestureInstance = SwipeGesture.add(target);
…
SwipeGesture.remove(target);

// or if you have reference to instance

swipeGestureInstance.dispose();

swipeGestureInstance = null;

Combining gestures

Some gestures could work in parallel without any hassle (@see Free Transform Example from Gestouch Examples project), for others you could need a special conjunction: (TODO: I’m very uncertain about this API… any thoughts?)

// handler for LongPressGesture

private function image_gestureLongPressHandler(event:LongPressGestureEvent):void

{

	if (event.phase == GesturePhase.BEGIN)

	{

		// do some UI change here like highlight/emphasize

		dragGesture = DragGesture.add(image, {slop: 0});

		// start DragGesture at once

		// it’s being populated with TouchPoints from another gesture (longPressGesture)

		dragGesture.continueGesture(longPressGesture);
// this results in DragGesture being registered (like if you would begin touch) at once

		// and so drag will start on next mouse/touch move.

	}

@see Hold-n-Drag Example

Creating a new gesture

Simplest way is to extend Gesture / MovingGestureBase class or implement IGesture interface. Don’t forget to override reflect() method. TODO: more details. @see sources for more info.

Extending GesturesManager

Though I don’t see any point (need) in extending it, you still can do it:

// in the very beginning of your application

GesturesManager.implementation = new MyGesturesManager();
public class MyGesturesManager extends GesturesManager

// or

public class MyGesturesManager implements IGesturesManager

You should check the source code of GesturesManager for more details since it’s quite an advantage use.