[Orxonox-commit 764] r3292 - branches/core4/src/core/input
rgrieder at orxonox.net
rgrieder at orxonox.net
Tue Jul 14 13:59:40 CEST 2009
Author: rgrieder
Date: 2009-07-14 13:59:39 +0200 (Tue, 14 Jul 2009)
New Revision: 3292
Modified:
branches/core4/src/core/input/InputState.cc
branches/core4/src/core/input/InputState.h
Log:
Added documentation for the InputState.
Modified: branches/core4/src/core/input/InputState.cc
===================================================================
--- branches/core4/src/core/input/InputState.cc 2009-07-14 09:50:47 UTC (rev 3291)
+++ branches/core4/src/core/input/InputState.cc 2009-07-14 11:59:39 UTC (rev 3292)
@@ -31,6 +31,7 @@
namespace orxonox
{
+ //! Sets priority of it's a high priority and resizes the handler list
InputState::InputState(const std::string& name, bool bAlwaysGetsInput, bool bTransparent, InputStatePriority priority)
: name_(name)
, bAlwaysGetsInput_(bAlwaysGetsInput)
@@ -46,7 +47,7 @@
else
priority_ = 0;
- handlers_.resize(InputDeviceEnumerator::FirstJoyStick + JoyStickQuantityListener::getJoyStickList().size(), NULL);
+ handlers_.resize(InputDeviceEnumerator::FirstJoyStick + this->getJoyStickList().size(), NULL);
}
bool InputState::isInputDeviceEnabled(unsigned int device)
@@ -57,6 +58,7 @@
return false;
}
+ //! Called by JoyStickQuantityListener upon joy stick adding/removal
void InputState::JoyStickQuantityChanged(const std::vector<JoyStick*>& joyStickList)
{
unsigned int oldSize = handlers_.size();
@@ -68,16 +70,6 @@
bExpired_ = true;
}
- /**
- @brief
- Adds a joy stick handler.
- @param handler
- Pointer to the handler object.
- @param joyStickID
- ID of the joy stick
- @return
- True if added, false otherwise.
- */
bool InputState::setJoyStickHandler(InputHandler* handler, unsigned int joyStick)
{
unsigned device = joyStick + firstJoyStickIndex_s;
@@ -89,36 +81,19 @@
return true;
}
- /**
- @brief
- Adds a joy stick handler.
- @param handler
- Pointer to the handler object.
- @return
- True if added, false if handler already existed.
- */
- bool InputState::setJoyStickHandler(InputHandler* handler)
+ void InputState::setJoyStickHandler(InputHandler* handler)
{
joyStickHandlerAll_ = handler;
for (unsigned int i = firstJoyStickIndex_s; i < handlers_.size(); ++i)
handlers_[i] = handler;
bExpired_ = true;
- return true;
}
- /**
- @brief
- Adds a handler of any kind. dynamic_cast determines to which list it is added.
- @param handler
- Pointer to the handler object.
- @return
- True if added, false if handler already existed.
- */
- bool InputState::setHandler(InputHandler* handler)
+ void InputState::setHandler(InputHandler* handler)
{
setKeyHandler(handler);
setMouseHandler(handler);
- return setJoyStickHandler(handler);
+ setJoyStickHandler(handler);
}
void InputState::entered()
Modified: branches/core4/src/core/input/InputState.h
===================================================================
--- branches/core4/src/core/input/InputState.h 2009-07-14 09:50:47 UTC (rev 3291)
+++ branches/core4/src/core/input/InputState.h 2009-07-14 11:59:39 UTC (rev 3292)
@@ -41,6 +41,7 @@
namespace orxonox
{
+ //! Enumeration wrapper for input state priorities
struct InputStatePriority : OrxEnum<InputStatePriority>
{
OrxEnumConstructors(InputStatePriority);
@@ -54,45 +55,101 @@
static const int Detector = HighPriority + 2;
};
+ /**
+ @brief
+ InputStates allow you to customise the input event targets at runtime.
+
+ The general idea is a stack: Every activated InputState will be pushed on
+ that stack and only the top one gets the input events. This is done for
+ every device (keyboard, mouse, all joy sticks) separately to allow
+ for intance keyboard input capturing for the console while you can still
+ steer a ship with the mouse.
+ There are two exceptions to this behaviour though:
+ - If an InputState is created with the 'Transparent' parameter on, the
+ state will not prevent input from getting to the state below it on the stack.
+ This can be useful for instance if you need to deploy input to multiple
+ handlers: Simply create two InputStates and make the high priority one transparent.
+ - If an InputState is created with the 'AlwaysGetsInput' parameter on, then
+ the state will always receive input as long as it is activated.
+ - Note: If you mark an InputState with both parameters on, then it will
+ not influence ony other InputState at all.
+
+ Priorities
+ **********
+ Every InputState has a priority when on the stack, but mostly this
+ priority is dynamic (InputStatePriority::Dynamic) which means that a state
+ pushed onto the stack will simply have a higher priority than the top one.
+ This behaviour really only applies to normal states that don't have
+ a high priority (InputStatePriority::HighPriority). These 'special' ones
+ are used for features like the KeyDetector or the console. Use with care!
+ */
class _CoreExport InputState : public JoyStickQuantityListener
{
friend class InputManager;
- static const InputDeviceEnumerator::Value keyboardIndex_s = InputDeviceEnumerator::Keyboard;
- static const InputDeviceEnumerator::Value mouseIndex_s = InputDeviceEnumerator::Mouse;
+ //! Marks the index in the handler vector for the keyboard handler
+ static const InputDeviceEnumerator::Value keyboardIndex_s = InputDeviceEnumerator::Keyboard;
+ //! Marks the index in the handler vector for the mouse handler
+ static const InputDeviceEnumerator::Value mouseIndex_s = InputDeviceEnumerator::Mouse;
+ //! Marks the index in the handler vector for the first joy stick handler
static const InputDeviceEnumerator::Value firstJoyStickIndex_s = InputDeviceEnumerator::FirstJoyStick;
public:
+ //! Sets the keyboard event handler (overwrites if there already was one!)
void setKeyHandler (InputHandler* handler)
{ handlers_[keyboardIndex_s] = handler; bExpired_ = true; }
+ //! Sets the mouse event handler (overwrites if there already was one!)
void setMouseHandler (InputHandler* handler)
{ handlers_[mouseIndex_s] = handler; bExpired_ = true; }
+ /**
+ @brief
+ Sets the joy stick event handler for one specific joy stick (overwrites if there already was one!)
+ @return
+ Returns false if the specified device was not found
+ */
bool setJoyStickHandler(InputHandler* handler, unsigned int joyStick);
- bool setJoyStickHandler(InputHandler* handler);
- bool setHandler (InputHandler* handler);
+ //! Sets the joy stick event handler for all joy sticks (overwrites if there already was one!)
+ void setJoyStickHandler(InputHandler* handler);
+ //! Sets an InputHandler to be used for all devices
+ void setHandler (InputHandler* handler);
+ //! Returns the name of the state (which is unique!)
const std::string& getName() const { return name_; }
+ //! Returns the priority of the state (which is unique if != 0)
int getPriority() const { return priority_; }
+ //! Tells whether there a handler installed for a specific device
bool isInputDeviceEnabled(unsigned int device);
+ //! Returns true if the handler situation has changed
bool hasExpired() { return this->bExpired_; }
+ //! Call this if you have applied the changes resulting from changed handlers
void resetExpiration() { bExpired_ = false; }
+ //! Updates one specific device handler with #device#Updated
void update(float dt, unsigned int device);
+ //! Updates all handlers with allDevicesUpdated
void update(float dt);
+ //! Generic function that distributes all 9 button events
template <typename EventType, class Traits>
void buttonEvent(unsigned int device, const typename Traits::ButtonTypeParam button);
+ //! Event handler
void mouseMoved(IntVector2 abs, IntVector2 rel, IntVector2 clippingSize);
+ //! Event handler
void mouseScrolled(int abs, int rel);
+ //! Event handler
void joyStickAxisMoved(unsigned int device, unsigned int axis, float value);
// Functors
+ //! Called when the state is being activated (even if it doesn't get any events afterwards!)
void entered();
+ //! Called upon deactivation of the state
void left();
+ //! Sets a functor to be called upon activation of the state
void setEnterFunctor(Functor* functor) { this->enterFunctor_ = functor; }
+ //! Sets a functor to be called upon deactivation of the state
void setLeaveFunctor(Functor* functor) { this->leaveFunctor_ = functor; }
private:
@@ -101,17 +158,19 @@
void JoyStickQuantityChanged(const std::vector<JoyStick*>& joyStickList);
+ //! Sets the priority (only to be used by the InputManager!)
void setPriority(int priority) { priority_ = priority; }
- const std::string name_;
- const bool bAlwaysGetsInput_;
- const bool bTransparent_;
- int priority_;
- bool bExpired_;
- std::vector<InputHandler*> handlers_;
+ const std::string name_; //!< Name of the state
+ const bool bAlwaysGetsInput_; //!< See class declaration for explanation
+ const bool bTransparent_; //!< See class declaration for explanation
+ int priority_; //!< Current priority (might change)
+ bool bExpired_; //!< See hasExpired()
+ std::vector<InputHandler*> handlers_; //!< Vector with all handlers where the index is the device ID
+ //! Handler to be used for all joy sticks (needs to be saved in case another joy stick gets attached)
InputHandler* joyStickHandlerAll_;
- Functor* enterFunctor_;
- Functor* leaveFunctor_;
+ Functor* enterFunctor_; //!< Functor to be executed on enter
+ Functor* leaveFunctor_; //!< Functor to be executed on leave
};
inline void InputState::update(float dt)
More information about the Orxonox-commit
mailing list