LeapController Class Reference
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
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.
See Also
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.
- LEAP_POLICY_DEFAULT – restore the default policy configuration for this
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