LeapControllerΒΆ

LeapController Class Reference

The LeapController class is your main interface to the Leap Motion Controller hardware. More...

Inherits NSObject.

Instance Methods

(BOOL) - addDelegate:
 Adds a delegate to this LeapController. More...
 
(BOOL) - addListener:
 Adds a listener to this LeapController. More...
 
(void) - clearPolicy:
 Requests clearing a policy. More...
 
(void) - enableGesture:enable:
 Enables or disables reporting of a specified gesture type. More...
 
(LeapFrame *) - frame:
 Returns a LeapFrame containing a frame of tracking data from the Leap. More...
 
(id) - init
 Initializes a LeapController instance. More...
 
(id) - initWithDelegate:
 Initializes a LeapController instance and assigns a delegate. More...
 
(id) - initWithListener:
 Initializes a LeapController instance and assigns a listener. More...
 
(BOOL) - isGestureEnabled:
 Reports whether the specified gesture type is enabled. More...
 
(BOOL) - isPolicySet:
 Gets the active setting for a specific policy. More...
 
(int64_t) - now
 Returns a timestamp value as close as possible to the current time. More...
 
(LeapPolicyFlag) - policyFlags
 This method has been deprecated. More...
 
(BOOL) - removeDelegate
 Removes the delegate assigned to this LeapController. More...
 
(BOOL) - removeListener:
 Unsubscribes the listener object from receiving Leap NSNotifications. More...
 
(void) - setPaused:
 Pauses or resumes the Leap Motion service. More...
 
(void) - setPolicy:
 Requests setting a policy. More...
 
(void) - setPolicyFlags:
 This method has been deprecated. More...
 

Properties

LeapConfigconfig
 Returns a Config object, which you can use to query the Leap system for configuration information. More...
 
NSArray * devices
 Returns a list of currently attached devices. More...
 
NSArray * failedDevices
 A list of any Leap Motion hardware devices that are physically connected to the client computer, but are not functioning correctly. More...
 
BOOL hasFocus
 Reports whether this application is the focused, foreground application. More...
 
NSArray * images
 The most recent set of images from the Leap Motion cameras. More...
 
BOOL isConnected
 Reports whether this LeapController is connected to the Leap device. More...
 
BOOL isPaused
 Reports whether the Leap Motion service is currently paused. More...
 
BOOL isServiceConnected
 Reports whether this LeapService is in communication with the client API. More...
 

Detailed Description

The LeapController class is your main interface to the Leap Motion Controller hardware.

Create an instance of this LeapController class to access frames of tracking data and configuration information. Frame data can be polled at any time using the [LeapController frame:] function. Set the frame: parameter to 0 to get the most recent frame. Set the parameter to a positive integer to access previous frames. For example, [controller frame:10] returns the frame that occurred ten frames ago. A controller stores up to 60 frames in its frame history.

Polling is an appropriate strategy for applications which already have an intrinsic update loop, such as a game. You can also add a listener object or delegate to the controller to handle events as they occur. The Leap dispatches events to the listener upon initialization and exiting, on connection changes, and when a new frame of tracking data is available. When these events occur, the controller object invokes the appropriate callback function.

Polling

Create an instance of the LeapController class using the default initializer:

LeapController *controller = [[LeapController alloc] init];

Access the frame data at regular intervals:

LeapFrame *frame = [controller frame:0];

You can check [LeapController isConnected] to determine if the controller is connected to the Leap software.

LeapListener protocol

Implement a class adopting the LeapListener protocol.

Create an instance of the LeapController class and assign your LeapListener object to it:

FrameListener *listener = [[FrameListener alloc] init];
LeapController *controller = [[LeapController alloc] initWithListener:listener];

The controller subscribes the LeapListener instance to the appropriate NSNotifications for the Leap events. When a new frame of data is ready, the controller dispatches an NSNotification on the main application thread, which is handled by your [LeapListener onFrame:] implementation.

LeapDelegate protocol

Implement a class adopting the LeapDelegate protocol.

Create an instance of the LeapController class and assign your LeapListener object to it:

LeapEventDelegate *delegate = [[LeapEventDelegate alloc] init];
LeapController *controller = [[LeapController alloc] init];
[controller addDelegate:delegate];

When a new frame of data is ready, the controller calls the [LeapDelegate onFrame:] method. The Controller object is multithreaded and calls the LeapDelegate functions on its own thread, not on an application thread.

You can handle the other Leap events, onInit, onConnect, onDisconnect, onServiceConnect, onServiceDisconnect, onDeviceChange, and onExit in the same manner.

Since 1.0

Method Documentation

- (BOOL) addDelegate: (id< LeapDelegate >)  delegate

Adds a delegate to this LeapController.

LeapEventDelegate *delegate = [[LeapEventDelegate alloc] init];
LeapController *controller = [[LeapController alloc] init];
[controller addDelegate:delegate];

Note: You cannot add a delegate when there is already a listener assigned.

Parameters
delegateAn object adopting the LeapDelegate protocol.
Returns
BOOL Whether or not the delegate was successfully added.
Since 1.0
- (BOOL) addListener: (id< LeapListener >)  listener

Adds a listener to this LeapController.

When you add an object adopting the LeapListener protocol to a LeapController, the controller automatically subscribes the listener to NSNotifications dispatched for the Leap events.

[controller addListener:listener];

Note: You cannot add a listener when there is already a delegate assigned.

Parameters
listenerAn object adopting the LeapListener protocol.
Returns
BOOL Whether or not the listener was successfully added to the list of listeners.
Since 1.0
- (void) clearPolicy: (LeapPolicyFlag)  policy

Requests clearing a policy.

Policy changes are completed asynchronously and, because they are subject to user approval, may not complete successfully. Call [LeapController isPolicySet:] after a suitable interval to test whether the change was accepted.

[controller clearPolicy:LEAP_POLICY_IMAGES];
Parameters
flagsA PolicyFlag value indicating the policy to request.
Since 2.1.6
- (void) enableGesture: (LeapGestureType)  gestureType
enable: (BOOL)  enable 

Enables or disables reporting of a specified gesture type.

Parameters
enableYES, to enable the specified gesture type; NO, to disable.
See also
[LeapController - isGestureEnabled:]
- (LeapFrame *) frame: (int)  history

Returns a LeapFrame containing a frame of tracking data from the Leap.

Use the optional history parameter to specify which frame to retrieve. Call [controller frame:0] to access the most recent frame; call [controller frame:1] to access the previous frame, and so on. If you use a history value greater than the number of stored frames, then the controller returns an invalid frame.

LeapFrame *frame = [controller frame:0];
Parameters
historyThe age of the LeapFrame to return, counting backwards from the most recent frame (0) into the past and up to the maximum age (59).
Returns
The specified LeapFrame; or, if no history parameter is specified, the newest frame. If a frame is not available at the specified history position, an invalid LeapFrame is returned.
Since 1.0
- (id) init

Initializes a LeapController instance.

LeapController *controller = [[LeapController alloc] init];
Since 1.0
- (id) initWithDelegate: (id< LeapDelegate >)  delegate

Initializes a LeapController instance and assigns a delegate.

LeapEventDelegate *delegate = [[LeapEventDelegate alloc] init];
LeapController *controller = [[LeapController alloc] initWithDelegate:delegate];
  • Note: You can use either a delegate or a listener, but not both.
Parameters
delegateAn object adopting the LeapDelegate protocol.
Since 1.0
- (id) initWithListener: (id< LeapListener >)  listener

Initializes a LeapController instance and assigns a listener.

FrameListener *listener = [[FrameListener alloc] init];
LeapController *controller = [[LeapController alloc] initWithListener:listener];
  • Note: You can use either a listener or a delegate, but not both.
Parameters
listenerAn object adopting the LeapListener protocol.
Since 1.0
- (BOOL) isGestureEnabled: (LeapGestureType)  gestureType

Reports whether the specified gesture type is enabled.

if (![controller isGestureEnabled:LEAP_GESTURE_TYPE_KEY_TAP]) {
[controller enableGesture:LEAP_GESTURE_TYPE_KEY_TAP enable:true];
}
Parameters
gestureTypeThe type of gesture to check. Must be a member of the LeapGestureType enumeration:
Returns
YES, if the specified type is enabled; NO, otherwise.
See also
[LeapController - enableGesture:enable:]
- (BOOL) isPolicySet: (LeapPolicyFlag)  policy

Gets the active setting for a specific policy.

Use this function to determine the current policy state. Keep in mind that setting a policy flag is asynchronous, so changes are not effective immediately after calling [LeapController setPolicy:]. In addition, a policy request can be declined by the user. You should always set the policy flags required by your application at startup and check that the policy change request was successful after an appropriate interval.

If the controller object is not connected to the Leap, then the default policy state is returned.

bool isImagePolicySet = [controller isPolicySet:LEAP_POLICY_IMAGES];

This method has been deprecated. Use [LeapController isPolicySet:] instead.

Parameters
flagsA PolicyFlag value indicating the policy to query.
Returns
A boolean indicating whether the specified policy has been set.
Since 2.1.6
- (int64_t) now

Returns a timestamp value as close as possible to the current time.

Values are in microseconds, as with all the other timestamp values.

LeapFrame *frame = [controller frame:0];
int64_t frameAge = 0;
if(frame.isValid){
frameAge = [controller now] - frame.timestamp; //microseconds
}
Since
2.3.0
- (LeapPolicyFlag) policyFlags

This method has been deprecated.

Use [LeapController isPolicySet:] instead.

Returns
The current policy flags.
- (BOOL) removeDelegate

Removes the delegate assigned to this LeapController.

[controller removeDelegate];
Returns
BOOL Whether or not the delegate was successfully removed.
Since 1.0
- (BOOL) removeListener: (id< LeapListener >)  listener

Unsubscribes the listener object from receiving Leap NSNotifications.

[controller removeListener:listener];
Parameters
listenerThe listener to unsubscribe.
Returns
BOOL Whether or not the listener was successfully removed.
Since 1.0
- (void) setPaused: (BOOL)  enable

Pauses or resumes the Leap Motion service.

When the service is paused no applications receive tracking data and the service itself uses minimal CPU time.

Before changing the state of the service, you must set the POLICY_ALLOW_PAUSE_RESUME using the [LeapController setPolicy:] function. Policies must be set every time the application is run.

Parameters
pauseSet true to pause the service; false to resume.
Since
3.0
- (void) setPolicy: (LeapPolicyFlag)  policy

Requests setting a policy.

A request to change a policy is subject to user approval and a policy can be changed by the user at any time (using the Leap settings window). The desired policy flags must be set every time an application runs.

Policy changes are completed asynchronously and, because they are subject to user approval, may not complete successfully. Call [LeapController isPolicySet:] after a suitable interval to test whether the change was accepted.

The current policies are:

LEAP_POLICY_BACKGROUND_FRAMES – requests that your application receives frames when it is not the foreground application for user input.
The background frames policy determines whether an application receives frames of tracking data while in the background. By default, the Leap Motion software only sends tracking data to the foreground application. Only applications that need this ability should request the background frames policy. The "Allow Background Apps" checkbox must be enabled in the Leap Motion Control Panel or this policy will be denied.

LEAP_POLICY_IMAGES – request that your application receives images from the device cameras. The "Allow Images" checkbox must be enabled in the Leap Motion Control Panel or this policy will be denied.
The images policy determines whether an application receives image data from the Leap Motion sensors which each frame of data. By default, this data is not sent. Only applications that use the image data should request this policy.
LEAP_POLICY_OPTIMIZE_HMD – request that the tracking be optimized for head-mounted tracking.
The optimize HMD policy improves tracking in situations where the Leap Motion hardware is attached to a head-mounted display. This policy is not granted for devices that cannot be mounted to an HMD.

[controller setPolicy:LEAP_POLICY_BACKGROUND_FRAMES];
[controller setPolicy:LEAP_POLICY_IMAGES];
Parameters
flagsA PolicyFlag value indicating the policy to request. Must be a member of the LeapPolicyFlags enumeration:

LEAP_POLICY_BACKGROUND_FRAMES

LEAP_POLICY_IMAGES

LEAP_POLICY_OPTIMIZE_HMD

Since 2.1.6
- (void) setPolicyFlags: (LeapPolicyFlag)  flags

This method has been deprecated.

Use [LeapController setPolicy:] and [LeapController clearPolicy:] instead.

Returns
The current policy flags.

Property Documentation

- (LeapConfig*) config
readnonatomicassign

Returns a Config object, which you can use to query the Leap system for configuration information.

LeapConfig *config = controller.config;
Since 1.0
- (NSArray*) devices
readnonatomicassign

Returns a list of currently attached devices.

Devices can be queried for device-specific information such as field of view.

Currently the Leap controller only recognizes a single device at a time.

NSArray *deviceList = controller.devices;
Since 1.0
- (NSArray*) failedDevices
readnonatomicassign

A list of any Leap Motion hardware devices that are physically connected to the client computer, but are not functioning correctly.

The list contains LeapFailedDevice objects containing the pnpID and the reason for failure. No other device information is available.

Since
3.0
- (BOOL) hasFocus
readnonatomicassign

Reports whether this application is the focused, foreground application.

Only the foreground application receives tracking information from the Leap Motion Controller.

if(!controller.hasFocus){
//Pause app
}
Returns
True, if application has focus; false otherwise.
Since 1.0
- (NSArray*) images
readnonatomicassign

The most recent set of images from the Leap Motion cameras.

Depending on timing and the current processing frame rate, the images obtained with this function can be newer than images obtained from the current frame of tracking data.

NSArray *images = controller.images;
//image latency:
LeapImage * image = [images objectAtIndex:0];
int64_t imageAge = [controller now] - image.timestamp;
Returns
An NSArray object containing the most recent camera images.
Since
2.2.1
- (BOOL) isConnected
readnonatomicassign

Reports whether this LeapController is connected to the Leap device.

When you first create a LeapController object, isConnected returns false. After the controller finishes initializing and connects to the Leap, isConnected will return true.

You can either handle the onConnect event using a LeapListener or LeapDelegate instance or poll the isConnected function if you need to wait for your application to be connected to the Leap before performing some other operation.

if(controller.isConnected){
LeapFrame *frame = [controller frame:0];
}
Returns
True, if connected; false otherwise.
Since 1.0
- (BOOL) isPaused
readnonatomicassign

Reports whether the Leap Motion service is currently paused.

Returns
True, if the service is paused; false, otherwise.
Since
3.0
- (BOOL) isServiceConnected
readnonatomicassign

Reports whether this LeapService is in communication with the client API.

When you first create a LeapController object, isServiceConnected returns false. After the controller finishes initializing and makes contact with the LeapService, isServiceConnected will return true.

You can either handle the onServiceConnect event using a LeapListener or LeapDelegate instance or poll the isServiceConnected function if you need to wait for your application to be connected to the Leap Service before performing some other operation.

if(controller.isServiceConnected){
LeapFrame *frame = [controller frame:0];
}
Returns
True, if connected; false otherwise.
Since 1.2