diff --git a/README.textile b/README.textile index 9014360..70152a2 100644 --- a/README.textile +++ b/README.textile @@ -1,6 +1,6 @@ -h1. Gestouch: NUI gestures detection framework for mouse, touch and multitouch AS3 development. +h1. Gestouch: multitouch gesture recognition library for Flash (ActionScript) development. -Gestouch is a ActionScript library/framework that helps you to deal with single- and multitouch gestures for building better NUI (Natural User Interface). +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! @@ -13,9 +13,9 @@ _Upd:_ With "native way" you also won't get anything out of Stage3D and of custo h3. What Gestouch does in short? Well basically there's 3 distinctive tasks to solve. -# To provide various input. It can be standard 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 out of touch points. Each type of Gesture has it's own inner algorithms that ... -# To manage gestures relations. Because they may "overlap" and once some has been recognized probably we don't want other to do so. +# 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. @@ -23,7 +23,7 @@ So I want Gestouch to go far beyond that. Features: * Pretty neat architecture! Very similar to Apple's UIGestureRecognizers (Cocoa-Touch UIKit) -* Works with any display list hierarchy structures: native DisplayList (pure AS3/Flex/your UI framework), Starling or ND2D (Stage3D), and 3D libs... +* Works with any display list hierarchy structures: native DisplayList (pure AS3/Flex/your UI framework), Starling or ND2D (Stage3D) and 3D libs... * Doesn't require any additional software (may use runtime's build-in touch support) * Works across all platforms (where Flash Player or AIR run of course) in exactly same way * Extendable. You can write your own application-specific gestures @@ -70,23 +70,32 @@ private function onFreeTransform(event:TransformGestureEvent):void 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 one 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 detect gestures with Starling do following: +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 do the following: 
starling = new Starling(MyStarlingRootClass, stage);
 /* setup & start your Starling instance here */
 
-var gesturesManager:IGesturesManager = GesturesManager.getInstance();
-// Register instance of StarlingDisplayListAdapter to be used for objects of type starling.display.DisplayObject.
-// What StarlingDisplayListAdapter 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().
-gesturesManager.addDisplayListAdapter(starling.display.DisplayObject, new StarlingDisplayListAdapter());
+// Gestouch initialization step 1 of 3:
+// Initialize native (default) input adapter. Needed for non-DisplayList usage.
+Gestouch.inputAdapter ||= new NativeInputAdapter(stage);
 
-// Initialize and register StarlingInputAdapter.
-// What StarlingInputAdapter does: populates library with touches for Starling "layer" 
-gesturesManager.addInputAdapter(new StarlingInputAdapter(starling));
+// 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 gesture in familiar way: +Now you can register gesture in familiar, exactly same way: 
var tap:TapGesture = new TapGesture(starlingSprite);