Inherits from NSObject
Declared in LeapObjectiveC.h

Overview

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 occured 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:

MYListener *listener = [[MYListener 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:

MYDelegate *delegate = [[MYDelegate 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,
and onExit in the same manner.

Tasks

  • – init

    Initializes a LeapController instance.

  • – initWithListener:

    Initializes a LeapController instance and assigns a listener.

  • – policyFlags

    Gets the active policy settings.

  • – setPolicyFlags:

    Requests a change in policy.

  • – addListener:

    Adds a listener to this LeapController.

  • – removeListener:

    Unsubscribes the listener object from receiving Leap NSNotifications.

  • – initWithDelegate:

    Initializes a LeapController instance and assigns a delegate.

  • – addDelegate:

    Adds a delegate to this LeapController.

  • – removeDelegate

    Removes the delegate assigned to this LeapController.

  • – frame:

    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.

  • – config

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

  • – devices

    Returns a list of currently attached devices. Devices can be queried for
    device-specific information such as field of view.

  • – isConnected

    Reports whether this LeapController is connected to the Leap device.

  • – hasFocus

    Reports whether this application is the focused, foreground application.

  • – enableGesture:enable:

    Enables or disables reporting of a specified gesture type.

  • – isGestureEnabled:

    Reports whether the specified gesture type is enabled.

  • – locatedScreens

    The list of LeapScreen objects representing the computer display screens
    whose positions have been identified by using the Leap application's
    Screen Locator utility.

  •   calibratedScreens

    Deprecated. Use [LeapController locatedScreens:] instead.

    property

Properties

calibratedScreens

Deprecated. Use [LeapController locatedScreens:] instead.

@property (nonatomic, getter=locatedScreens, readonly) NSArray *calibratedScreens

Discussion

Deprecated. Use [LeapController locatedScreens:] instead.

Declared In

LeapObjectiveC.h

Instance Methods

addDelegate:

Adds a delegate to this LeapController.

- (BOOL)addDelegate:(id)delegate

Parameters

delegate

An object adopting the LeapDelegate protocol.

Return Value

BOOL Whether or not the delegate was successfully added.

Discussion

Adds a delegate to this LeapController.

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

Declared In

LeapObjectiveC.h

addListener:

Adds a listener to this LeapController.

- (BOOL)addListener:(id)listener

Parameters

listener

An object adopting the LeapListener protocol.

Return Value

BOOL Whether or not the listener was successfully added to the list
of listeners.

Discussion

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.

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

Declared In

LeapObjectiveC.h

config

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

- (LeapConfig *)config

Discussion

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

Declared In

LeapObjectiveC.h

devices

Returns a list of currently attached devices. Devices can be queried for
device-specific information such as field of view.

- (NSArray *)devices

Discussion

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.

Declared In

LeapObjectiveC.h

enableGesture:enable:

Enables or disables reporting of a specified gesture type.

- (void)enableGesture:(LeapGestureType)gestureType enable:(BOOL)enable

Parameters

gestureType

The type of gesture to enable or disable. Must be a
member of the LeapGestureType enumeration:

  • LEAP_GESTURE_TYPE_SWIPE – A straight line movement by the hand with fingers extended.
  • LEAP_GESTURE_TYPE_CIRCLE – A circular movement by a finger.
  • LEAP_GESTURE_TYPE_SCREEN_TAP – A forward tapping movement by a finger.
  • LEAP_GESTURE_TYPE_KEY_TAP – A downward tapping movement by a finger.
enable

YES, to enable the specified gesture type; NO,
to disable.

Discussion

Enables or disables reporting of a specified gesture type.

By default, all gesture types are disabled. When disabled, gestures of the
disabled type are never reported and will not appear in the frame
gesture list.

As a performance optimization, only enable recognition for the types
of movements that you use in your application.

Declared In

LeapObjectiveC.h

frame:

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:(int)history

Parameters

history

The age of the LeapFrame to return, counting backwards from
the most recent frame (0) into the past and up to the maximum age (59).

Return Value

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.

Discussion

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.

Declared In

LeapObjectiveC.h

hasFocus

Reports whether this application is the focused, foreground application.

- (BOOL)hasFocus

Return Value

True, if application has focus; false otherwise.

Discussion

Reports whether this application is the focused, foreground application.

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

Declared In

LeapObjectiveC.h

init

Initializes a LeapController instance.

- (id)init

Discussion

Initializes a LeapController instance.

Declared In

LeapObjectiveC.h

initWithDelegate:

Initializes a LeapController instance and assigns a delegate.

- (id)initWithDelegate:(id)delegate

Parameters

delegate

An object adopting the LeapDelegate protocol.

Discussion

Initializes a LeapController instance and assigns a delegate.

  • Note: You can use either a delegate or a listener, but not both.

Declared In

LeapObjectiveC.h

initWithListener:

Initializes a LeapController instance and assigns a listener.

- (id)initWithListener:(id)listener

Parameters

listener

An object adopting the LeapListener protocol.

Discussion

Initializes a LeapController instance and assigns a listener.

  • Note: You can use either a listener or a delegate, but not both.

Declared In

LeapObjectiveC.h

isConnected

Reports whether this LeapController is connected to the Leap device.

- (BOOL)isConnected

Return Value

True, if connected; false otherwise.

Discussion

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.

Declared In

LeapObjectiveC.h

isGestureEnabled:

Reports whether the specified gesture type is enabled.

- (BOOL)isGestureEnabled:(LeapGestureType)gestureType

Parameters

gestureType

The type of gesture to check. Must be a
member of the LeapGestureType enumeration:

  • LEAP_GESTURE_TYPE_SWIPE – A straight line movement by the hand with fingers extended.
  • LEAP_GESTURE_TYPE_CIRCLE – A circular movement by a finger.
  • LEAP_GESTURE_TYPE_SCREEN_TAP – A forward tapping movement by a finger.
  • LEAP_GESTURE_TYPE_KEY_TAP – A downward tapping movement by a finger.

Return Value

YES, if the specified type is enabled; NO, otherwise.

Discussion

Reports whether the specified gesture type is enabled.

Declared In

LeapObjectiveC.h

locatedScreens

The list of LeapScreen objects representing the computer display screens
whose positions have been identified by using the Leap application's
Screen Locator utility.

- (NSArray *)locatedScreens

Return Value

NSArray An array containing the screens whose positions have
been registered by the user using the Screen Locator tool.
The list always contains at least one entry representing the default
monitor. If the user has not run the Screen Locator or has moved the Leap
device or screen since running it, the LeapScreen object for this entry
only contains default values.

Discussion

The list of LeapScreen objects representing the computer display screens
whose positions have been identified by using the Leap application's
Screen Locator utility.

The list always contains at least one entry representing the default
screen. If the user has not registered the location of this default
screen, then the coordinates, directions, and other values reported by
the functions in its LeapScreen object will not be accurate. Other monitor
screens only appear in the list if their positions have been registered
using the Leap Screen Locator.

A LeapScreen object represents the position and orientation of a display
monitor screen within the Leap coordinate system.
For example, if the screen location is known, you can get Leap coordinates
for the bottom-left corner of the screen. Registering the screen
location also allows the Leap to calculate the point on the screen at
which a finger or tool is pointing.

A user can run the Screen Locator tool from the Leap application
Settings window. Avoid assuming that a screen location is known or that
an existing position is still correct. The registered position is only
valid as long as the relative position of the Leap device and the
monitor screen remain constant.

Declared In

LeapObjectiveC.h

policyFlags

Gets the active policy settings.

- (LeapPolicyFlag)policyFlags

Return Value

The current policy flags.

Discussion

Gets the active policy settings.

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 setPolicyFlag]. 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.

Declared In

LeapObjectiveC.h

removeDelegate

Removes the delegate assigned to this LeapController.

- (BOOL)removeDelegate

Return Value

BOOL Whether or not the delegate was successfully removed.

Discussion

Removes the delegate assigned to this LeapController.

Declared In

LeapObjectiveC.h

removeListener:

Unsubscribes the listener object from receiving Leap NSNotifications.

- (BOOL)removeListener:(id)listener

Parameters

listener

The listener to unsubscribe.

Return Value

BOOL Whether or not the listener was successfully removed.

Discussion

Unsubscribes the listener object from receiving Leap NSNotifications.

Declared In

LeapObjectiveC.h

setPolicyFlags:

Requests a change in policy.

- (void)setPolicyFlags:(LeapPolicyFlag)flags

Parameters

flags

A PolicyFlag value indicating the policies to request. Must be
a member of the LeapPolicyFlags enumeration:

  • LEAP_POLICY_DEFAULT – restore the default policy configuration for this
    application (do not receive frames while in the background).
  • LEAP_POLICY_BACKGROUND_FRAMES – the application should receive frames of
    motion tracking data while in the background.

Discussion

Requests a change in 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 policyFlags] after a suitable interval to test whether
the change was accepted.

Currently, the background frames policy is the only policy supported.
The background frames policy determines whether an application
receives frames of tracking data while in the background. By
default, the Leap only sends tracking data to the foreground application.
Only applications that need this ability should request the background
frames policy.

At this time, you can use the Leap applications Settings window to
globally enable or disable the background frames policy. However,
each application that needs tracking data while in the background
must also set the policy flag using this function.

This function can be called before the LeapController object is connected,
but the request will be sent to the Leap after the controller connects.

Declared In

LeapObjectiveC.h