1 //////////////////////////////////////////////////////////// 2 // 3 // SFML - Simple and Fast Multimedia Library 4 // Copyright (C) 2007-2018 Laurent Gomila (laurent@sfml-dev.org) 5 // 6 // This software is provided 'as-is', without any express or implied warranty. 7 // In no event will the authors be held liable for any damages arising from the use of this software. 8 // 9 // Permission is granted to anyone to use this software for any purpose, 10 // including commercial applications, and to alter it and redistribute it freely, 11 // subject to the following restrictions: 12 // 13 // 1. The origin of this software must not be misrepresented; 14 // you must not claim that you wrote the original software. 15 // If you use this software in a product, an acknowledgment 16 // in the product documentation would be appreciated but is not required. 17 // 18 // 2. Altered source versions must be plainly marked as such, 19 // and must not be misrepresented as being the original software. 20 // 21 // 3. This notice may not be removed or altered from any source distribution. 22 // 23 //////////////////////////////////////////////////////////// 24 25 #ifndef SFML_JOYSTICK_HPP 26 #define SFML_JOYSTICK_HPP 27 28 //////////////////////////////////////////////////////////// 29 // Headers 30 //////////////////////////////////////////////////////////// 31 #include <SFML/Window/Export.hpp> 32 #include <SFML/System/String.hpp> 33 34 35 namespace sf 36 { 37 //////////////////////////////////////////////////////////// 38 /// \brief Give access to the real-time state of the joysticks 39 /// 40 //////////////////////////////////////////////////////////// 41 class SFML_WINDOW_API Joystick 42 { 43 public: 44 45 //////////////////////////////////////////////////////////// 46 /// \brief Constants related to joysticks capabilities 47 /// 48 //////////////////////////////////////////////////////////// 49 enum 50 { 51 Count = 8, ///< Maximum number of supported joysticks 52 ButtonCount = 32, ///< Maximum number of supported buttons 53 AxisCount = 8 ///< Maximum number of supported axes 54 }; 55 56 //////////////////////////////////////////////////////////// 57 /// \brief Axes supported by SFML joysticks 58 /// 59 //////////////////////////////////////////////////////////// 60 enum Axis 61 { 62 X, ///< The X axis 63 Y, ///< The Y axis 64 Z, ///< The Z axis 65 R, ///< The R axis 66 U, ///< The U axis 67 V, ///< The V axis 68 PovX, ///< The X axis of the point-of-view hat 69 PovY ///< The Y axis of the point-of-view hat 70 }; 71 72 //////////////////////////////////////////////////////////// 73 /// \brief Structure holding a joystick's identification 74 /// 75 //////////////////////////////////////////////////////////// 76 struct SFML_WINDOW_API Identification 77 { 78 Identification(); 79 80 String name; ///< Name of the joystick 81 unsigned int vendorId; ///< Manufacturer identifier 82 unsigned int productId; ///< Product identifier 83 }; 84 85 //////////////////////////////////////////////////////////// 86 /// \brief Check if a joystick is connected 87 /// 88 /// \param joystick Index of the joystick to check 89 /// 90 /// \return True if the joystick is connected, false otherwise 91 /// 92 //////////////////////////////////////////////////////////// 93 static bool isConnected(unsigned int joystick); 94 95 //////////////////////////////////////////////////////////// 96 /// \brief Return the number of buttons supported by a joystick 97 /// 98 /// If the joystick is not connected, this function returns 0. 99 /// 100 /// \param joystick Index of the joystick 101 /// 102 /// \return Number of buttons supported by the joystick 103 /// 104 //////////////////////////////////////////////////////////// 105 static unsigned int getButtonCount(unsigned int joystick); 106 107 //////////////////////////////////////////////////////////// 108 /// \brief Check if a joystick supports a given axis 109 /// 110 /// If the joystick is not connected, this function returns false. 111 /// 112 /// \param joystick Index of the joystick 113 /// \param axis Axis to check 114 /// 115 /// \return True if the joystick supports the axis, false otherwise 116 /// 117 //////////////////////////////////////////////////////////// 118 static bool hasAxis(unsigned int joystick, Axis axis); 119 120 //////////////////////////////////////////////////////////// 121 /// \brief Check if a joystick button is pressed 122 /// 123 /// If the joystick is not connected, this function returns false. 124 /// 125 /// \param joystick Index of the joystick 126 /// \param button Button to check 127 /// 128 /// \return True if the button is pressed, false otherwise 129 /// 130 //////////////////////////////////////////////////////////// 131 static bool isButtonPressed(unsigned int joystick, unsigned int button); 132 133 //////////////////////////////////////////////////////////// 134 /// \brief Get the current position of a joystick axis 135 /// 136 /// If the joystick is not connected, this function returns 0. 137 /// 138 /// \param joystick Index of the joystick 139 /// \param axis Axis to check 140 /// 141 /// \return Current position of the axis, in range [-100 .. 100] 142 /// 143 //////////////////////////////////////////////////////////// 144 static float getAxisPosition(unsigned int joystick, Axis axis); 145 146 //////////////////////////////////////////////////////////// 147 /// \brief Get the joystick information 148 /// 149 /// \param joystick Index of the joystick 150 /// 151 /// \return Structure containing joystick information. 152 /// 153 //////////////////////////////////////////////////////////// 154 static Identification getIdentification(unsigned int joystick); 155 156 //////////////////////////////////////////////////////////// 157 /// \brief Update the states of all joysticks 158 /// 159 /// This function is used internally by SFML, so you normally 160 /// don't have to call it explicitly. However, you may need to 161 /// call it if you have no window yet (or no window at all): 162 /// in this case the joystick states are not updated automatically. 163 /// 164 //////////////////////////////////////////////////////////// 165 static void update(); 166 }; 167 168 } // namespace sf 169 170 171 #endif // SFML_JOYSTICK_HPP 172 173 174 //////////////////////////////////////////////////////////// 175 /// \class sf::Joystick 176 /// \ingroup window 177 /// 178 /// sf::Joystick provides an interface to the state of the 179 /// joysticks. It only contains static functions, so it's not 180 /// meant to be instantiated. Instead, each joystick is identified 181 /// by an index that is passed to the functions of this class. 182 /// 183 /// This class allows users to query the state of joysticks at any 184 /// time and directly, without having to deal with a window and 185 /// its events. Compared to the JoystickMoved, JoystickButtonPressed 186 /// and JoystickButtonReleased events, sf::Joystick can retrieve the 187 /// state of axes and buttons of joysticks at any time 188 /// (you don't need to store and update a boolean on your side 189 /// in order to know if a button is pressed or released), and you 190 /// always get the real state of joysticks, even if they are 191 /// moved, pressed or released when your window is out of focus 192 /// and no event is triggered. 193 /// 194 /// SFML supports: 195 /// \li 8 joysticks (sf::Joystick::Count) 196 /// \li 32 buttons per joystick (sf::Joystick::ButtonCount) 197 /// \li 8 axes per joystick (sf::Joystick::AxisCount) 198 /// 199 /// Unlike the keyboard or mouse, the state of joysticks is sometimes 200 /// not directly available (depending on the OS), therefore an update() 201 /// function must be called in order to update the current state of 202 /// joysticks. When you have a window with event handling, this is done 203 /// automatically, you don't need to call anything. But if you have no 204 /// window, or if you want to check joysticks state before creating one, 205 /// you must call sf::Joystick::update explicitly. 206 /// 207 /// Usage example: 208 /// \code 209 /// // Is joystick #0 connected? 210 /// bool connected = sf::Joystick::isConnected(0); 211 /// 212 /// // How many buttons does joystick #0 support? 213 /// unsigned int buttons = sf::Joystick::getButtonCount(0); 214 /// 215 /// // Does joystick #0 define a X axis? 216 /// bool hasX = sf::Joystick::hasAxis(0, sf::Joystick::X); 217 /// 218 /// // Is button #2 pressed on joystick #0? 219 /// bool pressed = sf::Joystick::isButtonPressed(0, 2); 220 /// 221 /// // What's the current position of the Y axis on joystick #0? 222 /// float position = sf::Joystick::getAxisPosition(0, sf::Joystick::Y); 223 /// \endcode 224 /// 225 /// \see sf::Keyboard, sf::Mouse 226 /// 227 //////////////////////////////////////////////////////////// 228