search

fljot / Gestouch

Gestouch: multitouch gesture recognition library for Flash (ActionScript) development.
MIT License
358 stars 84 forks source link

readme

h1. Gestouch: multitouch gesture recognition library for Flash (ActionScript) development.

Gestouch is a ActionScript (AS3) library that helps you to deal with single- and multitouch gestures for building better NUI (Natural User Interface).

h3. Why? There's already gesture support in Flash/AIR!

Yes, last versions of Flash Player and AIR runtimes have built-in touch and multitouch support, but the gestures support is very poor: only small set of gestures are supported, they depend on OS, they are not customizable in any way, only one can be processed at the same time and, finally, you are forced to use either raw TouchEvents, or gestures (@see http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/ui/Multitouch.html#inputMode). Upd: With "native way" you also won't get anything out of Stage3D and of custom input like TUIO protocol.

h3. What Gestouch does in short?

Well basically there's 3 distinctive tasks to solve.

To provide various input. It can be native MouseEvents, TouchEvents or more complex things like custom input via TUIO protocol for your hand-made installation. So what we get here is Touches (touch points).

To recognize gesture analyzing touches. Each type of Gesture has it's own inner algorithms that ...

To manage gestures conflicts. As multiple gestures may be recognized simultaneously, we need to be able to control whether it's allowed or some of them should not be recognized (fail).

Gestouch solves these 3 tasks. I was hardly inspired by Apple team, how they solved this (quite recently to my big surprise! I thought they had it right from the beginning) in they Cocoa-touch UIKit framework. Gestouch is very similar in many ways. But I wouldn't call it "direct port" because 1) the whole architecture was implemented based just on conference videos and user documentation 2) flash platform is a different platform with own specialization, needs, etc. So I want Gestouch to go far beyond that.

Features:

h3. Getting Started

All gestures dispatch (if you listen to!) GestureEvent with the next types: GestureEvent.GESTURE_STATE_CHANGE GestureEvent.GESTURE_IDLE GestureEvent.GESTURE_POSSIBLE GestureEvent.GESTURE_FAILED

Discrete gestures also dispatch: GestureEvent.GESTURE_RECOGNIZED

Continuous gestures also dispatch: GestureEvent.GESTURE_BEGAN GestureEvent.GESTURE_CHANGED GestureEvent.GESTURE_ENDED

If you use a good IDE (such as IntelliJ IDEA, FDT, FlashDevelop, Flash Builder) you should see these events in autocompletion.

Quick start:

var doubleTap:TapGesture = new TapGesture(myButton);
doubleTap.numTapsRequired = 2;
doubleTap.addEventListener(GestureEvent.GESTURE_RECOGNIZED, onDoubleTap);
...
private function onDoubleTap(event:GestureEvent):void
{
    // handle double tap!
}

or

var freeTransform:TransformGesture = new TransformGesture(myImage);
freeTransform.addEventListener(GestureEvent.GESTURE_BEGAN, onFreeTransform);
freeTransform.addEventListener(GestureEvent.GESTURE_CHANGED, onFreeTransform);
...
private function onFreeTransform(event:GestureEvent):void
{
    // move, rotate, scale — all at once for better performance!
    trace(freeTransform.offsetX, freeTransform.offsetY, freeTransform.rotation, freeTransform.scale);
}

h3. Advanced usage: Starling, ...

Recent changes made it possible to work with "Starling":http://www.starling-framework.org display list objects as well as any other display list hierarchical structures, e.g. other Stage3D frameworks that have display objects hierarchy like "ND2D":https://github.com/nulldesign/nd2d or even 3D libraries. In order to use Gestouch with Starling all you need to do is a bit of bootstrapping:

starling = new Starling(MyStarlingRootClass, stage);
/* setup & start your Starling instance here */

// Gestouch initialization step 1 of 3:
// Initialize native (default) input adapter. Needed for non-DisplayList usage.
Gestouch.inputAdapter ||= new NativeInputAdapter(stage);

// Gestouch initialization step 2 of 3:
// Register instance of StarlingDisplayListAdapter to be used for objects of type starling.display.DisplayObject.
// What it does: helps to build hierarchy (chain of parents) for any Starling display object and
// acts as a adapter for gesture target to provide strong-typed access to methods like globalToLocal() and contains().
Gestouch.addDisplayListAdapter(starling.display.DisplayObject, new StarlingDisplayListAdapter());

// Gestouch initialization step 3 of 3:
// Initialize and register StarlingTouchHitTester.
// What it does: finds appropriate target for the new touches (uses Starling Stage#hitTest() method)
// What does "-1" mean: priority for this hit-tester. Since Stage3D layer sits behind native DisplayList
// we give it lower priority in the sense of interactivity.
Gestouch.addTouchHitTester(new StarlingTouchHitTester(starling), -1);
// NB! Use Gestouch#removeTouchHitTester() method if you manage multiple Starling instances during
// your application lifetime.

Now you can register gestures as usual:

var tap:TapGesture = new TapGesture(starlingSprite);

h3. Roadmap, TODOs

h3. News

h3. Contribution, Donations

Contribute, share. Found it useful, nothing to add? Hire me for some project.

h3. Links

h2. License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.