1 ////////////////////////////////////////////////////////////
3 // SFML - Simple and Fast Multimedia Library
4 // Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
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.
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:
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.
18 // 2. Altered source versions must be plainly marked as such,
19 // and must not be misrepresented as being the original software.
21 // 3. This notice may not be removed or altered from any source distribution.
23 ////////////////////////////////////////////////////////////
25 #ifndef SFML_JOYSTICK_HPP
26 #define SFML_JOYSTICK_HPP
28 ////////////////////////////////////////////////////////////
30 ////////////////////////////////////////////////////////////
31 #include <SFML/Window/Export.hpp>
32 #include <SFML/System/String.hpp>
37 ////////////////////////////////////////////////////////////
38 /// \brief Give access to the real-time state of the joysticks
40 ////////////////////////////////////////////////////////////
41 class SFML_WINDOW_API Joystick
45 ////////////////////////////////////////////////////////////
46 /// \brief Constants related to joysticks capabilities
48 ////////////////////////////////////////////////////////////
51 Count = 8, ///< Maximum number of supported joysticks
52 ButtonCount = 32, ///< Maximum number of supported buttons
53 AxisCount = 8 ///< Maximum number of supported axes
56 ////////////////////////////////////////////////////////////
57 /// \brief Axes supported by SFML joysticks
59 ////////////////////////////////////////////////////////////
68 PovX, ///< The X axis of the point-of-view hat
69 PovY ///< The Y axis of the point-of-view hat
72 ////////////////////////////////////////////////////////////
73 /// \brief Structure holding a joystick's identification
75 ////////////////////////////////////////////////////////////
80 sf::String name; ///< Name of the joystick
81 unsigned int vendorId; ///< Manufacturer identifier
82 unsigned int productId; ///< Product identifier
85 ////////////////////////////////////////////////////////////
86 /// \brief Check if a joystick is connected
88 /// \param joystick Index of the joystick to check
90 /// \return True if the joystick is connected, false otherwise
92 ////////////////////////////////////////////////////////////
93 static bool isConnected(unsigned int joystick);
95 ////////////////////////////////////////////////////////////
96 /// \brief Return the number of buttons supported by a joystick
98 /// If the joystick is not connected, this function returns 0.
100 /// \param joystick Index of the joystick
102 /// \return Number of buttons supported by the joystick
104 ////////////////////////////////////////////////////////////
105 static unsigned int getButtonCount(unsigned int joystick);
107 ////////////////////////////////////////////////////////////
108 /// \brief Check if a joystick supports a given axis
110 /// If the joystick is not connected, this function returns false.
112 /// \param joystick Index of the joystick
113 /// \param axis Axis to check
115 /// \return True if the joystick supports the axis, false otherwise
117 ////////////////////////////////////////////////////////////
118 static bool hasAxis(unsigned int joystick, Axis axis);
120 ////////////////////////////////////////////////////////////
121 /// \brief Check if a joystick button is pressed
123 /// If the joystick is not connected, this function returns false.
125 /// \param joystick Index of the joystick
126 /// \param button Button to check
128 /// \return True if the button is pressed, false otherwise
130 ////////////////////////////////////////////////////////////
131 static bool isButtonPressed(unsigned int joystick, unsigned int button);
133 ////////////////////////////////////////////////////////////
134 /// \brief Get the current position of a joystick axis
136 /// If the joystick is not connected, this function returns 0.
138 /// \param joystick Index of the joystick
139 /// \param axis Axis to check
141 /// \return Current position of the axis, in range [-100 .. 100]
143 ////////////////////////////////////////////////////////////
144 static float getAxisPosition(unsigned int joystick, Axis axis);
146 ////////////////////////////////////////////////////////////
147 /// \brief Get the joystick information
149 /// \param joystick Index of the joystick
151 /// \return Structure containing joystick information.
153 ////////////////////////////////////////////////////////////
154 static Identification getIdentification(unsigned int joystick);
156 ////////////////////////////////////////////////////////////
157 /// \brief Update the states of all joysticks
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.
164 ////////////////////////////////////////////////////////////
165 static void update();
171 #endif // SFML_JOYSTICK_HPP
174 ////////////////////////////////////////////////////////////
175 /// \class sf::Joystick
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.
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.
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)
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.
209 /// // Is joystick #0 connected?
210 /// bool connected = sf::Joystick::isConnected(0);
212 /// // How many buttons does joystick #0 support?
213 /// unsigned int buttons = sf::Joystick::getButtonCount(0);
215 /// // Does joystick #0 define a X axis?
216 /// bool hasX = sf::Joystick::hasAxis(0, sf::Joystick::X);
218 /// // Is button #2 pressed on joystick #0?
219 /// bool pressed = sf::Joystick::isButtonPressed(0, 2);
221 /// // What's the current position of the Y axis on joystick #0?
222 /// float position = sf::Joystick::getAxisPosition(0, sf::Joystick::Y);
225 /// \see sf::Keyboard, sf::Mouse
227 ////////////////////////////////////////////////////////////