#4 doc, demo, tweaks

Author: EddyVerbruggen

README.md

@@ -67,6 +67,29 @@ TapticEngine.impact({
 });
 ```
 
+#### `gestureSelection[start | changed | end]`
+The functions above are great for one-time events, not so much for gestures.
+Say for instance you want to tie this plugin to a range slider, then you can
+'start' the selection first, invoke 'changed' upon changes in the range (there may
+be many during one gesture), then 'end' when the slider changes are done.
+
+Tell the taptic engine that a gesture for a selection change is starting.
+
+```js
+TapticEngine.gestureSelectionStart();
+```
+
+Tell the taptic engine that a selection changed during a gesture.
+
+```js
+TapticEngine.gestureSelectionChanged();
+```
+
+Tell the taptic engine we are done with a gesture. This needs to be called lest resources are not properly recycled.
+
+```js
+TapticEngine.gestureSelectionEnd();
+```
 
 ### Unofficial API (requires at least iPhone 6s)
 __BEWARE__ This uses an undocumented feature which may get your app rejected when reviewed by Apple.
@@ -97,6 +120,7 @@ This triggers the 'Nope' effect you get when fi. force touching a home icon whic
 Codewise this is exactly the same as `weakBoom` and `strongBoom`, except for the function name of course.
 
 ## Changelog
+* 2.1.0  [Max Lynch](https://github.com/mlynch) added `gestureSelection*` methods. See the doc above why those matter!
 * 2.0.1  A crash was fixed for iPhone 7 devices (official API), thanks [Max Lynch](https://github.com/mlynch)!
 * 2.0.0  Added official API for iPhone 7. Moved the old API to `TapticEngine.unofficial.*`. Requires Xcode 8 to build.
 * 1.0.0  Initial release, unofficial API only. Compatible with any Xcode version.

demo/index.html

@@ -12,15 +12,20 @@ <h1>Taptic Engine</h1>
     <p class="event listening">Connecting to Device</p>
     <p class="event received">Device is Ready</p>
 
-    <h3>Unofficial API (iPhone >= 6s)</h3>
+    <h2>Unofficial API (iPhone >= 6s)</h2>
     <button ontouchstart="weakBoom()">weak boom ('Peek')</button><br/><br/>
     <button ontouchstart="strongBoom()">strong boom ('Pop')</button><br/><br/>
     <button ontouchstart="burst()">burst ('Nope!')</button><br/><br/>
 
-    <h3>Official API (iPhone >= 7)</h3>
+    <h2>Official API (iPhone >= 7)</h2>
     <button ontouchstart="notification('error')">notification</button><br/><br/>
     <button ontouchstart="selection()">selection</button><br/><br/>
     <button ontouchstart="impact('heavy')">impact</button><br/><br/>
+
+    <h3>Gesture selection</h3>
+    <button ontouchstart="gestureSelectionStart()">start</button>&nbsp;
+    <button ontouchstart="gestureSelectionChanged()">changes</button>&nbsp;
+    <button ontouchstart="gestureSelectionEnd()">end</button><br/><br/>
   </div>
 </div>
 <script type="text/javascript" src="cordova.js"></script>
@@ -74,6 +79,25 @@ <h3>Official API (iPhone >= 7)</h3>
       }, onSuccess, onError);
     }
   }
+
+  function gestureSelectionStart() {
+    if (window.TapticEngine) {
+      TapticEngine.gestureSelectionStart(onSuccess, onError);
+    }
+  }
+
+  function gestureSelectionChanged() {
+    if (window.TapticEngine) {
+      TapticEngine.gestureSelectionChanged(onSuccess, onError);
+    }
+  }
+
+  function gestureSelectionEnd() {
+    if (window.TapticEngine) {
+      TapticEngine.gestureSelectionEnd(onSuccess, onError);
+    }
+  }
+
 </script>
 </body>
 </html>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordova-plugin-taptic-engine",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Use Apple's Taptic Engine to vibrate your iPhone 6s (or up) in a variety of ways.",
   "cordova": {
     "id": "cordova-plugin-taptic-engine",

plugin.xml

@@ -1,7 +1,7 @@
 <?xml version='1.0' encoding='UTF-8'?>
 <plugin
     id="cordova-plugin-taptic-engine"
-    version="2.0.1"
+    version="2.1.0"
     xmlns="http://apache.org/cordova/ns/plugins/1.0">
 
   <name>Taptic Engine</name>

src/ios/TapticEngine.h

@@ -7,6 +7,10 @@
 - (void) selection:(CDVInvokedUrlCommand*)command;
 - (void) impact:(CDVInvokedUrlCommand*)command;
 
+- (void) gestureSelectionStart:(CDVInvokedUrlCommand*)command;
+- (void) gestureSelectionChanged:(CDVInvokedUrlCommand*)command;
+- (void) gestureSelectionEnd:(CDVInvokedUrlCommand*)command;
+
 // Unofficial API
 - (void) weakBoom:(CDVInvokedUrlCommand*)command;
 - (void) strongBoom:(CDVInvokedUrlCommand*)command;

src/ios/TapticEngine.m

@@ -62,7 +62,7 @@ - (void) selection:(CDVInvokedUrlCommand *)command
  */
 - (void) gestureSelectionStart:(CDVInvokedUrlCommand *)command
 {
-    if(!self.selectionGenerator) {
+    if (!self.selectionGenerator) {
         self.selectionGenerator = [UISelectionFeedbackGenerator new];
         if (self.selectionGenerator == nil || isSimulator) {
             [self.commandDelegate sendPluginResult:[CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Unsupported Operating System"] callbackId:command.callbackId];
@@ -72,7 +72,6 @@ - (void) gestureSelectionStart:(CDVInvokedUrlCommand *)command
 
     [self.selectionGenerator prepare];
 
-
     [self.commandDelegate sendPluginResult:[CDVPluginResult resultWithStatus:CDVCommandStatus_OK] callbackId:command.callbackId];
 }
 
@@ -82,8 +81,8 @@ - (void) gestureSelectionStart:(CDVInvokedUrlCommand *)command
  */
 - (void) gestureSelectionChanged:(CDVInvokedUrlCommand *)command
 {
-    if(!self.selectionGenerator) {
-        [self.commandDelegate sendPluginResult:[CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Unsupported Operating System"] callbackId:command.callbackId];
+    if (!self.selectionGenerator) {
+        [self.commandDelegate sendPluginResult:[CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Invoke gestureSelectionStart first"] callbackId:command.callbackId];
         return;
     }
 

www/TapticEngine.js

@@ -35,9 +35,11 @@ TapticEngine.prototype.impact = function (options, onSuccess, onFail) {
 TapticEngine.prototype.gestureSelectionStart = function (onSuccess, onFail) {
   exec(onSuccess, onFail, "TapticEngine", "gestureSelectionStart", []);
 };
+
 TapticEngine.prototype.gestureSelectionChanged = function (onSuccess, onFail) {
   exec(onSuccess, onFail, "TapticEngine", "gestureSelectionChanged", []);
 };
+
 TapticEngine.prototype.gestureSelectionEnd = function (onSuccess, onFail) {
   exec(onSuccess, onFail, "TapticEngine", "gestureSelectionEnd", []);
 };