Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Jul 14, 2009, 1:59:39 PM (15 years ago)
Author:
rgrieder
Message:

Added documentation for the InputState.

Location:
code/branches/core4/src/core/input
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • code/branches/core4/src/core/input/InputState.cc

    r3288 r3292  
    3232namespace orxonox
    3333{
     34    //! Sets priority of it's a high priority and resizes the handler list
    3435    InputState::InputState(const std::string& name, bool bAlwaysGetsInput, bool bTransparent, InputStatePriority priority)
    3536        : name_(name)
    … …  
    4748            priority_ = 0;
    4849
    49         handlers_.resize(InputDeviceEnumerator::FirstJoyStick + JoyStickQuantityListener::getJoyStickList().size(), NULL);
     50        handlers_.resize(InputDeviceEnumerator::FirstJoyStick + this->getJoyStickList().size(), NULL);
    5051    }
    5152
    … …  
    5859    }
    5960
     61    //! Called by JoyStickQuantityListener upon joy stick adding/removal
    6062    void InputState::JoyStickQuantityChanged(const std::vector<JoyStick*>& joyStickList)
    6163    {
    … …  
    6971    }
    7072
    71     /**
    72     @brief
    73         Adds a joy stick handler.
    74     @param handler
    75         Pointer to the handler object.
    76     @param joyStickID
    77         ID of the joy stick
    78     @return
    79         True if added, false otherwise.
    80     */
    8173    bool InputState::setJoyStickHandler(InputHandler* handler, unsigned int joyStick)
    8274    {
    … …  
    9082    }
    9183
    92     /**
    93     @brief
    94         Adds a joy stick handler.
    95     @param handler
    96         Pointer to the handler object.
    97     @return
    98         True if added, false if handler already existed.
    99     */
    100     bool InputState::setJoyStickHandler(InputHandler* handler)
     84    void InputState::setJoyStickHandler(InputHandler* handler)
    10185    {
    10286        joyStickHandlerAll_ = handler;
    … …  
    10488            handlers_[i] = handler;
    10589        bExpired_ = true;
    106         return true;
    10790    }
    10891
    109     /**
    110     @brief
    111         Adds a handler of any kind. dynamic_cast determines to which list it is added.
    112     @param handler
    113         Pointer to the handler object.
    114     @return
    115         True if added, false if handler already existed.
    116     */
    117     bool InputState::setHandler(InputHandler* handler)
     92    void InputState::setHandler(InputHandler* handler)
    11893    {
    11994        setKeyHandler(handler);
    12095        setMouseHandler(handler);
    121         return setJoyStickHandler(handler);
     96        setJoyStickHandler(handler);
    12297    }
    12398

  • code/branches/core4/src/core/input/InputState.h

    r3288 r3292  
    4242namespace orxonox
    4343{
     44    //! Enumeration wrapper for input state priorities
    4445    struct InputStatePriority : OrxEnum<InputStatePriority>
    4546    {
    … …  
    5556    };
    5657
     58    /**
     59    @brief
     60        InputStates allow you to customise the input event targets at runtime.
     61
     62        The general idea is a stack: Every activated InputState will be pushed on
     63        that stack and only the top one gets the input events. This is done for
     64        every device (keyboard, mouse, all joy sticks) separately to allow
     65        for intance keyboard input capturing for the console while you can still
     66        steer a ship with the mouse.
     67        There are two exceptions to this behaviour though:
     68        - If an InputState is created with the 'Transparent' parameter on, the
     69          state will not prevent input from getting to the state below it on the stack.
     70          This can be useful for instance if you need to deploy input to multiple
     71          handlers: Simply create two InputStates and make the high priority one transparent.
     72        - If an InputState is created with the 'AlwaysGetsInput' parameter on, then
     73          the state will always receive input as long as it is activated.
     74        - Note: If you mark an InputState with both parameters on, then it will
     75          not influence ony other InputState at all.
     76
     77        Priorities
     78        **********
     79        Every InputState has a priority when on the stack, but mostly this
     80        priority is dynamic (InputStatePriority::Dynamic) which means that a state
     81        pushed onto the stack will simply have a higher priority than the top one.
     82        This behaviour really only applies to normal states that don't have
     83        a high priority (InputStatePriority::HighPriority). These 'special' ones
     84        are used for features like the KeyDetector or the console. Use with care!
     85    */
    5786    class _CoreExport InputState : public JoyStickQuantityListener
    5887    {
    5988        friend class InputManager;
    6089
    61         static const InputDeviceEnumerator::Value keyboardIndex_s      = InputDeviceEnumerator::Keyboard;
    62         static const InputDeviceEnumerator::Value mouseIndex_s         = InputDeviceEnumerator::Mouse;
     90        //! Marks the index in the handler vector for the keyboard handler
     91        static const InputDeviceEnumerator::Value keyboardIndex_s = InputDeviceEnumerator::Keyboard;
     92        //! Marks the index in the handler vector for the mouse handler
     93        static const InputDeviceEnumerator::Value mouseIndex_s = InputDeviceEnumerator::Mouse;
     94        //! Marks the index in the handler vector for the first joy stick handler
    6395        static const InputDeviceEnumerator::Value firstJoyStickIndex_s = InputDeviceEnumerator::FirstJoyStick;
    6496
    6597    public:
     98        //! Sets the keyboard event handler (overwrites if there already was one!)
    6699        void setKeyHandler     (InputHandler* handler)
    67100            { handlers_[keyboardIndex_s] = handler; bExpired_ = true; }
     101        //! Sets the mouse event handler (overwrites if there already was one!)
    68102        void setMouseHandler   (InputHandler* handler)
    69103            { handlers_[mouseIndex_s]    = handler; bExpired_ = true; }
     104        /**
     105        @brief
     106            Sets the joy stick event handler for one specific joy stick (overwrites if there already was one!)
     107        @return
     108            Returns false if the specified device was not found
     109        */
    70110        bool setJoyStickHandler(InputHandler* handler, unsigned int joyStick);
    71         bool setJoyStickHandler(InputHandler* handler);
    72         bool setHandler        (InputHandler* handler);
    73 
     111        //! Sets the joy stick event handler for all joy sticks (overwrites if there already was one!)
     112        void setJoyStickHandler(InputHandler* handler);
     113        //! Sets an InputHandler to be used for all devices
     114        void setHandler        (InputHandler* handler);
     115
     116        //! Returns the name of the state (which is unique!)
    74117        const std::string& getName() const { return name_; }
     118        //! Returns the priority of the state (which is unique if != 0)
    75119        int getPriority()            const { return priority_; }
    76120
     121        //! Tells whether there a handler installed for a specific device
    77122        bool isInputDeviceEnabled(unsigned int device);
    78123
     124        //! Returns true if the handler situation has changed
    79125        bool hasExpired()      { return this->bExpired_; }
     126        //! Call this if you have applied the changes resulting from changed handlers
    80127        void resetExpiration() { bExpired_ = false; }
    81128
     129        //! Updates one specific device handler with #device#Updated
    82130        void update(float dt, unsigned int device);
     131        //! Updates all handlers with allDevicesUpdated
    83132        void update(float dt);
    84133
     134        //! Generic function that distributes all 9 button events
    85135        template <typename EventType, class Traits>
    86136        void buttonEvent(unsigned int device, const typename Traits::ButtonTypeParam button);
    87137
     138        //! Event handler
    88139        void mouseMoved(IntVector2 abs, IntVector2 rel, IntVector2 clippingSize);
     140        //! Event handler
    89141        void mouseScrolled(int abs, int rel);
     142        //! Event handler
    90143        void joyStickAxisMoved(unsigned int device, unsigned int axis, float value);
    91144
    92145        // Functors
     146        //! Called when the state is being activated (even if it doesn't get any events afterwards!)
    93147        void entered();
     148        //! Called upon deactivation of the state
    94149        void left();
     150        //! Sets a functor to be called upon activation of the state
    95151        void setEnterFunctor(Functor* functor) { this->enterFunctor_ = functor; }
     152        //! Sets a functor to be called upon deactivation of the state
    96153        void setLeaveFunctor(Functor* functor) { this->leaveFunctor_ = functor; }
    97154
    … …  
    102159        void JoyStickQuantityChanged(const std::vector<JoyStick*>& joyStickList);
    103160
     161        //! Sets the priority (only to be used by the InputManager!)
    104162        void setPriority(int priority) { priority_ = priority; }
    105163
    106         const std::string           name_;
    107         const bool                  bAlwaysGetsInput_;
    108         const bool                  bTransparent_;
    109         int                         priority_;
    110         bool                        bExpired_;
    111         std::vector<InputHandler*>  handlers_;
     164        const std::string           name_;                  //!< Name of the state
     165        const bool                  bAlwaysGetsInput_;      //!< See class declaration for explanation
     166        const bool                  bTransparent_;          //!< See class declaration for explanation
     167        int                         priority_;              //!< Current priority (might change)
     168        bool                        bExpired_;              //!< See hasExpired()
     169        std::vector<InputHandler*>  handlers_;              //!< Vector with all handlers where the index is the device ID
     170        //! Handler to be used for all joy sticks (needs to be saved in case another joy stick gets attached)
    112171        InputHandler*               joyStickHandlerAll_;
    113         Functor*                    enterFunctor_;
    114         Functor*                    leaveFunctor_;
     172        Functor*                    enterFunctor_;          //!< Functor to be executed on enter
     173        Functor*                    leaveFunctor_;          //!< Functor to be executed on leave
    115174    };
    116175
Note: See TracChangeset for help on using the changeset viewer.