To connect to the Leap Motion device, create a Controller object. The Controller object automatically establishes a connection to the Leap Motion daemon or service which then passes tracking data, in the form of Frame objects to your application.
Controller controller = new Controller ();
Use the Controller object to get information about the state of the connection and connected hardware and to set connection options for your application.
Get Frame objects containing tracking data by calling the Controller.Frame() function. You can call this function whenever your application is ready to process data to get the most recent set of data generated by the Leap Motion device. You can also implement a |Listener|_ object defining a callback function and the Controller will invoke this function when a new frame of data is ready.
See Frames for more information.
Ordinarily, the Leap Motion service/daemon only sends tracking data to the application that has the operating system input focus. This prevents applications idling in the background from receiving input intended for another applications.
If your application runs in the foreground and you want to know whether the service/daemon considers your application to be the foreground application, you can check |Controller.hasFocus|_ or listen to events dispatched by the controller. The service/daemon gets changes in application focus status directly from the operating system. Note that the Linux operating system does not provide this information, so applications running on Linux always receive tracking data.
Note that applications connecting to the Leap Motion service/daemon through the WebSocket server do not automatically start receiving data when they gain the operating system focus. Applications using the WebSocket server must explicitly request focus from the service when they move to the foreground. (The LeapJS JavaScript library does manage the foreground-background transition for you, however.)
You can tell the controller that your application wants data even when it is in the background using Controller.SetPolicy(). Set the BACKGROUND_POLICY_FLAG policy for applications such as mouse emulators or operating system controls that need data when they are not the focused application. The Allow Background Apps setting in the Leap Motion control panel must be checked or the attempt to set the policy is denied.
Note that your application does not receive frames if another Leap-enabled application is in the foreground, even when the background frames policy is in effect. The policy only matters when a non-Leap-enabled app has the operating system input focus.
In order for your application to receive images from the Leap Motion cameras, you must set the Images policy. The Allow Images setting in the Leap Motion control panel must be checked or the attempt to set the policy is denied. See Camera Images.
When you create a Controller, the object attempts to establish a connection to the Leap Motion service/daemon. If it succeeds, the |Controller.isServiceConnected|_ property changes to true. Likewise, if the Leap Motion hardware is plugged in and detected by the service/daemon, the Controller.IsConnected property changes to true.
The IsServiceConnected and IsConnected properties can change while your application is running. You can monitor their values or listen for events dispatched by the controller when the connection status changes.
The Controller object dispatches a number of events using the |Listener|_ mechanism. To handle these events, you can extend the |Listener|_ class to implement callback functions. The Controller invokes the relevant callback function when an event occurs.
The events include:
| |Listener_onConnect|_ | The Controller connects to the Leap Motion service/daemon and the Leap Motion hardware is attached. |
| |Listener_onDeviceChange|_ | The status of a Leap Motion hardware device changes. |
| |Listener_onDisconnect|_ | The Controller disconnects from the Leap Motion service/daemon or the Leap Motion hardware is removed. |
| |Listener_onExit|_ | The Controller object is destroyed. |
| |Listener_onFocusGained|_ | The application has gained operating system input focus and will start receiving tracking data. |
| |Listener_onFocusLost|_ | The application has lost operating system input focus. The application will stop receiving tracking data unless it has set the |BACKGROUND_FRAMES_POLICY|_. |
| |Listener_onFrame|_ | A new Frame of tracking data is available. |
| |Listener_onInit|_ | The Controller object is initialized. |
| |Listener_onServiceConnect|_ | The Controller has connected to the Leap Motion service/daemon. |
| |Listener_onServiceDisconnect|_ | The Controller has lost its connection to the Leap Motion service/daemon. |
The dispatching Controller passes itself to the callback, which makes it easy to then query the Controller for more information in the body of the callback function.
The following example shows a simplistic implementation of a Listener subclass with some representative callback functions:
You can then add an instance of your listener implementation to a controller:
Each event callback function is invoked on an independent thread created by the Leap Motion library. The tracking data objects created by the library are thread safe, but you must make sure that other application data accessed from the callback function can be safely altered from seprate threads. You can avoid the complications associated with multithreaded applications by polling the Controller for frames and state when convenient for your application instead of using listeners.
There are currently three types of Leap Motion hardware available: the standard controller as a separate computer peripheral, a controller embedded in a computer keyboard, and a controller embedded in a laptop computer The performance of all of these devices is equivalent. However, be aware that the devices are very different physically. For example, devices embedded in laptops cannot be unplugged, but rather are activated or deactivated with keyboard shortcuts.
You can get the device type from Device.Type. Use Controller.Devices to get the list of attached devices (currently only one device is recognized at a time).