Leap Motion Java API Reference  0.8.0
com.leapmotion.leap.Controller Class Reference

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

Inherits com.leapmotion.leap.Interface.

Classes

enum  PolicyFlag
 The supported controller policies. More...
 

Public Member Functions

boolean addListener (Listener listener)
 Adds a listener to this Controller.
 
ScreenList calibratedScreens ()
 Deprecated.
 
Config config ()
 Returns a Config object, which you can use to query the Leap Motion system for configuration information.
 
 Controller ()
 Constructs a Controller object.
 
 Controller (Listener listener)
 Constructs a Controller object.
 
DeviceList devices ()
 The list of currently attached and recognized Leap Motion controller devices.
 
void enableGesture (Gesture.Type type, boolean enable)
 Enables or disables reporting of a specified gesture type.
 
void enableGesture (Gesture.Type type)
 Enables or disables reporting of a specified gesture type.
 
Frame frame (int history)
 Returns a frame of tracking data from the Leap Motion software.
 
Frame frame ()
 Returns a frame of tracking data from the Leap Motion software.
 
boolean hasFocus ()
 Reports whether this application is the focused, foreground application.
 
boolean isConnected ()
 Reports whether this Controller is connected to the Leap Motion device.
 
boolean isGestureEnabled (Gesture.Type type)
 Reports whether the specified gesture type is enabled.
 
ScreenList locatedScreens ()
 The list of screens whose positions have been identified by using the Leap Motion Screen Locator.
 
Controller.PolicyFlag policyFlags ()
 Gets the active policy settings.
 
boolean removeListener (Listener listener)
 Remove a listener from the list of listeners that will receive Leap Motion events.
 
void setPolicyFlags (Controller.PolicyFlag flags)
 Requests a change in policy.
 

Detailed Description

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

Create an instance of this Controller class to access frames of tracking data and configuration information. Frame data can be polled at any time using the Controller::frame() function. Call frame() or frame(0) to get the most recent frame. Set the history parameter to a positive integer to access previous frames. 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 an instance of a subclass of Leap::Listener to the controller to handle events as they occur. The Controller dispatches events to the listener upon initialization and exiting, on connection changes, when the application gains and loses the OS input focus, and when a new frame of tracking data is available. When these events occur, the controller object invokes the appropriate callback function defined in your subclass of Listener.

To access frames of tracking data as they become available:

  1. Implement a subclass of the Listener class and override the Listener::onFrame() function.
  2. In your Listener::onFrame() function, call the Controller::frame() function to access the newest frame of tracking data.
  3. To start receiving frames, create a Controller object and add an instance of the Listener subclass to the Controller::addListener() function.

When an instance of a Listener subclass is added to a Controller object, it calls the Listener::onInit() function when the listener is ready for use. When a connection is established between the controller and the Leap Motion software, the controller calls the Listener::onConnect() function. At this point, your application will start receiving frames of data. The controller calls the Listener::onFrame() function each time a new frame is available. If the controller loses its connection with the Leap Motion software or device for any reason, it calls the Listener::onDisconnect() function. If the listener is removed from the controller or the controller is destroyed, it calls the Listener::onExit() function. At that point, unless the listener is added to another controller again, it will no longer receive frames of tracking data.

The Controller object is multithreaded and calls the Listener functions on its own thread, not on an application thread.

Constructor & Destructor Documentation

com.leapmotion.leap.Controller.Controller ( )

Constructs a Controller object.

When creating a Controller object, you may optionally pass in a reference to an instance of a subclass of Leap::Listener. Alternatively, you may add a listener using the Controller::addListener() function.

com.leapmotion.leap.Controller.Controller ( Listener  listener)

Constructs a Controller object.

When creating a Controller object, you may optionally pass in a reference to an instance of a subclass of Leap::Listener. Alternatively, you may add a listener using the Controller::addListener() function.

Parameters
listenerAn instance of Leap::Listener implementing the callback functions for the Leap Motion events you want to handle in your application.

Member Function Documentation

boolean com.leapmotion.leap.Controller.addListener ( Listener  listener)

Adds a listener to this Controller.

The Controller dispatches Leap Motion events to each associated listener. The order in which listener callback functions are invoked is arbitrary. If you pass a listener to the Controller's constructor function, it is automatically added to the list and can be removed with the Controller::removeListener() function.

Parameters
listenerA subclass of Leap::Listener implementing the callback functions for the Leap Motion events you want to handle in your application.
Returns
Whether or not the listener was successfully added to the list of listeners.
ScreenList com.leapmotion.leap.Controller.calibratedScreens ( )
Config com.leapmotion.leap.Controller.config ( )

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

DeviceList com.leapmotion.leap.Controller.devices ( )

The list of currently attached and recognized Leap Motion controller devices.

The Device objects in the list describe information such as the range and tracking volume.

Currently, the Leap Motion Controller only recognizes a single device at a time.

void com.leapmotion.leap.Controller.enableGesture ( Gesture.Type  type,
boolean  enable 
)

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.

Parameters
typeThe type of gesture to enable or disable. Must be a member of the Gesture::Type enumeration.
enableTrue, to enable the specified gesture type; False, to disable.
See Also
Controller::isGestureEnabled()
void com.leapmotion.leap.Controller.enableGesture ( Gesture.Type  type)

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.

Parameters
typeThe type of gesture to enable or disable. Must be a member of the Gesture::Type enumeration.
enableTrue, to enable the specified gesture type; False, to disable.
See Also
Controller::isGestureEnabled()
Frame com.leapmotion.leap.Controller.frame ( int  history)

Returns a frame of tracking data from the Leap Motion software.

Use the optional history parameter to specify which frame to retrieve. Call frame() or frame(0) to access the most recent frame; call 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.

Parameters
historyThe age of the frame to return, counting backwards from the most recent frame (0) into the past and up to the maximum age (59).
Returns
The specified frame; or, if no history parameter is specified, the newest frame. If a frame is not available at the specified history position, an invalid Frame is returned.
Frame com.leapmotion.leap.Controller.frame ( )

Returns a frame of tracking data from the Leap Motion software.

Use the optional history parameter to specify which frame to retrieve. Call frame() or frame(0) to access the most recent frame; call 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.

Parameters
historyThe age of the frame to return, counting backwards from the most recent frame (0) into the past and up to the maximum age (59).
Returns
The specified frame; or, if no history parameter is specified, the newest frame. If a frame is not available at the specified history position, an invalid Frame is returned.
boolean com.leapmotion.leap.Controller.hasFocus ( )

Reports whether this application is the focused, foreground application.

By default, your application only receives tracking information from the Leap Motion controller when it has the operating system input focus. To receive tracking data when your application is in the background, the background frames policy flag must be set.

Returns
True, if application has focus; false otherwise.
See Also
Controller::setPolicyFlags()
boolean com.leapmotion.leap.Controller.isConnected ( )

Reports whether this Controller is connected to the Leap Motion device.

When you first create a Controller object, isConnected() returns false. After the controller finishes initializing and connects to the Leap Motion software, isConnected() will return true.

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

Returns
True, if connected; false otherwise.
boolean com.leapmotion.leap.Controller.isGestureEnabled ( Gesture.Type  type)

Reports whether the specified gesture type is enabled.

Returns
True, if the specified type is enabled; false, otherwise.
See Also
Controller::enableGesture()
ScreenList com.leapmotion.leap.Controller.locatedScreens ( )

The list of screens whose positions have been identified by using the Leap Motion Screen Locator.

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 Screen object will not be accurate. Other monitor screens only appear in the list if their positions have been registered using the Leap Motion Screen Locator.

A Screen object represents the position and orientation of a display monitor screen within the Leap Motion coordinate system. For example, if the screen location is known, you can get Leap Motion coordinates for the bottom-left corner of the screen. Registering the screen location also allows the Leap Motion software 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 Motion Settings dialog. 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 Motion device and the monitor screen remain constant.

ScreenList screens = this.controller.locatedScreens();
Returns
ScreenList A list 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 Motion device or screen since running it, the Screen object for this entry only contains default values.
Controller.PolicyFlag com.leapmotion.leap.Controller.policyFlags ( )

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 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 Motion software, then the default policy state is returned.

Returns
The current policy flags.
boolean com.leapmotion.leap.Controller.removeListener ( Listener  listener)

Remove a listener from the list of listeners that will receive Leap Motion events.

A listener must be removed if its lifetime is shorter than the controller to which it is listening.

Parameters
listenerThe listener to remove.
Returns
Whether or not the listener was successfully removed from the list of listeners.
void com.leapmotion.leap.Controller.setPolicyFlags ( Controller.PolicyFlag  flags)

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 Motion settings dialog). 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 Controller::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 Motion software 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 Motion Settings dialog 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 Controller object is connected, but the request will be sent to the Leap Motion software after the Controller connects.

Parameters
flagsA PolicyFlag value indicating the policies to request.