Connecting to the Controller(与控制器对象连接)

Connecting to the Controller(与控制器对象连接)

为了与Leap Motion设备连接，需要创建一个Controller对象。这个对象会自动建立与Leap Motion服务的连接，之后后者以Frame对象的形式把跟踪数据传递到你的应用程序中。用这个Controller对象来得到关于连接状态和硬件的信息，并为你的应用程序设置连接选项。
Leap::Controller controller;

• Get Frames

通过调用Controller.frame()函数来得到包含跟踪数据的Frame对象。只要你的应用程序准备好处理数据来得到Leap Motion设备最近生成的一组数据。也可以执行一个Listener对象来定义一个回调函数，然后当新的一帧数据准备好的时候Controller会调用这个函数。

• Foreground and Background Applications

通常，Leap Motion的服务只会把跟踪数据送给操作系统聚焦的应用程序，这会防止在后台空载的应用程序接收另一个应用程序的输入。
如果你的应用程序在前台运行，你想知道服务是否把你的应用看作是前台应用，你可以用Controller.hasFocus()或者听控制器分派的事件。服务会直接从操作系统中改变应用程序的聚焦状态。注意，Linux系统不会提供这个信息，所以在Linux下运行的应用会不断的接收跟踪信息。
当得到了操作系统的聚焦时，通过WebSocket服务器与Leap Motion服务连接的应用程序不会自动开始接收数据。当移动到前台时，用WebSocket服务器的应用程序必须明确地请求服务的聚焦（然而Leap JavaScript库会为你管理前后台的过渡）。
你可以用Controller.setPolicy()函数来告诉控制器你的应用程序需要数据，即使它在后台。为需要数据的应用设置策略BACKGROUND_POLICY_FLAG，诸如鼠标模拟器或操作系统控制。Leap Motion控制面板上的Allow Background Apps的设置必须检查或者设置这个策略的尝试被拒绝。
如果另一个Leap启用的应用程序在前台的话，你的应用无法接收帧数据，即使后台帧策略有效。只有当一个非Leap启用的应用程序被操作系统聚焦输入，策略才会有效。
Leap::Controller::PolicyFlag current = controller.policyFlags();

• Access to Images

为了你的应用可以从Leap Motion相机中接收图片，必须设置Images的策略。Leap Motion控制面板上的Allow Images的设置必须检查或者设置这个策略的尝试被拒绝。

• Enabling Gestures

为了使用固定的手势，首先必须用Controller.enableGesture()函数启用它们（只启用你的应用程序用到的那些手势）：
controller.enableGesture(Leap::Gesture::TYPE_CIRCLE);

• Connection State

当你创建一个Controller，这个对象尝试与Leap Motion的服务建立连接。如果成功，Controller.isServiceConnected()属性变为true。同样的，如果Leap Motion的硬件插电了，被服务检测到了，Controller.isConnected()属性变为true。
当你的应用程序在执行的时候，isServiceConnected()和isConnected()属性会改变。你可以监控它们的值或者当连接状态变化的时候听控制器分派的事件。

• Listening for Controller Events

Controller对象利用Listener机制分派了一定数量的事件。为了处理这些事件，你可以扩展Listener类来实现回调函数。当一个事件发生，Controller对象调用相关的回调函数。这些事件包括：onConnect()、onDeviceChange()、onDisconnect()、onExit()、onFocusGained()、onFocusLost()、onFrame()、onInit()、onServiceConnect()、onServiceDisconnect()，详见Listener类。分派的Controller对象把它传给回调函数，这会使得查询Controller的更多信息变容易。下面的例子是一个Listener的子类使用一些代表性的回调函数的简单运用：

#include <iostream>#include "Leap.h"using namespace Leap;class LeapEventListener : public Listener {  public:    virtual void onConnect(const Controller&);    virtual void onDisconnect(const Controller&);    virtual void onFrame(const Controller&);};void LeapEventListener::onConnect(const Controller& controller) {    std::cout << "Connected" << std::endl;    // Enable gestures, set Config values:    controller.enableGesture(Gesture::TYPE_SWIPE);    controller.config().setFloat("Gesture.Swipe.MinLength", 200.0);    controller.config().save();}//Not dispatched when running in a debuggervoid LeapEventListener::onDisconnect(const Controller& controller) {    std::cout << "Disconnected" << std::endl;}void LeapEventListener::onFrame(const Controller& controller) {    std::cout << "New frame available" << std::endl;    Frame frame = controller.frame();    // Process this frame's data...}

你也可以把一个listener的实例加到一个控制器中：
Controller controller;
LeapEventListener listener;
controller.addListener(listener);
每个事件的回调函数在Leap Motion库创建的一个独立进程中被调用，由这个库创建的跟踪数据类是线程安全的，但是你必须确定其他由回调函数访问的应用程序数据可以从线程中安全改变。当你的应用程序方便的话，可以通过Controller轮询帧和状态来避免多线程并发症，而不是用侦听器。

• Device Types

这里有三种Leap Motion硬件的类型：标准的控制器作为独立电脑的外设、嵌入在键盘里的控制器和嵌入在笔记本电脑中的控制器。所有这些设备的性能都是相等的。然而，要知道这些设备从物理上说是非常不同的。比如，嵌入在笔记本电脑的设备无法拔出，而是用键盘快捷键来激活或者不激活。可以通过Device.type()来得到设备的类型。用Controller.devices()来得到相连设备的列表（通常在某个时刻只有一个设备可以被识别）。

译自：https://developer.leapmotion.com/documentation/cpp/devguide/Leap_Controllers.html