ground/gcs/src/libs/sdlgamepad/sdlgamepad.h

   1 /**
   2  * @internal
   3  *
   4  * This file is part of SDLGamepad.
   5  *
   6  * SDLGamepad is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * SDLGamepad is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
  18  *
  19  * Manuel Blanquett
  20  * mail.nalla@gmail.com
  21  */
  22
  23 #ifndef SDLGAMEPAD_H
  24 #define SDLGAMEPAD_H
  25
  26 #include "sdlgamepad_global.h"
  27
  28 #include <QThread>
  29
  30 /**
  31  * The Axis range that is treated as null.
  32  *
  33  * This is a sort of callibration mechanism for the physical gamepad.
  34  * SDL axis values greater than -NULL_RANGE and smaller than +NULL_RANGE
  35  * will be treated as null.
  36  */
  37 #define NULL_RANGE 2800
  38
  39 /**
  40  * The default tick rate of refreshing the SDL info.
  41  *
  42  * This is the default ms value in the thread method to sleep. If you
  43  * dont set a sleep rate you processor will have a much higher load!
  44  *
  45  * @see SDLGamepad::setTickRate()
  46  */
  47 #define MIN_RATE   10
  48
  49 /**
  50  * Axis enumeration.
  51  *
  52  * This enumeration can be used to have a more readable code for
  53  * dealing with axes numbers. Up to 10 axes are supported. That should
  54  * be more than enough for every gamepad out there.
  55  */
  56 enum AxisNumber {
  57     AXIS_1,
  58     AXIS_2,
  59     AXIS_3,
  60     AXIS_4,
  61     AXIS_5,
  62     AXIS_6,
  63     AXIS_7,
  64     AXIS_8,
  65     AXIS_9
  66 };
  67
  68 /**
  69  * Button enumeration.
  70  *
  71  * This enumeration is uesed internaly in the singal for the buttons.
  72  * Be aware that you need to register this enumeration with
  73  * qRegisterMetaType when you want to use the signal buttonState with
  74  * queued connections.
  75  *
  76  * @see SDLGamepad::buttonState()
  77  */
  78 enum ButtonNumber {
  79     BUTTON_01,
  80     BUTTON_02,
  81     BUTTON_03,
  82     BUTTON_04,
  83     BUTTON_05,
  84     BUTTON_06,
  85     BUTTON_07,
  86     BUTTON_08,
  87     BUTTON_09,
  88     BUTTON_10,
  89     BUTTON_11,
  90     BUTTON_12,
  91     BUTTON_13,
  92     BUTTON_14,
  93     BUTTON_15,
  94     BUTTON_16,
  95     BUTTON_17,
  96     BUTTON_18,
  97     BUTTON_19,
  98     BUTTON_20
  99 };
 100
 101 /**
 102  * A typedef for qRegisterMetaType().
 103  *
 104  * This typedef is used to int the signal axesValues. You need this if
 105  * you want to use the signal with queued connections, because you
 106  * can not register QList<qint16> directly.
 107  *
 108  * @see SDLGamepad::axisValues()
 109  */
 110 typedef QList<qint16> QListInt16;
 111
 112 class SDLGamepadPrivate;
 113
 114 /**
 115  * A class for communication with a sdl gamepad.
 116  *
 117  * This class inherts QThread. The run method will look for new button
 118  * states via SDL function calls and emit signals for every button if
 119  * the state of the button has changed. It will also emit signals with
 120  * the current axes values. The default sleep after this two tasks is
 121  * 10 milliseconds.
 122  *
 123  * @author Manuel Blanquett (mail.nalla@gmail.com)
 124  * @version 1.0
 125  * @date 2009
 126  */
 127 class SDLGAMEPADSHARED_EXPORT SDLGamepad : public QThread {
 128     Q_OBJECT
 129
 130 public:
 131
 132     /**
 133      * Class constructor.
 134      *
 135      * Some private variables will be initzialized here and the tick
 136      * rate will be set to MIN_RATE.
 137      */
 138     SDLGamepad();
 139
 140     /**
 141      * Class deconstructor.
 142      *
 143      * The SDL gamepad will be cracefully closed. After that the SDL
 144      * system will be terminated.
 145      */
 146     ~SDLGamepad();
 147
 148     /**
 149      * Implemented virtual run method from QThread.
 150      *
 151      * The base of operation so to speak. Very abstract this method
 152      * does the following:
 153      * - refresh SDL information
 154      * - emit signals
 155      * - sleep tickrate
 156      */
 157     void run();
 158
 159     /**
 160      * Getter method for the axis count.
 161      *
 162      * This class member retunrs the actual number of axes present
 163      * on the currently opened gamepad. If no gamepad is present after
 164      * setting a new one with setGamepad() the value will be -1. This
 165      * is also the default value.
 166      */
 167     qint16 getAxes();
 168
 169     /**
 170      * Getter method for the button count.
 171      *
 172      * This class member retunrs the actual number of buttons present
 173      * on the currently opened gamepad. If no gamepad is present after
 174      * setting a new one with setGamepad() the value will be -1. This
 175      * is also the default value.
 176      */
 177     qint16 getButtons();
 178
 179 public slots:
 180
 181     /**
 182      * Init the SDL system and set up gamepad.
 183      *
 184      * You have to connect to the gamepads signal if you want to
 185      * receive the gamepads present in the SDL system.
 186      *
 187      * @see gamepads()
 188      * @return True if the initzialisation was successfull.
 189      */
 190     bool init();
 191
 192     /**
 193      * Exiting the thread.
 194      *
 195      * This is a overwritten method from QThread to gracefully end the
 196      * execution of this thread. You should connect the QT App's
 197      * aboutToQuit signal with this.
 198      */
 199     void quit();
 200
 201     /**
 202      * Change the default tickrate.
 203      *
 204      * You can change the tickrate at any time. So you can change the
 205      * thread sleep dynamicly accordingly to your application's state.
 206      *
 207      * @param ms The new tickrate in milliseconds.
 208      */
 209     void setTickRate(qint16 ms);
 210
 211     /**
 212      * Change the active gamepad.
 213      *
 214      * You can set active gamepad here. The first gamepad to be
 215      * activaed is 0. If the gamepad could not be activated a qCritical
 216      * will be printed and false is returned.
 217      *
 218      * @see gamepads()
 219      * @param index The new gamepad by index.
 220      * @return True if the gamepad was successfully changed.
 221      */
 222     bool setGamepad(qint16 index);
 223
 224 private:
 225
 226     /**
 227      * Get new axes information from the SDL system.
 228      *
 229      * This class member is called from the run method to ask the SDL
 230      * system for new axes values. Afterwords those values are emitted
 231      * via the axesValues signal.
 232      *
 233      * @see run()
 234      * @see axesValues()
 235      */
 236     void updateAxes();
 237
 238     /**
 239      * Get new button information from the SDL system.
 240      *
 241      * This class member is called from the run method to ask the SDL
 242      * system for new button states. If changed, the states are will be
 243      * emitted via the buttonState signal.
 244      *
 245      * @see run()
 246      * @see buttonState()
 247      */
 248     void updateButtons();
 249
 250     /**
 251      * Variable to control thread.
 252      *
 253      * This class member variable is false at construction time. If
 254      * the SDL init was successful it will be set to true. The quit
 255      * slot will false it again.
 256      *
 257      * @see quit()
 258      */
 259     bool loop;
 260
 261     /**
 262      * Number of buttons.
 263      *
 264      * If a new gamepad is opened via SDL the acutal button count is
 265      * saved in this class member to be used in control statements.
 266      */
 267     qint16 buttons;
 268
 269     /**
 270      * Number of axes.
 271      *
 272      * If a new gamepad is opened via SDL the acutal axes count is
 273      * saved in this class member to be used in control statements.
 274      */
 275     qint16 axes;
 276
 277     /**
 278      * The tickrate.
 279      *
 280      * A variable to be used in the run method to sleep after getting
 281      * and emitting SDL information.
 282      *
 283      * @see run()
 284      */
 285     qint16 tick;
 286
 287     /**
 288      * SDL_Joystick index.
 289      *
 290      * A variable that holds the SDL_Joystick index of the currently
 291      * opend SDL_Joystick Object.
 292      */
 293     qint16 index;
 294
 295     /**
 296      * A QList to store the current button states.
 297      *
 298      * This list stores the current states of all available buttons.
 299      */
 300     QList<qint16> buttonStates;
 301
 302     /**
 303      * Variable that holds private members.
 304      */
 305     SDLGamepadPrivate *priv;
 306
 307 signals:
 308
 309     /**
 310      * A signal that emitts the number of gamepads present in SDL.
 311      *
 312      * This signal is emitted in the init slot, so you need connect to
 313      * this bevore you call init! You get a quint8 with the number of
 314      * gamepads currently present in the SDL system. The first gamepad
 315      * will be opened at default. You can set another gamepad with the
 316      * setGamepad slot. If you have 5 gamepads in the system you need
 317      * to use 0-4 in the setGamepad slot.
 318      *
 319      * @see setGamepad()
 320      * @param count The number of gamepads present in SDL.
 321      */
 322     void gamepads(quint8 count);
 323
 324     /**
 325      * A signal that emitts the current state of a gamepad button.
 326      *
 327      * You can connect to this signal to receive the state of the
 328      * gamepad buttons. The states are not pressed at default. If the
 329      * first pressed state will occur within SDL you will get a signal.
 330      * You will get another signal if you release the button. With
 331      * every tick the states will be reread from the SDL system.
 332      *
 333      * @param number A ButtonNumber enum value.
 334      * @param pressed A bool value wether the button is pressed or not.
 335      */
 336     void buttonState(ButtonNumber number, bool pressed);
 337
 338     /**
 339      * A signal that emitts the current values of the gamepad axes.
 340      *
 341      * You can connect to this signal to receive the values of the
 342      * gamepad axes. Unlike the button signal, this signal is thrown
 343      * with every tick. You will get a QListInt16 containing the value
 344      * of every present axis in a QList.
 345      *
 346      * @see QListInt16
 347      * @param values A QListInt16 Type containing all axes values.
 348      */
 349     void axesValues(QListInt16 values);
 350 };
 351
 352 #endif // SDLGAMEPAD_H