Leap::Controller Class Reference 控制器类参考

简要说明（由于本人英语水平真的很烂，文里漏洞百出，欢迎批评指正）

点击查看原文

Controller类是你访问Leap Motion控制器的主要接口

继承 Leap::Interface

公共类型

enum PolicyFlag { POLICY_DEFAULT = 0, POLICY_BACKGROUND_FRAMES = (1 << 0) }

所支持的控制器（Controller）的模式（Policy）

注：这里的Policy翻译成什么比较合适呢？暂且翻译为模式，以后想到好的再改

公有成员函数

---

        bool      addListener (Listener &listener)

                    给这个Controller添加一个监听器

---

     Config      config () const

                    返回一个Config对象，你可以用它来查询Leap Motion系统的配置信息

---

                    Controller ()

                    构造一个Controller 对象

---

                    Controller (Listener &listener)

                    构造一个Controller 对象

---

DeviceList      devices () const

                    当前连接并识别到的Leap Motion设备的列表

---

        void      enableGesture (Gesture::Type type, bool enable=true) const

                    启用或者禁用指定的手势类型的报告

---

     Frame      frame (int history=0) const

                   从Leap Motion软件返回跟踪数据的一帧

---

       bool       hasFocus () const

                    报告这个应用程序是否是获得焦点的、前台的应用程序

---

       bool       isConnected () const

                    报告这个Controller是否连接到了Leap Motion服务，Leap Motion硬件是否插上了

---

       bool       isGestureEnabled (Gesture::Type type) const

                    报告一个特定的手势类型是否开启了

---

PolicyFlay       policyFlags () const

                    获得当前的模式设置

---

      bool        removeListener (Listener &listener)

                    从监听器列表中移除一个会接收Leap Motion事件的监听器

---

      void        setPolicyFlags (PolicyFlag flags) const

                    请求改变模式

---

详细说明

Controller类是你访问Leap Motion控制器的主要接口。

创建这个Controller类的一个实例来访问跟踪的帧数据和配置信息。使用函数Controller::frame()，帧数据能被在任何时候轮询。调用frame()或者frame(0)来获取当前的一帧。设置 history 参数为一个正整数来访问之前的帧。一个Controller对象存储了至多60个历史（之前的）帧。

轮询对一个已经有内在的更新循环的应用程序来说是一个合适的策略，例如一个游戏。你也可以添加一个 Leap::Listener的子类的实例到Controller上，来处理当事件发生时候的此事件。Controller调度事件给监听器，在初始化和退出时，在连接变化时，当应用程序获得和丢失OS的输入焦点时，和当一个新的跟踪数据的帧获得时。当这些事件发生的时候，Controller对象调用在监听器子类中定义的相应的回调函数。

当跟踪到的帧数据可用时，访问它们

1、实现Listener类的一个子类，并复写 Listener::onFrame()函数

2、在你的 Listener::onFrame()函数中，调用 Controller::frame() 函数来访问跟踪数据的最新的一帧

3、为了开始接收帧，创建一个Controller对象，并添加Listener子类的一个实例到Controller::addListener() 函数

当一个Listener子类的实例被添加到Controller对象后，它将调用 Listener::onInit() 函数，当这个监听器已经准备好使用的时候。当在controller和Leap Motion软件之间的一个连接建立后，这个controller调用 Listener::onConnect() 函数。在这一时刻点，你的应用程序将要开始接收数据帧。每当一个新的帧可获得的时候，controller就调用 Listener::onFrame()函数。如果这个controller丢失了它和Leap Motion软件或者设备的连接（不管什么原因），它将调用Listener::onDisconnect() 函数。如果这个监听器被从controller中移除了，或者这个controller销毁了，它将调用 Listener::onExit() 函数。在这一时刻点，除非监听器被再次添加到其他controller上，它就会不再接收跟踪到的数据帧了。

这个controller对象是多线程的，在它的独立线程中调用监听器的函数，而不是在一个应用程序线程中。

Since

1.0

枚举成员文档

enum Leap::Controller::PolicyFlag

所支持的controller模式

当前，唯一支持的模式是后台帧模式，它确定你的应用程序是否接收跟踪到的数据帧，当它不是获得焦点的、前台的应用程序的时候。

Since

1.0

枚举值：

         POLICY_DEFAULT            默认的模式                                             

                                       Since

                                                 1.0

      POLICY_BACKGROUND_FRAMES            接收后台帧

                                                         Since

                                                         1.0

构造函数和析构函数文档

Leap::Controller::Controller()

构造一个controller对象。

当创建一个controller对象的时候，你可以可选择的传递一个Leap::Listener子类的实例作为参数。或者，你可以使用 Controller::addListener() 函数添加一个监听器。

Since

1.0

Leap::Controller::Controller(Listener & listener)

构造一个controller对象。

当创建一个controller对象的时候，你可以可选择的传递一个Leap::Listener子类的实例作为参数。或者，你可以使用 Controller::addListener() 函数添加一个监听器。

SampleListener listenerSubclass;
Controller leapController = Controller(listenerSubclass);

参数：

listener   Leap::Listener的一个实例，它实现了你在应用程序中要处理Leap Motion事件的回调函数。

Since

1.0

成员函数文档

bool  Leap::Controller::addListener(Listener & listener)

添加一个监听器到这个controller中。

这个controller分派Leap Motion事件到每个相关的监听器。在哪一个监听器中回调函数被调用的顺序是任意的。如果你传递一个监听器到controller的构造函数中去，它将被自动的添加到这个列表中，并且能够使用 Controller::removeListener() 函数将它移除。

SampleListener listener;
controller.addListener(listener);

参数：

listener   Leap::Listener的一个实例，它实现了你在应用程序中要处理Leap Motion事件的回调函数。

返回：

是否这个监听器被成功的添加到了监听器列表中。

Since

1.0

Config Leap::Controller::config()const

返回一个Config对象，你可以使用它查询Leap Motion系统的配置信息。

controller.config().setFloat("Gesture.Circle.MinRadius",15);
controller.config().setFloat("Gesture.Circle.MinArc",1.7);
bool saved = controller.config().save();

Since

1.0

DeviceList Leap::Controller::devices()const

当前连接并识别到的Leap Motion设备的列表。

列表中的Device对象描述了例如范围和跟踪量等信息。

DeviceList connectedLeaps = controller.devices();

目前，Leap Motion Controller 只能够识别一个单独的设备。

Since

1.0

void Leap::Controller::enableGesture(Gesture::Type type,bool enable=ture)const

启用或者禁用指定的手势类型的报告。

默认的，所有的手势类型是禁用的。当禁用时，被禁用的手势类型将不会被报告，并且将不会在手势列表的帧中出现。

controller.enableGesture(Gesture::Type::TYPE_CIRCLE);

作为一种对性能的优化，最好只启用识别在你的应用程序中使用到的手势类型。

参数：

type   启用或者禁用的手势类型。必须是 Gesture::Type 枚举值中的成员。

enable  True,将启用这个指定的手势类型。False,禁用。

参见：

Controller::isGestureEnabled()

Since

1.0

Frame Leap::Controller::frame(int history = 0)const

从Leap Motion软件返回跟踪数据的一帧.

使用可选的参数history来指定检索某一个帧。调用frame()或者frame(0)来访问最新的一个帧；调用frame(1)来访问之前的一个帧，等等。如果你使用的一个history数值比存储的帧的总数大，那么controller返回一个无效帧。

if(controller.isConnected())//controller是一个controller对象
{
    Frame frame = controller.frame();//最新的一帧
    Frame previous= controller.frame(1);//之前的一帧
}

你可以在你的监听器的实现中调用这个函数在Leap Motion 帧率上来获得帧。

class FrameListener : Leap::Listener
    {
        void onFrame(Controller &controller)
        {
            Frame frame = controller.frame(); //最新的一帧
            Frame previous = controller.frame(1); //之前的一帧//...
        }
    };

参数：

history   要返回的帧的序号，从最新的一帧（0）开始向后计数，直到最大的序号（59）。

返回：

特定的帧；或者，如果没有指定history的值，返回最新的一帧。如果一个帧没有在指定的历史位置获得，那么返回一个无效帧。

Since

1.0

bool Leap::Controller::hasFocus()const

报告这个应用程序是否是获得焦点的、前台的应用程序.

默认的，当你的应用程序能够获得操作系统的输入焦点的时候，它才能够从Leap Motion控制器中获得跟踪信息。当你的应用程序在后台是如果获得跟踪数据，那么这个后台帧模式标志必须被设置。

if(controller.hasFocus()){
    //执行操作需要应用程序获得焦点
}

返回：

True, 如果应用程序获得了焦点；否则返回false。

参见：

Controller::setPolicyFlags()

Since

1.0

bool Leap::Controller::isConnected()const

报告这个Controller是否连接到了Leap Motion服务，Leap Motion硬件是否插上了.

当你第一次创建controller对象的时候，isConnected()返回false。当controller完成了初始化并且连接到了Leap Motion 软件的之后，如果Leap Motion硬件被插上了，isConnected()返回true。

你可以选择使用一个监听器实例来处理连接事件，或者轮询isConnected()函数，如果你需要在执行某些操作之前等待你的应用程序连接到Leap Motion软件

if(controller.isConnected()){
    //执行操作需要一个已连接的contr
}

返回：

True,如果已经连接；否则返回false。

Since

1.0

bool Leap::Controller::isGestureEnabled(Gesture::Type type)const

报告一个特定的手势类型是否启用了。

if(!controller.isGestureEnabled(Gesture::Type::TYPE_SWIPE)){
    controller.enableGesture(Gesture::Type::TYPE_SWIPE);
}

返回：

True,如果这个指定的类型启用了；否则返回false。

参见：

Controller::enableGesture()

Since

1.0

PolicyFlag Leap::Controller::policyFlags()const

获得当前的模式设置。

使用这个函数来确定目前的模式状态。请记住，设置一个模式标志是异步的，所以在调用setPolicyFlag()之后改变不能立即生效。另外，一个模式请求可以被用户拒绝。你应该经常设置你的应用程序在启动时请求的模式标志，并且在适当的时间之后检查模式改变请求是否成功了。

如果controller对象没有连接到Leap Motion 软件上，那么默认的模式状态将会被返回。

if (controller.policyFlags() != Controller::PolicyFlag::POLICY_BACKGROUND_FRAMES) {
    controller.setPolicyFlags(Controller::PolicyFlag::POLICY_BACKGROUND_FRAMES);
}

返回：

当前的模式标志。

Since

1.0

bool Leap::Controller::removeListener(Listener & listener)

从监听器列表中移除一个会接收Leap Motion事件的监听器.

一个监听器必须被移除，如果他的生命长度比它要监听的controller短。

SampleListener listenerObject;
leapController.addListener(listenerObject);
// ... much later
leapController.removeListener(listenerObject);

参数：

listener  将被移除的监听器

返回：

是否这个监听器被成功的从监听器列表中移除。

Since

1.0

void Leap::Controller::setPolicyFlags(PolicyFlag flags)const

请求改变模式.

一个改变模式的请求受用户的批准，并且一个模式可以通过用户在任何时候被改变（使用Leap Motion设置对话框）。所需要的模式标志必须每次在一个应用程序运行时被设置。

模式的改变完全是异步的，因为它们受用户批准，并且不会完全成功。在一段合适的时间之后，调用Controller::policyFlags() 函数来检测是否改变被接受了。

目前，后台帧模式是唯一的支持模式。后台帧模式确定是否一个应用程序在后台的时候还会接收跟踪到的数据帧。默认的，Leap Motion 软件只发送跟踪到的数据帧到前台的应用程序。只有当应用程序需要这项能力的时候才会去请求后台帧模式。

这时，你可以使用Leap Motion 设置对话框来全局的启用或者禁用后台帧模式。然而，每一个应用程序当在后台的时候需要跟踪到的数据，必须也使用这个函数设置模式标志。

这个函数可以在controller对象连接之前被调用，但是这个请求将会在controller连接之后被发送到Leap Motion软件。

controller.setPolicyFlags(Controller::PolicyFlag::POLICY_BACKGROUND_FRAMES);

参数：

flags  一个模式标志，表明要被请求的模式

Since

1.0