Nanogest iOS Objective-C API

Installation in Xcode

Add Nanogest.framework to your project

Nanogest.framework is a static framework for Xcode. It contains a static library for iOS, and the corresponding header files.

Platform compatibility

Nanogest is compatible with iOS 8.0+. Nanogest requires an iOS device with a front-facing camera, (iPhone 4s+, iPad 2+, iPad mini+, iPod Touch 5th generation and newer).

Nanogest is a universal library that can be used on all architectures supported by iOS (armv6, armv7, armv7s, arm64, and x86_64 in the simulator).

However, all the iOS devices supporting only armv6 also lack a front-facing camera. Therefore, Nanogest is implemented as a no-op on armv6 and x86_64.

In other words, Nanogest can be compiled into a universal application for arm64, armv7s, armv7 and armv6 devices, but it will be disabled on armv6 (no code change required on your end).

Synopsis

Example code in this documentation assumes that automatic reference counting (ARC) is enabled. If ARC is not used, manual reference counting must be added to the examples in this documentation. The API itself is compatible both with code using ARC and with code using manual reference counting.

#import "Nanogest/NanogestIOS.h" @interface YourViewController : UIViewController < NanogestGestureDelegate > @property Nanogest *ngest; @end @implementation YourViewController - (id)init { self = [super init]; if (self != nil) { self.ngest = [[Nanogest alloc] init]; self.ngest.gestureDelegate = self; [self.ngest start]; } return self; } - (void)viewWillTransitionToSize:(CGSize)size withTransitionCoordinator:(id<UIViewControllerTransitionCoordinator>)coordinator { [super viewWillTransitionToSize:size withTransitionCoordinator:coordinator]; [self.ngest viewWillTransitionToSize:size withTransitionCoordinator:coordinator]; } - (void)onGesture:(NanogestKind)gesture timestamp:(NSTimeInterval)timestamp { switch (gesture) { case NANOGEST_SWIPE_LEFT: [self onLeft]; break; case NANOGEST_SWIPE_RIGHT: [self onRight]; break; case NANOGEST_SWIPE_UP: [self onUp]; break; case NANOGEST_SWIPE_DOWN: [self onDown]; break; } } @end

API

NanogestKind Enum

The NanogestKind enum identifies each gesture recognized by Nanogest.

enum nanogest_kind { NANOGEST_NONE = 0, NANOGEST_SWIPE_LEFT = 1, NANOGEST_SWIPE_RIGHT = 2, NANOGEST_SWIPE_UP = 3, NANOGEST_SWIPE_DOWN = 4, NANOGEST_HELLO = 5, }; typedef enum nanogest_kind NanogestKind;

The gestures are always to be understood with respect to the user. Nanogest takes into account the current orientation of the device automatically.

NanogestGestureDelegate Protocol

The method declared by the NanogestGestureDelegate protocol allows the adopting delegate to respond to hand gestures detected by the Nanogest class.

- (void) onGesture:(NanogestKind)gesture timestamp:(NSTimeInterval)timestamp;

Tells the delegate that the user performed a hand gesture. Called on the main thread.

gesture is the kind of gesture detected. timestamp is the the date at which the gesture was detected, in seconds since the reference date (January 1st, 2001, GMT).

Forwarding viewWillTransitionToSize to Nanogest

Nanogest needs to be told when the UI of the application rotates, as gestures are represented with respect to the current orientation of the UI (that is, NANOGEST_SWIPE_LEFT means the gesture was to the left of the user interface displayed on the screen).

Your UIViewController or UIPresentationController must implement viewWillTransitionToSize:withTransitionCoordinator: from the UIContentContainer protocol (see Apple iOS documentation ).

In your implementation, you must call the same method with the same parameters on both super and your Nanogest instance:

- (void)viewWillTransitionToSize:(CGSize)size withTransitionCoordinator:(id)coordinator { [super viewWillTransitionToSize:size withTransitionCoordinator:coordinator]; [self.ngest viewWillTransitionToSize:size withTransitionCoordinator:coordinator]; }

NanogestError Enum

The NanogestError enum identifies the errors that may be generated by Nanogest.

enum nanogest_error { NANOGEST_OK = 0, NANOGEST_ERROR_ALLOC = 1, NANOGEST_ERROR_INVALID_ARGUMENT = 2, NANOGEST_ERROR_OS = 3, NANOGEST_ERROR_DISABLED = 4, NANOGEST_ERROR_UNKNOWN = 5, }; typedef enum nanogest_error NanogestError;

NanogestErrorDelegate Protocol

The method declared by the NanogestErrorDelegate protocol allows the adopting delegate to respond to errors generated by the Nanogest class.

- (void) onError:(NanogestError)code codeName:(NSString *)codeName message:(NSString *)message;

Tells the delegate that an error was detected by the class Nanogest. Called on the main thread.

code is the error code. codeName is the string naming the error code (e.g. the string "NANOGEST_ERROR_ALLOC" for the error code NANOGEST_ERROR_ALLOC). message is a string describing the error.

On error, the Nanogest instance is disabled. When possible, stop is called. Any further interaction with the disabled Nanogest instance will be ignored.

To recover from an error, a new Nanogest instance should be created and started. When using manual reference counting, release the old, disabled instance.

NanogestConfigBits Enum

The NanogestConfigBits enum identifies the configuration options in the config bitmask.

enum nanogest_config_bits { NANOGEST_CONFIG_DEFAULT = 0, NANOGEST_CONFIG_NORMAL_RANGE = 0, NANOGEST_CONFIG_CLOSE_RANGE = 0x1, }; typedef enum nanogest_config_bits NanogestConfigBits;

Nanogest Class

@property(retain) id < NanogestGestureDelegate > gestureDelegate;

The gesture delegate of the gesture recognition object. The delegate must adopt the NanogestGestureDelegate protocol.

@property(retain) id < NanogestErrorDelegate > errorDelegate;

The error delegate of the gesture recognition object. The delegate must adopt the NanogestErrorDelegate protocol.

- (id)init;

Initializes and return a newly allocated gesture recognition object. On success, the gesture recognition must be started by sending the message start.

- (void)start;

Start gesture recognition. If running is YES, the message is ignored.

- (void)stop;

Stop gesture recognition. If running is NO, the message is ignored.

@property(nonatomic) NSUInteger config;

The config mask, a bitwise OR of NanogestConfigBits values. For instance, to set Nanogest in close range mode, use the following code:

self.ngest.config |= NANOGEST_CONFIG_CLOSE_RANGE;

- (void)mayAcceptOneHelloGesture:(BOOL)enabled;

If enabled is YES, allow the next gesture to be a "hello" gesture, or any other gesture. Once any gesture is detected, Nanogest will revert to the normal behavior of only accepting non-hello gestures.

If enabled is NO, only accept non-hello gestures. This is the default behavior.

This message must be sent whenever a HELLO gesture is expected or possible. For instance, if a dialog pops up to inform the user of an event, and the user may dismiss the dialog with a "hello" gesture, use the following code:

- (void)onAlert { [self showAlertDialog]; [self.ngest mayAcceptOneHelloGesture:YES]; } - (void)onGesture:(NanogestKind)gesture timestamp:(NSTimeInterval)timestamp { switch (gesture) { case NANOGEST_HELLO: [self dismissAlertDialog]; break; default: ... } }

Because "hello" is a slow gesture that can only be detected over a few hundred milliseconds, Nanogest does not accept "hello" gestures by default. Use "hello" gestures only when needed.

Advanced and optional features

@property BOOL preventScreenTimeout;

Whenever a gesture is detected, if preventScreenTimeout is YES, Nanogest will reset the idle timer of the application. If preventScreenTimeout is NO, gestures detected by Nanogest will not prevent the display from going to sleep. The default value is YES.

@property(readonly) BOOL running;

YES if the gesture detection is running. NO otherwise.

@property(retain) AVCaptureSession *captureSession;

The underlying AVCaptureSession used by Nanogest. It is possible to add an AVCaptureOutput to captureSession, but the inputs and configuration of captureSession must not be modified.

You may create an AVCaptureVideoPreviewLayer using captureSession.