xbmc/input/joysticks/IInputHandler.h

   1 /*
   2  *      Copyright (C) 2014-2016 Team Kodi
   3  *      http://kodi.tv
   4  *
   5  *  This Program is free software; you can redistribute it and/or modify
   6  *  it under the terms of the GNU General Public License as published by
   7  *  the Free Software Foundation; either version 2, or (at your option)
   8  *  any later version.
   9  *
  10  *  This Program is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  *  GNU General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU General Public License
  16  *  along with this Program; see the file COPYING.  If not, see
  17  *  <http://www.gnu.org/licenses/>.
  18  *
  19  */
  20 #pragma once
  21
  22 #include "JoystickTypes.h"
  23
  24 #include <string>
  25
  26 namespace JOYSTICK
  27 {
  28   class IInputReceiver;
  29
  30   /*!
  31    * \brief Interface for handling input events for game controllers
  32    */
  33   class IInputHandler
  34   {
  35   public:
  36     IInputHandler(void) : m_receiver(nullptr) { }
  37
  38     virtual ~IInputHandler(void) { }
  39
  40     /*!
  41      * \brief The add-on ID of the game controller associated with this input handler
  42      *
  43      * \return The ID of the add-on extending kodi.game.controller
  44      */
  45     virtual std::string ControllerID(void) const = 0;
  46
  47     /*!
  48      * \brief Return true if the input handler accepts the given feature
  49      *
  50      * \param feature A feature belonging to the controller specified by ControllerID()
  51      *
  52      * \return True if the feature is used for input, false otherwise
  53      */
  54     virtual bool HasFeature(const FeatureName& feature) const = 0;
  55
  56     /*!
  57      * \brief Return true if the input handler is currently accepting input
  58      */
  59     virtual bool AcceptsInput(void) = 0;
  60
  61     /*!
  62      * \brief Get the type of input handled by the specified feature
  63      *
  64      * \return INPUT_TYPE::DIGITAL for digital buttons, INPUT::ANALOG for analog
  65      *         buttons, or INPUT::UNKNOWN otherwise
  66      */
  67     virtual INPUT_TYPE GetInputType(const FeatureName& feature) const = 0;
  68
  69     /*!
  70      * \brief A digital button has been pressed or released
  71      *
  72      * \param feature      The feature being pressed
  73      * \param bPressed     True if pressed, false if released
  74      *
  75      * \return True if the event was handled otherwise false
  76      */
  77     virtual bool OnButtonPress(const FeatureName& feature, bool bPressed) = 0;
  78
  79     /*!
  80     * \brief A digital button has been pressed for more than one event frame
  81     *
  82     * \param feature      The feature being held
  83     * \param holdTimeMs   The time elapsed since the initial press (ms)
  84     *
  85     * If OnButtonPress() returns true for the initial press, then this callback
  86     * is invoked on subsequent frames until the button is released.
  87     */
  88     virtual void OnButtonHold(const FeatureName& feature, unsigned int holdTimeMs) = 0;
  89
  90     /*!
  91      * \brief An analog button (trigger or a pressure-sensitive button) has changed state
  92      *
  93      * \param feature      The feature changing state
  94      * \param magnitude    The button pressure or trigger travel distance in the
  95      *                     closed interval [0, 1]
  96      *
  97      * \return True if the event was handled otherwise false
  98      */
  99     virtual bool OnButtonMotion(const FeatureName& feature, float magnitude) = 0;
 100
 101     /*!
 102      * \brief An analog stick has moved
 103      *
 104      * \param feature      The analog stick being moved
 105      * \param x            The x coordinate in the closed interval [-1, 1]
 106      * \param y            The y coordinate in the closed interval [-1, 1]
 107      * \param motionTimeMs The time elapsed since this analog stick was centered,
 108      *                     or 0 if the analog stick is centered
 109      *
 110      * \return True if the event was handled otherwise false
 111      */
 112     virtual bool OnAnalogStickMotion(const FeatureName& feature, float x, float y, unsigned int motionTimeMs = 0) = 0;
 113
 114     /*!
 115      * \brief An accelerometer's state has changed
 116      *
 117      * \param feature      The accelerometer being accelerated
 118      * \param x            The x coordinate in the closed interval [-1, 1]
 119      * \param y            The y coordinate in the closed interval [-1, 1]
 120      * \param z            The z coordinate in the closed interval [-1, 1]
 121      *
 122      * \return True if the event was handled otherwise false
 123      */
 124     virtual bool OnAccelerometerMotion(const FeatureName& feature, float x, float y, float z) { return false; }
 125
 126     // Input receiver interface
 127     void SetInputReceiver(IInputReceiver* receiver) { m_receiver = receiver; }
 128     void ResetInputReceiver(void) { m_receiver = nullptr; }
 129     IInputReceiver* InputReceiver(void) { return m_receiver; }
 130
 131   private:
 132     IInputReceiver* m_receiver;
 133   };
 134 }