Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Jul 13, 2009, 1:57:53 PM (15 years ago)
Author:
rgrieder
Message:

Adjusted InputManager documentation.

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

Legend:

Unmodified
Added
Removed

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

    r3279 r3281  
    3030@file
    3131@brief
    32     Implementation of the InputManager that captures all the input from OIS
    33     and redirects it to handlers.
    34  */
     32    Implementation of the InputManager and a static variable from the InputHandler.
     33*/
    3534
    3635#include "InputManager.h"
    … …  
    6059namespace orxonox
    6160{
    62     // TODO: Add console commands again as member commands
    63     //SetConsoleCommand(InputManager, calibrate, true);
    64     //SetConsoleCommand(InputManager, reload, false);
    6561    SetCommandLineSwitch(keyboard_no_grab).information("Whether not to exclusively grab the keyboard");
    6662
    … …  
    7066    InputManager* InputManager::singletonRef_s = 0;
    7167
    72     /**
    73     @brief
    74         Defines the |= operator for easier use.
    75     */
     68    //! Defines the |= operator for easier use.
    7669    inline InputManager::State operator|=(InputManager::State& lval, InputManager::State rval)
    7770    {
    … …  
    7972    }
    8073
    81     /**
    82     @brief
    83         Defines the &= operator for easier use.
    84     */
     74    //! Defines the &= operator for easier use.
    8575    inline InputManager::State operator&=(InputManager::State& lval, int rval)
    8676    {
    … …  
    9282    // ##########                                        ##########
    9383    // ############################################################
    94     /**
    95     @brief
    96         Constructor only sets member fields to initial zero values
    97         and registers the class in the class hierarchy.
    98     */
    9984    InputManager::InputManager(size_t windowHnd, unsigned int windowWidth, unsigned int windowHeight)
    10085        : internalState_(Bad)
    … …  
    157142    }
    158143
    159     /**
    160     @brief
    161         Sets the configurable values.
    162     */
    163144    void InputManager::setConfigValues()
    164145    {
    … …  
    168149    @brief
    169150        Creates the OIS::InputMananger, the keyboard, the mouse and
    170         the joysticks and assigns the key bindings.
     151        the joys ticks. If either of the first two fail, this method throws an exception.
    171152    @param windowHnd
    172153        The window handle of the render window
    … …  
    244225    }
    245226
     227    //! Creates a new orxonox::Mouse
    246228    void InputManager::loadMouse(unsigned int windowWidth, unsigned int windowHeight)
    247229    {
    … …  
    262244    }
    263245
    264     /**
    265     @brief
    266         Creates all joy sticks and sets the event handler.
    267     @return
    268         False joy stick stay uninitialised, true otherwise.
    269     */
     246    //! Creates as many joy sticks as are available.
    270247    void InputManager::loadJoySticks()
    271248    {
    … …  
    287264    }
    288265
    289     /**
    290     @brief
    291         Checks whether there is already a joy stick with the given ID string.
    292     @return
    293         Returns true if ID is ok (unique), false otherwise.
    294     */
    295266    bool InputManager::checkJoyStickID(const std::string& idString) const
    296267    {
    … …  
    301272    }
    302273
    303     /**
    304     @brief
    305         Sets the the name of the command used by the KeyDetector as callback.
    306     @param command
    307         Command name as string
    308     */
    309274    void InputManager::setKeyDetectorCallback(const std::string& command)
    310275    {
    … …  
    317282    // ############################################################
    318283
    319     /**
    320     @brief
    321         Destroys all the created input devices and states.
    322     */
    323     // TODO: export this to be used with reload()
    324284    InputManager::~InputManager()
    325285    {
    … …  
    346306    }
    347307
     308    /**
     309    @brief
     310        Destoys all input devices (joy sticks, mouse, keyboard and OIS::InputManager)
     311    @throw
     312        Method does not throw
     313    */
    348314    void InputManager::destroyDevices()
    349315    {
    … …  
    388354    // ############################################################
    389355
    390     /**
    391     @brief
    392         Public interface. Only reloads immediately if the call stack doesn't
    393         include the update() method.
    394     */
    395356    void InputManager::reload()
    396357    {
    … …  
    408369    }
    409370
    410     /**
    411     @brief
    412         Internal reload method. Destroys the OIS devices and loads them again.
    413     */
     371    //! Internal reload method. Destroys the OIS devices and loads them again.
    414372    void InputManager::reloadInternal()
    415373    {
    … …  
    438396    // ############################################################
    439397
    440     /**
    441     @brief
    442         Updates the states and the InputState situation.
    443     @param time
    444         Clock holding the current time.
    445     */
    446398    void InputManager::update(const Clock& time)
    447399    {
    … …  
    581533    }
    582534
    583     /**
    584     @brief
    585         Clears all buffers that store what keys/buttons are being pressed at the moment.
    586     */
    587535    void InputManager::clearBuffers()
    588536    {
    … …  
    592540    }
    593541
    594     /**
    595     @brief
    596         Starts joy stick calibration.
    597     */
    598542    void InputManager::calibrate()
    599543    {
    … …  
    609553    }
    610554
     555    //! Tells all devices to stop the calibration and evaluate it. Buffers are being cleared as well!
    611556    void InputManager::stopCalibration()
    612557    {
    … …  
    627572    // ############################################################
    628573
    629     /**
    630     @brief
    631         Creates a new InputState by type, name and priority.
    632        
    633         You will have to use this method because the
    634         c'tors and d'tors are private.
    635     @remarks
    636         The InputManager will take care of the state completely. That also
    637         means it gets deleted when the InputManager is destroyed!
    638     @param name
    639         Name of the InputState when referenced as string
    640     @param priority
    641         Priority matters when multiple states are active. You can specify any
    642         number, but 1 - 99 is preferred (99 means high).
    643     */
    644574    InputState* InputManager::createInputState(const std::string& name, bool bAlwaysGetsInput, bool bTransparent, InputStatePriority priority)
    645575    {
    646         InputState* state = new InputState;
    647         if (configureInputState(state, name, bAlwaysGetsInput, bTransparent, priority))
    648             return state;
    649         else
    650         {
    651             delete state;
     576        if (name == "")
    652577            return 0;
    653         }
    654     }
    655 
    656     /**
    657     @brief
    658         Adds a new key handler.
    659     @param handler
    660         Pointer to the handler object.
    661     @param name
    662         Unique name of the handler.
    663     @param priority
    664         Determines which InputState gets the input. Higher is better.
    665         Use 0 to handle it implicitely by the order of activation.
    666         Otherwise numbers larger than maxStateStackSize_s have to be used!
    667     @return
    668         True if added, false if name or priority already existed.
    669     */
    670     bool InputManager::configureInputState(InputState* state, const std::string& name, bool bAlwaysGetsInput, bool bTransparent, int priority)
    671     {
    672         if (name == "")
    673             return false;
    674         if (!state)
    675             return false;
    676578        if (statesByName_.find(name) == statesByName_.end())
    677579        {
     580            InputState* state = new InputState;
    678581            if (priority >= InputStatePriority::HighPriority || priority == InputStatePriority::Empty)
    679582            {
    … …  
    685588                    {
    686589                        COUT(2) << "Warning: Could not add an InputState with the same priority '"
    687                             << priority << "' != 0." << std::endl;
     590                            << static_cast<int>(priority) << "' != 0." << std::endl;
    688591                        return false;
    689592                    }
    … …  
    697600            if (priority >= InputStatePriority::HighPriority || priority == InputStatePriority::Empty)
    698601                state->setPriority(priority);
    699             return true;
     602
     603            return state;
    700604        }
    701605        else
    702606        {
    703607            COUT(2) << "Warning: Could not add an InputState with the same name '" << name << "'." << std::endl;
    704             return false;
    705         }
    706     }
    707 
    708     /**
    709     @brief
    710         Returns the pointer to the requested InputState.
    711     @param name
    712         Unique name of the state.
    713     @return
    714         Pointer to the instance, 0 if name was not found.
    715     */
     608            return 0;
     609        }
     610    }
     611
    716612    InputState* InputManager::getState(const std::string& name)
    717613    {
    … …  
    723619    }
    724620
    725     /**
    726     @brief
    727         Activates a specific input state.
    728         It might not be really activated if the priority is too low!
    729     @param name
    730         Unique name of the state.
    731     @return
    732         False if name was not found, true otherwise.
    733     */
    734621    bool InputManager::enterState(const std::string& name)
    735622    {
    … …  
    754641    }
    755642
    756     /**
    757     @brief
    758         Deactivates a specific input state.
    759     @param name
    760         Unique name of the state.
    761     @return
    762         False if name was not found, true otherwise.
    763     */
    764643    bool InputManager::leaveState(const std::string& name)
    765644    {
    … …  
    784663    }
    785664
    786     /**
    787     @brief
    788         Removes and destroys an input state.
    789     @param name
    790         Name of the handler.
    791     @return
    792         True if removal was successful, false if name was not found.
    793     @remarks
    794         You can't remove the internal states "empty", "calibrator" and "detector".
    795         The removal process is being postponed if InputManager::update() is currently running.
    796     */
    797665    bool InputManager::destroyState(const std::string& name)
    798666    {
    … …  
    824692    }
    825693
    826     /**
    827     @brief
    828         Destroys an InputState internally
    829     */
     694    //! Destroys an InputState internally.
    830695    void InputManager::destroyStateInternal(InputState* state)
    831696    {

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

    r3279 r3281  
    2727 */
    2828
    29 /**
    30 @file
    31 @brief
    32     Implementation of a little Input handler that distributes everything
    33     coming from OIS.
    34 */
    35 
    3629#ifndef _InputManager_H__
    3730#define _InputManager_H__
    … …  
    5144    /**
    5245    @brief
    53         Captures and distributes mouse and keyboard input.
     46        Manages the input devices (mouse, keyboard, joy sticks) and the input states.
     47
     48        Every input device has its own wrapper class which does the actualy input event
     49        distribution. The InputManager only creates reloads (on request) those devices.
     50
     51        The other functionality concerns handling InputStates. They act as a layer
     52        between InputHandlers (like the KeyBinder or the GUIManager) and InputDevices.
     53        InputStates are memory managed by the IputManager. You cannot create or destroy
     54        them on your own. Therefore all states get destroyed with the InputManager d'tor.
     55    @note
     56        - The actual lists containing all the InputStates for a specific device are stored
     57          in the InputDevices themselves.
     58        - The devices_ vector always has at least two elements: Keyboard (first) and mouse.
     59          You best access them intenally with InputDeviceEnumerator::Keyboard/Mouse
     60          The first joy stick is accessed with InputDeviceEnumerator::FirstJoyStick.
     61        - Keyboard construction is mandatory , mouse and joy sticks are not.
     62          If the OIS::InputManager or the Keyboard fail, an exception is thrown.
    5463    */
    5564    class _CoreExport InputManager : public OrxonoxClass
    5665    {
    5766    public:
     67        //! Represents internal states of the InputManager.
    5868        enum State
    5969        {
    … …  
    6575        };
    6676
    67         InputManager (size_t windowHnd, unsigned int windowWidth, unsigned int windowHeight);
     77        /**
     78        @brief
     79            Loads the devices and initialises the KeyDetector and the Calibrator.
     80           
     81            If either the OIS input system and/or the keyboard could not be created,
     82            the constructor fails with an std::exception.
     83        */
     84        InputManager(size_t windowHnd, unsigned int windowWidth, unsigned int windowHeight);
     85        //! Destroys all devices AND all input states!
    6886        ~InputManager();
    6987        void setConfigValues();
    7088
     89        /**
     90        @brief
     91            Updates the devices (which distribute the input events) and the input states.
     92
     93            Any InpuStates changes (destroy, enter, leave) and happens here. If a reload request
     94            was submitted while updating, the request wil be postponed until the next update call.
     95        */
    7196        void update(const Clock& time);
     97        //! Clears all input device buffers. This usually only includes the pressed button list.
    7298        void clearBuffers();
     99        //! Starts joy stick calibration.
    73100        void calibrate();
     101        /**
     102        @brief
     103            Reloads all the input devices. Use this method to initialise new joy sticks.
     104        @note
     105            Only reloads immediately if the call stack doesn't include the update() method.
     106        */
    74107        void reload();
    75108
    … …  
    77110        // Input States
    78111        //-------------------------------
     112        /**
     113        @brief
     114            Creates a new InputState that gets managed by the InputManager.
     115        @remarks
     116            The InputManager will take care of the state completely. That also
     117            means it gets deleted when the InputManager is destroyed!
     118        @param name
     119            Unique name of the InputState when referenced as string
     120        @param priority
     121            Priority matters when multiple states are active. You can specify any
     122            number, but 1 - 99 is preferred (99 means high priority).
     123        */
    79124        InputState* createInputState(const std::string& name, bool bAlwaysGetsInput = false, bool bTransparent = false, InputStatePriority priority = InputStatePriority::Dynamic);
     125        /**
     126        @brief
     127            Returns a pointer to a InputState referenced by name.
     128        @return
     129            Returns NULL if state was not found.
     130        */
    80131        InputState* getState(const std::string& name);
    81         bool enterState     (const std::string& name);
    82         bool leaveState     (const std::string& name);
    83         bool destroyState   (const std::string& name);
     132        /**
     133        @brief
     134            Activates a specific input state.
     135            It might not be actually activated if the priority is too low!
     136        @return
     137            False if name was not found, true otherwise.
     138        */
     139        bool enterState(const std::string& name);
     140        /**
     141        @brief
     142            Deactivates a specific input state.
     143        @return
     144            False if name was not found, true otherwise.
     145        */
     146        bool leaveState(const std::string& name);
     147        /**
     148        @brief
     149            Removes and destroys an input state.
     150        @return
     151            True if removal was successful, false if name was not found.
     152        @remarks
     153            - You can't remove the internal states "empty", "calibrator" and "detector".
     154            - The removal process is being postponed if InputManager::update() is currently running.
     155        */
     156        bool destroyState(const std::string& name);
    84157
    85158        //-------------------------------
    86159        // Various getters and setters
    87160        //-------------------------------
     161        //! Sets the the name of the command used by the KeyDetector as callback.
    88162        void setKeyDetectorCallback(const std::string& command);
     163        /**
     164        @brief
     165            Checks whether there is already a joy stick with the given ID string.
     166        @return
     167            Returns true if ID is ok (unique), false otherwise.
     168        */
    89169        bool checkJoyStickID(const std::string& idString) const;
     170        //! Returns the number of joy stick that have been created since the c'tor or last call to reload().
    90171        unsigned int getJoyStickQuantity() const
    91172            { return devices_.size() - InputDeviceEnumerator::FirstJoyStick; }
     173        //! Returns a pointer to the OIS InputManager. Only you if you know what you're doing!
    92174        OIS::InputManager* getOISInputManager()
    93175            { return this->oisInputManager_; }
    94176
    95         static InputManager& getInstance()    { assert(singletonRef_s); return *singletonRef_s; }
     177        //! Returns a reference to the singleton instance
     178        static InputManager& getInstance() { assert(singletonRef_s); return *singletonRef_s; }
    96179
    97180    private: // functions
    … …  
    106189
    107190        void stopCalibration();
     191        void reloadInternal();
    108192
    109193        void destroyStateInternal(InputState* state);
    110194        void updateActiveStates();
    111         bool configureInputState(InputState* state, const std::string& name, bool bAlwaysGetsInput, bool bTransparent, int priority);
    112 
    113         void reloadInternal();
    114195
    115196    private: // variables
    … …  
    117198        OIS::InputManager*                  oisInputManager_;      //!< OIS input manager
    118199        std::vector<InputDevice*>           devices_;              //!< List of all input devices (keyboard, mouse, joy sticks)
    119         size_t                              windowHnd_;            //!< Render window handle
     200        // TODO: Get this from the GraphicsManager during reload
     201        size_t                              windowHnd_;            //!< Render window handle (used to reload the InputManager)
    120202
    121203        // some internally handled states and handlers
    122         InputState*                         emptyState_;
     204        InputState*                         emptyState_;           //!< Lowest priority states (makes handling easier)
    123205        KeyDetector*                        keyDetector_;          //!< KeyDetector instance
     206        //! InputBuffer that reacts to the Enter key when calibrating the joy sticks
    124207        InputBuffer*                        calibratorCallbackHandler_;
    125208
    126         std::map<std::string, InputState*>  statesByName_;
    127         std::map<int, InputState*>          activeStates_;
    128         std::vector<InputState*>            activeStatesTicked_;
    129 
    130         std::set<InputState*>               stateEnterRequests_;   //!< Request to enter a new state
    131         std::set<InputState*>               stateLeaveRequests_;   //!< Request to leave a running state
    132         std::set<InputState*>               stateDestroyRequests_; //!< Request to destroy a state
    133 
    134         static InputManager*                singletonRef_s;
     209        std::map<std::string, InputState*>  statesByName_;         //!< Contains all the created input states by name
     210        std::map<int, InputState*>          activeStates_;         //!< Contains all active input states by priority (std::map is sorted!)
     211        std::vector<InputState*>            activeStatesTicked_;   //!< Like activeStates_, but only contains the ones that currently receive events
     212
     213        std::set<InputState*>               stateEnterRequests_;   //!< Requests to enter a new state
     214        std::set<InputState*>               stateLeaveRequests_;   //!< Requests to leave a running state
     215        std::set<InputState*>               stateDestroyRequests_; //!< Requests to destroy a state
     216
     217        static InputManager*                singletonRef_s;        //!< Pointer reference to the singleton
    135218    };
    136219}
Note: See TracChangeset for help on using the changeset viewer.