Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 11, 2010, 12:34:00 AM (14 years ago)
Author:
landauf
Message:

merged doc branch back to trunk

Location:
code/trunk
Files:
95 edited

Legend:

Unmodified
Added
Removed

  • code/trunk

  • code/trunk/src/libraries/core/BaseObject.cc

    r7284 r7401  
    116116        @brief XML loading and saving.
    117117        @param xmlelement The XML-element
    118         @param loading Loading (true) or saving (false)
     118        @param mode The mode defines the operation that is being executed: loading or saving the object (from or to XML respectively)
    119119    */
    120120    void BaseObject::XMLPort(Element& xmlelement, XMLPort::Mode mode)
    … …  
    141141        @brief Defines the possible event states of this object and parses eventsources from an XML file.
    142142        @param xmlelement The XML-element
    143         @param loading Loading (true) or saving (false)
     143        @param mode The mode defines the operation that is being executed: loading or saving the object (from or to XML respectively)
    144144    */
    145145    void BaseObject::XMLEventPort(Element& xmlelement, XMLPort::Mode mode)

  • code/trunk/src/libraries/core/BaseObject.h

    r7284 r7401  
    2828
    2929/**
     30    @defgroup BaseObject BaseObject
     31    @ingroup Core
     32*/
     33
     34/**
    3035    @file
    31     @brief Definition of the BaseObject class.
     36    @ingroup BaseObject
     37    @brief Declaration of BaseObject, the base class of all objects in Orxonox.
    3238
    3339    The BaseObject is the parent of all classes representing an instance in the game.
    … …  
    5359    class Level;
    5460
    55     //! The BaseObject is the parent of all classes representing an instance in the game.
     61    /// The BaseObject is the parent of all classes representing an instance in the game.
    5662    class _CoreExport BaseObject : virtual public OrxonoxClass
    5763    {

  • code/trunk/src/libraries/core/ClassFactory.h

    r5929 r7401  
    2929/**
    3030    @file
     31    @ingroup Object Factory
    3132    @brief Definition and implementation of the ClassFactory class
    3233
    33     The ClassFactory is able to create new objects of a specific class.
     34    The ClassFactory is able to create new objects of a specific class which creates objects.
    3435*/
    3536
    … …  
    4950    // ###       Factory       ###
    5051    // ###########################
    51     //! Base-class of ClassFactory.
     52    /// Base-class of ClassFactory.
    5253    class _CoreExport Factory
    5354    {
    … …  
    6061    // ###      ClassFactory       ###
    6162    // ###############################
    62     //! The ClassFactory is able to create new objects of a specific class.
     63    /// The ClassFactory is able to create new objects of a specific class.
    6364    template <class T>
    6465    class ClassFactory : public Factory

  • code/trunk/src/libraries/core/ClassTreeMask.cc

    r7268 r7401  
    2929/**
    3030    @file
    31     @brief Implementation of the ClassTreeMask, ClassTreeMaskNode and ClassTreeMaskIterator classes.
     31    @brief Implementation of the ClassTreeMask, ClassTreeMaskNode, and ClassTreeMaskIterator classes.
    3232*/
    3333
    … …  
    9393    /**
    9494        @brief Adds a new subnode to the list of subnodes.
    95         @param subnode The new subnode
    9695    */
    9796    void ClassTreeMaskNode::addSubnode(ClassTreeMaskNode* subnode)
    … …  
    178177    /**
    179178        @brief Returns a pointer to the ClassTreeMaskNode whereon the iterator points.
    180         @return The pointer to the node
    181179    */
    182180    ClassTreeMaskNode* ClassTreeMaskIterator::operator*() const
    … …  
    187185    /**
    188186        @brief Returns a pointer to the ClassTreeMaskNode whereon the iterator points.
    189         @return The pointer to the node
    190187    */
    191188    ClassTreeMaskNode* ClassTreeMaskIterator::operator->() const
    … …  
    196193    /**
    197194        @brief Returns true if the stack is empty, meaning we've reached the end of the tree.
    198         @return True if we've reached the end of the tree
    199195    */
    200196    ClassTreeMaskIterator::operator bool() const
    … …  
    205201    /**
    206202        @brief Compares the current node with the given one and returns true if they match.
    207         @param compare The node to compare with
    208         @return The result of the comparison (true if they match)
    209203    */
    210204    bool ClassTreeMaskIterator::operator==(ClassTreeMaskNode* compare) const
    … …  
    218212    /**
    219213        @brief Compares the current node with the given one and returns true if they don't match.
    220         @param compare The node to compare with
    221         @return The result of the comparison (true if they don't match)
    222214    */
    223215    bool ClassTreeMaskIterator::operator!=(ClassTreeMaskNode* compare) const
    … …  
    242234
    243235    /**
    244         @brief Copyconstructor: Adds the root-node of the tree with the first rule ("include everything") and adds all rules from the other mask.
    245         @param other The other mask
     236        @brief Copy-constructor: Adds the root-node of the tree with the first rule ("include everything") and adds all rules from the other mask.
    246237    */
    247238    ClassTreeMask::ClassTreeMask(const ClassTreeMask& other)

  • code/trunk/src/libraries/core/ClassTreeMask.h

    r7268 r7401  
    2929/**
    3030    @file
    31     @brief Definition of the ClassTreeMask, ClassTreeMaskNode and ClassTreeMaskIterator classes.
    32 
    33     ClassTreeMask is a class to define a mask of the class-tree beginning with BaseObject.
     31    @ingroup Class
     32    @brief Declaration of the ClassTreeMask, ClassTreeMaskNode, and ClassTreeMaskIterator classes.
     33
     34    ClassTreeMask is a class to define a mask of the class-tree beginning with orxonox::BaseObject.
    3435    You can include or exclude classes by calling the corresponding functions with the
    35     Identifier of the class.
     36    orxonox::Identifier of the class. This mask can then be used to filter out objects that
     37    are instances of classes which aren't included in the tree, for example when Loading a
     38    level file or if a Trigger should be triggered by only a few classes.
     39
     40    See the description of orxonox::ClassTreeMask for a short example.
    3641
    3742    You can work with a ClassTreeMask in the sense of the set-theory, meaning that you can create
    3843    unions, intersections, complements and differences by using overloaded operators.
    3944
    40 
     45    @par Tree structure
    4146
    4247    The ClassTreeMask is internally represented by a tree. The nodes in the tree are
    … …  
    4550    nodes changing the mask. By adding new rules, the tree gets reordered dynamically.
    4651
    47     Adding a new rule overwrites all rules assigned to inherited classes. Use overwrite = false
     52    Adding a new rule overwrites all rules assigned to inherited classes. Use <tt>overwrite = false</tt>
    4853    if you don't like this feature. Useless rules that don't change the information of the mask
    49     aren't saved in the internal tree. Use clean = false if you wan't to save them.
    50 
    51     With overwrite = false and clean = false it doesn't matter in which way you create the mask.
    52     You can manually drop useless rules from the tree by calling clean().
    53 
    54 
    55 
    56     Because of the complicated shape of the internal tree, there is an iterator to iterate
    57     through all ClassTreeMaskNodes of a mask. It starts with the BaseObject and moves on to
    58     the first subclass until it reaches a leaf of the tree. Then the iterator moves one step
    59     back and iterates to the second subclass. If there are no more subclasses, it steps another
    60     step back, and so on.
    61 
    62     Example: A and B are children of BaseObject, A1 and A2 are children of A, B1 and B2 are children of B.
    63     The ClassTreeMaskIterator would move trough the tree in the following order:
    64     BaseObject, A, A1, A2, B, B1, B2.
    65 
    66     Note that the iterator doesn't move trough the whole class-tree, but only through the
    67     internal tree of the mask, containing the minimal needed set of nodes to describe the mask.
     54    aren't saved in the internal tree. Use <tt>clean = false</tt> if you still want to save them.
     55
     56    With <tt>overwrite = false</tt> and <tt>clean = false</tt> it doesn't matter in which order
     57    you create the mask. You can manually drop useless rules from the tree by calling
     58    @ref orxonox::ClassTreeMask::clean() "clean()".
     59
     60    @par Objects
     61
     62    To iterate through all objects of the classes that were included by a ClassTreeMask,
     63    use orxonox::ClassTreeMaskObjectIterator. The description of this class also contains
     64    a short example of how to use it.
    6865*/
    6966
    … …  
    8380    // ###      ClassTreeMaskNode      ###
    8481    // ###################################
    85     //! The ClassTreeMaskNode is a node in the internal tree of the ClassTreeMask, containing the rules of the mask.
    8682    /**
     83        @brief The ClassTreeMaskNode is a node in the internal tree of the ClassTreeMask, containing the rules of the mask.
     84
    8785        The ClassTreeMaskNode is used to store the rule (included or excluded) for a given
    8886        class (described by the corresponding Identifier). The nodes are used in the internal
    … …  
    105103            void addSubnode(ClassTreeMaskNode* subnode);
    106104
    107             /** @brief Tells if the rule is "included" or not. @return The rule: true = included, false = excluded */
     105            /// Tells if the rule is "included" or not.
    108106            inline bool isIncluded() const { return this->bIncluded_; }
    109             /** @brief Tells if the rule is "excluded" or not. @return The inverted rule: true = excluded, false = included */
     107            /// Tells if the rule is "excluded" or not.
    110108            inline bool isExcluded() const { return (!this->bIncluded_); }
    111109
    112             /** @brief Returns the Identifier of the class the rule refers to. @return The Identifier representing the class */
     110            /// Returns the Identifier of the class the rule refers to.
    113111            inline const Identifier* getClass() const { return this->subclass_; }
    114112
    115             /** @brief Returns true if the Node has some subnodes. */
     113            /// Returns true if the node has some subnodes.
    116114            inline bool hasSubnodes() const { return !this->subnodes_.empty(); }
    117115
    … …  
    119117            void deleteAllSubnodes();
    120118
    121             const Identifier* subclass_;                //!< The Identifier of the subclass the rule refers to
    122             bool bIncluded_;                            //!< The rule: included or excluded
    123             std::list<ClassTreeMaskNode*> subnodes_;    //!< A list containing all subnodes in the tree
     119            const Identifier* subclass_;                ///< The Identifier of the subclass the rule refers to
     120            bool bIncluded_;                            ///< The rule: included or excluded
     121            std::list<ClassTreeMaskNode*> subnodes_;    ///< A list containing all subnodes of this node
    124122    };
    125123
    … …  
    128126    // ###    ClassTreeMaskIterator    ###
    129127    // ###################################
    130     //! The ClassTreeMaskIterator moves through all ClassTreeMaskNodes of the internal tree of a ClassTreeMask, containing the rules.
    131128    /**
     129        @brief The ClassTreeMaskIterator moves through all ClassTreeMaskNodes of the internal tree of a ClassTreeMask which contains the rules.
     130
    132131        Because of the complicated shape of the internal rule-tree of ClassTreeMask, an
    133132        iterator is used to move through all nodes of the tree. It starts with the BaseObject
    … …  
    135134        iterator moves one step back and iterates to the second subclass. If there are no more
    136135        subclasses, it steps another step back, and so on.
     136
     137        Example: A and B are children of BaseObject, A1 and A2 are children of A, B1 and B2 are children of B.
     138        The ClassTreeMaskIterator would move trough the tree in the following order:
     139        BaseObject, A, A1, A2, B, B1, B2.
     140
     141        Note that the iterator doesn't move trough the whole class-tree, but only through the
     142        internal tree of the mask, containing the minimal needed set of nodes to describe the mask.
    137143    */
    138144    class _CoreExport ClassTreeMaskIterator
    … …  
    150156
    151157        private:
    152             std::stack<std::pair<std::list<ClassTreeMaskNode*>::iterator, std::list<ClassTreeMaskNode*>::iterator> > nodes_;    //!< A stack to store list-iterators
    153             std::list<ClassTreeMaskNode*> rootlist_;                                                                            //!< A list for internal use (it only stores the root-node)
     158            std::stack<std::pair<std::list<ClassTreeMaskNode*>::iterator, std::list<ClassTreeMaskNode*>::iterator> > nodes_;    ///< A stack to store list-iterators
     159            std::list<ClassTreeMaskNode*> rootlist_;                                                                            ///< A list for internal use (it only stores the root-node)
    154160    };
    155161
    … …  
    158164    // ###        ClassTreeMask        ###
    159165    // ###################################
    160     //! The ClassTreeMask is a set of rules, containing the information for each class whether it's included or not.
    161166    /**
     167        @brief The ClassTreeMask is a set of rules, containing the information for each class whether it's included or not.
     168
    162169        With a ClassTreeMask, you can include or exclude subtrees of the class-tree, starting
    163170        with a given subclass, described by the corresponding Identifier. To minimize the size
    164171        of the mask, the mask saves only relevant rules. But you can manually add rules that
    165         don't change the information of the mask by using clean = false. If you want to drop
     172        don't change the information of the mask by using <tt>clean = false</tt>. If you want to drop
    166173        useless rules, call the clean() function.
     174
     175        Example:
     176        @code
     177        ClassTreeMask mymask;
     178        mymask.exclude(Class(A));
     179        mymask.exclude(Class(B));
     180        mymask.include(Class(ChildOfA));
     181        @endcode
     182
     183        In this example, the classes A and B are excluded from the mask, but one of the child
     184        classes of A is included again.
    167185    */
    168186    class _CoreExport ClassTreeMask
    … …  
    189207            bool isExcluded(const Identifier* subclass) const;
    190208
    191             /** @brief Begin of the ClassTreeMaskObjectIterator. */
     209            /// Begin of the ClassTreeMaskObjectIterator.
    192210            inline const ClassTreeMask& begin() const { return (*this); }
    193             /** @brief End of the ClassTreeMaskObjectIterator. */
     211            /// End of the ClassTreeMaskObjectIterator.
    194212            inline BaseObject*          end()   const { return 0; }
    195213
    … …  
    228246            bool nodeExists(const Identifier* subclass);
    229247
    230             ClassTreeMaskNode* root_;   //!< The root-node of the internal rule-tree, usually BaseObject
     248            ClassTreeMaskNode* root_;   ///< The root-node of the internal rule-tree, usually BaseObject
    231249    };
    232250
    … …  
    235253    // ### ClassTreeMaskObjectIterator ###
    236254    // ###################################
    237     //! The ClassTreeMaskObjectIterator iterates through all objects of all classes, included by a ClassTreeMask.
    238255    /**
    239         The ClassTreeMaskObjectIterator iterates through all objects of all classes,
    240         included by a ClassTreeMask. This is done the following way:
    241 
     256        @brief The ClassTreeMaskObjectIterator iterates through all objects of the classes that were included by a ClassTreeMask.
     257
     258        This is done the following way:
     259        @code
    242260        ClassTreeMask mask;
    243261        for (ClassTreeMaskObjectIterator it = mask.begin(); it != mask.end(); ++it)
    244262            it->doSomething();
    245 
    246         Note: The ClassTreeMaskObjectIterator handles all objects as BaseObjects. If
     263        @endcode
     264
     265        @note The ClassTreeMaskObjectIterator handles all objects as BaseObjects. If
    247266              you want to use another class, you should use a dynamic_cast.
    248267
    249         Performance of ClassTreeMaskObjectIterator is good as long as you don't exclude
     268        The performance of ClassTreeMaskObjectIterator is good as long as you don't exclude
    250269        subclasses of included classes. Of course you can still exlucde subclasses, but
    251270        if this is done more often, we need a new implementation using a second ObjectList
    … …  
    255274    {
    256275        public:
    257             /** @brief Defaultconstructor: Does nothing. */
     276            /// Default-constructor: Does nothing.
    258277            inline ClassTreeMaskObjectIterator() {}
    259             /** @brief Constructor: Initializes the iterator from a given ClassTreeMask. @param mask The mask */
     278            /// Copy-Constructor: Initializes the iterator from another ClassTreeMask.
    260279            inline ClassTreeMaskObjectIterator(const ClassTreeMask& mask) { (*this) = mask; }
    261280
    … …  
    264283            const ClassTreeMaskObjectIterator& operator++();
    265284
    266             /** @brief Returns true if the ClassTreeMaskObjectIterator points at the given object. @param pointer The pointer of the object */
     285            /// Returns true if the ClassTreeMaskObjectIterator points at the given object.
    267286            inline bool operator==(BaseObject* pointer) const { return (this->objectIterator_ && (*this->objectIterator_) == pointer) || (!this->objectIterator_ && pointer == 0); }
    268             /** @brief Returns true if the ClassTreeMaskObjectIterator doesn't point at the given object. @param pointer The pointer of the object */
     287            /// Returns true if the ClassTreeMaskObjectIterator doesn't point at the given object.
    269288            inline bool operator!=(BaseObject* pointer) const { return (this->objectIterator_ && (*this->objectIterator_) != pointer) || (!this->objectIterator_ && pointer != 0); }
    270             /** @brief Returns true if the ClassTreeMaskObjectIterator hasn't already reached the end. */
     289            /// Returns true if the ClassTreeMaskObjectIterator hasn't already reached the end.
    271290            inline operator bool() const { return (this->objectIterator_); }
    272             /** @brief Returns the object the ClassTreeMaskObjectIterator currently points at. */
     291            /// Returns the object the ClassTreeMaskObjectIterator currently points at.
    273292            inline BaseObject* operator*() const { return (*this->objectIterator_); }
    274             /** @brief Returns the object the ClassTreeMaskObjectIterator currently points at. */
     293            /// Returns the object the ClassTreeMaskObjectIterator currently points at.
    275294            inline BaseObject* operator->() const { return (*this->objectIterator_); }
    276295
    … …  
    278297            void create(ClassTreeMaskNode* node);
    279298
    280             std::list<std::pair<const Identifier*, bool> >           subclasses_;       //!< A list of all Identifiers through which objects the iterator should iterate
    281             std::list<std::pair<const Identifier*, bool> >::iterator subclassIterator_; //!< The current class of the iterator
    282             Iterator<BaseObject>                                     objectIterator_;   //!< The current object of the iterator
     299            std::list<std::pair<const Identifier*, bool> >           subclasses_;       ///< A list of all Identifiers through which objects the iterator should iterate
     300            std::list<std::pair<const Identifier*, bool> >::iterator subclassIterator_; ///< The current class of the iterator
     301            Iterator<BaseObject>                                     objectIterator_;   ///< The current object of the iterator
    283302    };
    284303}

  • code/trunk/src/libraries/core/CommandLineParser.cc

    r7284 r7401  
    126126    @param arguments
    127127        Vector of space separated strings.
     128    @param bParsingFile
     129        Parsing a file or the command line itself
    128130    */
    129131    void CommandLineParser::_parse(const std::vector<std::string>& arguments, bool bParsingFile)
    … …  
    244246    @param value
    245247        String containing the value
     248    @param bParsingFile
     249        Parsing a file or the command line itself
    246250    */
    247251    void CommandLineParser::checkFullArgument(const std::string& name, const std::string& value, bool bParsingFile)
    … …  
    258262        Parses an argument based on its shortcut.
    259263    @param shortcut
    260         Shotcut to the argument
     264        Shortcut to the argument
    261265    @param value
    262266        String containing the value
     267    @param bParsingFile
     268        Parsing a file or the command line itself
    263269    */
    264270    void CommandLineParser::checkShortcut(const std::string& shortcut, const std::string& value, bool bParsingFile)
    … …  
    308314    }
    309315
     316    void CommandLineParser::generateDoc(std::ofstream& file)
     317    {
     318        file << "/** @page cmdargspage Command Line Arguments Reference" << endl;
     319        file << "    @verbatim"; /*no endl*/
     320        file << getUsageInformation(); /*no endl*/
     321        file << "    @endverbatim" << endl;
     322        file << "*/" << endl;
     323    }
     324
    310325    /**
    311326    @brief
    … …  
    313328        The method throws an exception if 'name' was not found or the value could not be converted.
    314329    @note
    315         You shold of course not call this method before the command line has been parsed.
     330        You should of course not call this method before the command line has been parsed.
    316331    */
    317332    const CommandLineArgument* CommandLineParser::getArgument(const std::string& name)

  • code/trunk/src/libraries/core/CommandLineParser.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @defgroup CmdArgs Commandline arguments
     31    @ingroup Config
     32    @brief For a reference of all commandline arguments see @ref cmdargspage
     33*/
     34
     35/**
     36    @file
     37    @ingroup Config CmdArgs
     38    @brief Declaration of CommandLineParser and CommandLineArgument, definition of the SetCommandLineArgument() macros.
     39*/
     40
    2941#ifndef _CommandLine_H__
    3042#define _CommandLine_H__
    … …  
    3244#include "CorePrereqs.h"
    3345
     46#include <fstream>
    3447#include <map>
    3548#include "util/OrxAssert.h"
    … …  
    165178        static void destroyAllArguments();
    166179
     180        static void generateDoc(std::ofstream& file);
     181
    167182    private:
    168183        //! Constructor initialises bFirstTimeParse_ with true.
    … …  
    207222    @param defaultValue
    208223        Default value that is used when argument was not given.
     224    @param bCommandLineOnly
     225        Parsing a file or the command line itself
    209226    */
    210227    template <class T>

  • code/trunk/src/libraries/core/ConfigFileManager.cc

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of ConfigFileManager and its helper classes.
     32*/
     33
    2934#include "ConfigFileManager.h"
    3035
    … …  
    4348    // ConfigFileEntryValue //
    4449    //////////////////////////
    45 
     50    /**
     51        @brief Updates the string that will be stored in the file after one of it's components (name, value, comment) has changed.
     52    */
    4653    void ConfigFileEntryValue::update()
    4754    {
    … …  
    6370    // ConfigFileEntryVectorValue //
    6471    ////////////////////////////////
     72    /**
     73        @brief Updates the string that will be stored in the file after one of it's components (name, value, index, comment) has changed.
     74    */
    6575    void ConfigFileEntryVectorValue::update()
    6676    {
    … …  
    7383    // ConfigFileSection //
    7484    ///////////////////////
     85    /**
     86        @brief Destructor: Deletes all entries.
     87    */
    7588    ConfigFileSection::~ConfigFileSection()
    7689    {
    … …  
    7992    }
    8093
     94    /**
     95        @brief Deletes all elements of a config vector if their index is greater or equal to @a startindex.
     96
     97        @param name         The name of the vector
     98        @param startindex   The index of the first element that will be deleted
     99    */
    81100    void ConfigFileSection::deleteVectorEntries(const std::string& name, unsigned int startindex)
    82101    {
    … …  
    95114    }
    96115
     116    /**
     117        @brief Returns the size of a config vector.
     118        @param name     The name of the vector
     119    */
    97120    unsigned int ConfigFileSection::getVectorSize(const std::string& name) const
    98121    {
    … …  
    108131    }
    109132
     133    /**
     134        @brief Returns the title and comment of the section as it will be stored in the file.
     135    */
    110136    std::string ConfigFileSection::getFileEntry() const
    111137    {
    … …  
    116142    }
    117143
     144    /**
     145        @brief Returns the entry with given name (or NULL if it doesn't exist).
     146
     147        @param name     The name of the entry
     148    */
    118149    ConfigFileEntry* ConfigFileSection::getEntry(const std::string& name) const
    119150    {
    … …  
    126157    }
    127158
     159    /**
     160        @brief Returns the entry of a vector element with given name and index (or NULL if it doesn't exist).
     161
     162        @param name     The name of the vector
     163        @param index    The index of the element in the vector
     164    */
    128165    ConfigFileEntry* ConfigFileSection::getEntry(const std::string& name, unsigned int index) const
    129166    {
    … …  
    136173    }
    137174
     175    /**
     176        @brief Returns the iterator to the entry with given name. If the entry doesn't exist, it is created using the fallback value.
     177
     178        @param name     The name of the entry
     179        @param fallback The value that will be used if the entry doesn't exist
     180        @param bString  If true, the value is treated as string which means some special treatment of special characters.
     181    */
    138182    std::list<ConfigFileEntry*>::iterator ConfigFileSection::getOrCreateEntryIterator(const std::string& name, const std::string& fallback, bool bString)
    139183    {
    … …  
    152196    }
    153197
     198    /**
     199        @brief Returns the iterator to the entry of a vector element with given name and index. If the entry doesn't exist, it is created using the fallback value.
     200
     201        @param name     The name of the vector
     202        @param index    The index of the element in the vector
     203        @param fallback The value that will be used if the entry doesn't exist
     204        @param bString  If true, the value is treated as string which means some special treatment of special characters.
     205    */
    154206    std::list<ConfigFileEntry*>::iterator ConfigFileSection::getOrCreateEntryIterator(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    155207    {
    … …  
    178230    const char* ConfigFile::DEFAULT_CONFIG_FOLDER = "defaultConfig";
    179231
     232    /**
     233        @brief Constructor: Initializes the config file.
     234        @param filename The file-name of this config file
     235        @param bCopyFallbackFile If true, the default config file is copied into the config-directory before loading the file
     236    */
    180237    ConfigFile::ConfigFile(const std::string& filename, bool bCopyFallbackFile)
    181238        : filename_(filename)
    … …  
    185242    }
    186243
     244    /**
     245        @brief Destructor: Deletes all sections and entries.
     246    */
    187247    ConfigFile::~ConfigFile()
    188248    {
    … …  
    190250    }
    191251
     252    /**
     253        @brief Loads the config file from the hard-disk and reads the sections and their values.
     254    */
    192255    void ConfigFile::load()
    193256    {
    … …  
    318381    }
    319382
     383    /**
     384        @brief Writes the sections and values to the hard-disk.
     385    */
    320386    void ConfigFile::save() const
    321387    {
    … …  
    323389    }
    324390
     391    /**
     392        @brief Writes the sections and values to a given file on the hard-disk.
     393    */
    325394    void ConfigFile::saveAs(const std::string& filename) const
    326395    {
    … …  
    354423    }
    355424
     425    /**
     426        @brief Deletes all sections (which again delete all their values) and clears the list of sections.
     427    */
    356428    void ConfigFile::clear()
    357429    {
    … …  
    361433    }
    362434
    363     const std::string& ConfigFile::getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString)
    364     {
    365         const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, fallback, bString);
    366         this->saveIfUpdated();
    367         return output;
    368     }
    369 
    370     const std::string& ConfigFile::getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    371     {
    372         const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, index, fallback, bString);
    373         this->saveIfUpdated();
    374         return output;
    375     }
    376 
     435    /**
     436        @brief Deletes all elements of a config vector if their index is greater or equal to @a startindex.
     437
     438        @param section      The name of the section
     439        @param name         The name of the vector
     440        @param startindex   The index of the first element that will be deleted
     441    */
    377442    void ConfigFile::deleteVectorEntries(const std::string& section, const std::string& name, unsigned int startindex)
    378443    {
    … …  
    384449    }
    385450
     451    /**
     452        @brief Returns a pointer to the section with given name (or NULL if the section doesn't exist).
     453    */
    386454    ConfigFileSection* ConfigFile::getSection(const std::string& section) const
    387455    {
    … …  
    392460    }
    393461
     462    /**
     463        @brief Returns a pointer to the section with given name. If it doesn't exist, the section is created.
     464    */
    394465    ConfigFileSection* ConfigFile::getOrCreateSection(const std::string& section)
    395466    {
    … …  
    403474    }
    404475
     476    /**
     477        @brief Saves the config file if it was updated (or if any of its sections were updated).
     478    */
    405479    void ConfigFile::saveIfUpdated()
    406480    {
    … …  
    442516    SettingsConfigFile* SettingsConfigFile::singletonPtr_s = 0;
    443517
     518    /**
     519        @brief Constructor: Activates the console commands.
     520    */
    444521    SettingsConfigFile::SettingsConfigFile(const std::string& filename)
    445522        : ConfigFile(filename)
    … …  
    452529    }
    453530
     531    /**
     532        @brief Destructor: Deactivates the console commands.
     533    */
    454534    SettingsConfigFile::~SettingsConfigFile()
    455535    {
    … …  
    461541    }
    462542
     543    /**
     544        @brief Loads the config file and updates the @ref ConfigValueContainer "config value containers".
     545    */
    463546    void SettingsConfigFile::load()
    464547    {
    … …  
    467550    }
    468551
     552    /**
     553        @brief Changes the file-name.
     554    */
    469555    void SettingsConfigFile::setFilename(const std::string& filename)
    470556    {
    … …  
    472558    }
    473559
     560    /**
     561        @brief Registers a new @ref ConfigValueContainer "config value container".
     562    */
    474563    void SettingsConfigFile::addConfigValueContainer(ConfigValueContainer* container)
    475564    {
    … …  
    481570    }
    482571
     572    /**
     573        @brief Unregisters a @ref ConfigValueContainer "config value container".
     574    */
    483575    void SettingsConfigFile::removeConfigValueContainer(ConfigValueContainer* container)
    484576    {
    … …  
    500592    }
    501593
     594    /**
     595        @brief Updates all @ref ConfigValueContainer "config value containers".
     596    */
    502597    void SettingsConfigFile::updateConfigValues()
    503598    {
     599        // todo: can this be done more efficiently? looks like some identifiers will be updated multiple times.
     600
    504601        for (ContainerMap::const_iterator it = this->containers_.begin(); it != this->containers_.end(); ++it)
    505602        {
    … …  
    509606    }
    510607
     608    /**
     609        @brief Removes entries and sections from the file that don't exist anymore (i.e. if there's no corresponding @ref ConfigValueContainer "config value container").
     610        @param bCleanComments If true, comments are also removed from the file
     611    */
    511612    void SettingsConfigFile::clean(bool bCleanComments)
    512613    {
    … …  
    558659    }
    559660
     661    /**
     662        @brief Console-command: Changes the value of an entry and stores it the file.
     663
     664        @param section  The section of the config value
     665        @param entry    The name of the config value
     666        @param value    The new value
     667    */
    560668    void SettingsConfigFile::config(const std::string& section, const std::string& entry, const std::string& value)
    561669    {
    … …  
    564672    }
    565673
     674    /**
     675        @brief Console-command: Changes the value of an entry, but doesn't store it in the file (it's only a temporary change).
     676
     677        @param section  The section of the config value
     678        @param entry    The name of the config value
     679        @param value    The new value
     680    */
    566681    void SettingsConfigFile::tconfig(const std::string& section, const std::string& entry, const std::string& value)
    567682    {
    … …  
    570685    }
    571686
     687    /**
     688        @brief Changes the value of an entry, depending on @a function, either by using "set" or "tset"
     689
     690        @param section  The section of the config value
     691        @param entry    The name of the config value
     692        @param value    The new value
     693        @param function The function ("set" or "tset") that will be used to change the value.
     694    */
    572695    bool SettingsConfigFile::configImpl(const std::string& section, const std::string& entry, const std::string& value, bool (ConfigValueContainer::*function)(const MultiType&))
    573696    {
    … …  
    586709    }
    587710
     711    /**
     712        @brief Console-command: Returns the value of a given entry.
     713
     714        @param section  The section of the config value
     715        @param entry    The name of the config value
     716    */
    588717    std::string SettingsConfigFile::getConfig(const std::string& section, const std::string& entry)
    589718    {
    … …  
    611740    ConfigFileManager* ConfigFileManager::singletonPtr_s = 0;
    612741
     742    /// Constructor: Initializes the array of config files with NULL.
    613743    ConfigFileManager::ConfigFileManager()
    614744    {
    … …  
    616746    }
    617747
     748    /// Destructor: Deletes the config files.
    618749    ConfigFileManager::~ConfigFileManager()
    619750    {
    … …  
    623754    }
    624755
     756    /// Defines the file-name for the config file of a given type (settings, calibration, etc.).
    625757    void ConfigFileManager::setFilename(ConfigFileType::Value type, const std::string& filename)
    626758    {

  • code/trunk/src/libraries/core/ConfigFileManager.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Config ConfigFile
     32    @brief Declaration of ConfigFileManager and its helper classes, used to load and save config files.
     33*/
     34
    2935#ifndef _ConfigFileManager_H__
    3036#define _ConfigFileManager_H__
    … …  
    4652    // ConfigFileEntry //
    4753    /////////////////////
     54    /**
     55        @brief This class represents an entry in the config file.
     56
     57        This class is pure virtual. Use one of the derived classes to define the type of the entry.
     58    */
    4859    class _CoreExport ConfigFileEntry
    4960    {
    5061        public:
     62            /// Destructor
    5163            virtual ~ConfigFileEntry() {};
     64
     65            /// Changes the value of the entry.
    5266            virtual void setValue(const std::string& value) = 0;
     67            /// Returns the value of the entry.
    5368            virtual const std::string& getValue() const = 0;
     69
     70            /// Returns the name of the entry
    5471            virtual const std::string& getName() const = 0;
     72
     73            /// Changes the comment of the entry (will be placed after the value)
    5574            virtual void setComment(const std::string& comment) = 0;
     75
     76            /// Returns the index of the entry in a vector (used only if it is a vector)
    5677            virtual unsigned int getIndex() const { return 0; }
     78
     79            /// Defines if this entry is treated as string which means some special treatment of special characters.
    5780            virtual void setString(bool bString) = 0;
     81
     82            /// Returns the line as it will be stored in the config file.
    5883            virtual const std::string& getFileEntry() const = 0;
    5984    };
    … …  
    6388    // ConfigFileEntryValue //
    6489    //////////////////////////
     90    /**
     91        @brief This class represents a normal value in the config file.
     92    */
    6593    class _CoreExport ConfigFileEntryValue : public ConfigFileEntry
    6694    {
    6795        public:
     96            /**
     97                @brief Constructor: Initializes the entry.
     98
     99                @param name                 The name of the entry
     100                @param value                The value of the entry
     101                @param bString              If true, the value is treated as string which means some special treatment of special characters.
     102                @param additionalComment    An optional comment that will be placed behind the value in the config file
     103            */
    68104            inline ConfigFileEntryValue(const std::string& name, const std::string& value = "", bool bString = false, const std::string& additionalComment = "")
    69105                : name_(name)
    … …  
    73109                { this->update(); }
    74110
     111            /// Destructor
    75112            inline virtual ~ConfigFileEntryValue() {}
    76113
    … …  
    92129                { return this->fileEntry_; }
    93130
     131            /// Returns the "key" of the value (in this case it's just the name of the entry, but for vectors it's different)
    94132            inline virtual const std::string& getKeyString() const
    95133                { return this->name_; }
    … …  
    98136            virtual void update();
    99137
    100             const std::string name_;
    101             std::string value_;
    102             std::string additionalComment_;
    103             std::string fileEntry_;
    104             bool bString_;
     138            const std::string name_;            ///< The name of the value
     139            std::string value_;                 ///< The value
     140            std::string additionalComment_;     ///< The additional comment
     141            std::string fileEntry_;             ///< The string as it will be stored in the config file
     142            bool bString_;                      ///< If true, the value is treated as string which means some special treatment of special characters.
    105143    };
    106144
    … …  
    109147    // ConfigFileEntryVectorValue //
    110148    ////////////////////////////////
     149    /**
     150        @brief Subclass of ConfigFileEntryValue, represents an element of a vector.
     151    */
    111152    class _CoreExport ConfigFileEntryVectorValue : public ConfigFileEntryValue
    112153    {
    113154        public:
     155            /**
     156                @brief Constructor: Initializes the entry.
     157
     158                @param name                 The name of the vector
     159                @param index                The index of the element in the vector
     160                @param value                The value of the element
     161                @param bString              If true, the value is treated as string which means some special treatment of special characters.
     162                @param additionalComment    An optional comment that will be placed behind the value in the config file
     163            */
    114164            inline ConfigFileEntryVectorValue(const std::string& name, unsigned int index, const std::string& value = "", bool bString = false, const std::string& additionalComment = "")
    115165                : ConfigFileEntryValue(name, value, bString, additionalComment)
    … …  
    117167                { this->update(); /*No virtual calls in base class ctor*/ }
    118168
     169            /// Destructor
    119170            inline ~ConfigFileEntryVectorValue() {}
    120171
    … …  
    122173                { return this->index_; }
    123174
     175            /// Returns the "key" of the value (the name of the vector plus the index of the element)
    124176            inline const std::string& getKeyString() const
    125177                { return this->keyString_; }
    … …  
    128180            void update();
    129181
    130             unsigned int index_;
    131             std::string keyString_;
     182            unsigned int index_;        ///< The index of the element in the vector
     183            std::string keyString_;     ///< The full name of the entry (the name of the vector plus the index of the element)
    132184    };
    133185
    … …  
    136188    // ConfigFileEntryComment //
    137189    ////////////////////////////
     190    /**
     191        @brief This class represents a line in the config file which contains only a comment.
     192    */
    138193    class _CoreExport ConfigFileEntryComment : public ConfigFileEntry
    139194    {
    140195        public:
     196            /// Constructor: Initializes the object.
    141197            inline ConfigFileEntryComment(const std::string& comment) : comment_(comment) {}
     198
     199            /// Destructor
    142200            inline virtual ~ConfigFileEntryComment() {}
    143201
    … …  
    159217                { return this->comment_; }
    160218
    161             inline virtual const std::string& getKeyString() const
    162                 { return BLANKSTRING; }
    163 
    164219        private:
    165             std::string comment_;
     220            std::string comment_;   ///< The comment
    166221    };
    167222
    … …  
    170225    // ConfigFileSection //
    171226    ///////////////////////
     227    /**
     228        @brief Represents a section in a config file.
     229
     230        A section has a name and a list of config values.
     231    */
    172232    class _CoreExport ConfigFileSection
    173233    {
    … …  
    176236
    177237        public:
     238            /**
     239                @brief Constructor: Initializes the section.
     240
     241                @param name The name of the section
     242                @param additionalComment An additional comment placed after the title of the section in the config file
     243            */
    178244            inline ConfigFileSection(const std::string& name, const std::string& additionalComment = "")
    179245                : name_(name)
    … …  
    183249            ~ConfigFileSection();
    184250
     251            /// Returns the name of the section.
    185252            inline const std::string& getName() const
    186253                { return this->name_; }
    187254
     255            /// Changes the comment which is placed after the title of the section in the config file.
    188256            inline void setComment(const std::string& comment)
    189257                { this->additionalComment_ = comment; }
    190258
     259            /**
     260                @brief Stores a value in the section. If the entry doesn't exist, it's created.
     261
     262                @param name     The name of the entry
     263                @param value    The new value
     264                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     265            */
    191266            inline void setValue(const std::string& name, const std::string& value, bool bString)
    192267                { this->getOrCreateEntry(name, value, bString)->setValue(value); }
     268            /**
     269                @brief Returns the value of a given entry in the section. Returns a blank string if the value doesn't exist.
     270
     271                @param name     The name of the entry
     272                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     273            */
    193274            inline const std::string& getValue(const std::string& name, bool bString)
    194275            {
    … …  
    196277                if (entry)
    197278                {
    198                     entry->setString(bString);
     279                    entry->setString(bString);  // if the entry was loaded from the config file, we have to tell it if it's a string
    199280                    return entry->getValue();
    200281                }
    201282                return BLANKSTRING;
    202283            }
     284            /**
     285                @brief Returns the value of a given entry in the section. If it doesn't exist, the entry is created using the fallback value.
     286
     287                @param name     The name of the entry
     288                @param fallback The value that will be used if the entry doesn't exist
     289                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     290            */
    203291            inline const std::string& getOrCreateValue(const std::string& name, const std::string& fallback, bool bString)
    204292                { return this->getOrCreateEntry(name, fallback, bString)->getValue(); }
    205293
     294            /**
     295                @brief Stores the value of an element of a vector in the section. If the entry doesn't exist, it's created.
     296
     297                @param name     The name of the vector
     298                @param index    The index of the element in the vector
     299                @param value    The new value
     300                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     301            */
    206302            inline void setValue(const std::string& name, unsigned int index, const std::string& value, bool bString)
    207303                { this->getOrCreateEntry(name, index, value, bString)->setValue(value); }
     304            /**
     305                @brief Returns the value of a given element of a vector in the section. Returns a blank string if the value doesn't exist.
     306
     307                @param name     The name of the vector
     308                @param index    The index of the element in the vector
     309                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     310            */
    208311            inline const std::string& getValue(const std::string& name, unsigned int index, bool bString)
    209312            {
    … …  
    211314                if (entry)
    212315                {
    213                     entry->setString(bString);
     316                    entry->setString(bString);  // if the entry was loaded from the config file, we have to tell it if it's a string
    214317                    return entry->getValue();
    215318                }
    216319                return BLANKSTRING;
    217320            }
     321            /**
     322                @brief Returns the value of a given element of a vector in the section. If it doesn't exist, the entry is created using the fallback value.
     323
     324                @param name     The name of the vector
     325                @param index    The index of the element in the vector
     326                @param fallback The value that will be used if the entry doesn't exist
     327                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     328            */
    218329            inline const std::string& getOrCreateValue(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    219330                { return this->getOrCreateEntry(name, index, fallback, bString)->getValue(); }
    … …  
    225336
    226337        private:
     338            /// Returns the list of entries in this section.
    227339            std::list<ConfigFileEntry*>& getEntries()
    228340                { return this->entries_; }
     341            /// Returns the begin-iterator of the list of entries in this section.
    229342            std::list<ConfigFileEntry*>::const_iterator getEntriesBegin() const
    230343                { return this->entries_.begin(); }
     344            /// Returns the end-iterator of the list of entries in this section.
    231345            std::list<ConfigFileEntry*>::const_iterator getEntriesEnd() const
    232346                { return this->entries_.end(); }
    … …  
    236350
    237351            ConfigFileEntry* getEntry(const std::string& name) const;
     352            /**
     353                @brief Returns the entry with given name. If it doesn't exist, the entry is created using the fallback value.
     354
     355                @param name     The name of the entry
     356                @param fallback The value that will be used if the entry doesn't exist
     357                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     358            */
    238359            inline ConfigFileEntry* getOrCreateEntry(const std::string& name, const std::string& fallback, bool bString)
    239360                { return (*this->getOrCreateEntryIterator(name, fallback, bString)); }
     361
    240362            ConfigFileEntry* getEntry(const std::string& name, unsigned int index) const;
     363            /**
     364                @brief Returns the entry that contains an element of a vector with given name. If it doesn't exist, the entry is created using the fallback value.
     365
     366                @param name     The name of the entry
     367                @param index    The index of the element in the vector
     368                @param fallback The value that will be used if the entry doesn't exist
     369                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     370            */
    241371            inline ConfigFileEntry* getOrCreateEntry(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    242372                { return (*this->getOrCreateEntryIterator(name, index, fallback, bString)); }
    243373
    244             std::string name_;
    245             std::string additionalComment_;
    246             std::list<ConfigFileEntry*> entries_;
    247             bool bUpdated_;
     374            std::string name_;                      ///< The name of the section
     375            std::string additionalComment_;         ///< The additional comment which is placed after the title of the section in the config file
     376            std::list<ConfigFileEntry*> entries_;   ///< The list of entries in this section
     377            bool bUpdated_;                         ///< True if an entry is created
    248378    };
    249379
    … …  
    252382    // ConfigFile //
    253383    ////////////////
     384    /**
     385        @brief This class represents a config file, which is stored on the hard-disk and contains config values in different sections.
     386
     387        It provides an interface to manipulate the sections and values.
     388    */
    254389    class _CoreExport ConfigFile
    255390    {
    … …  
    263398            virtual void clear();
    264399
     400            /// Returns the file-name of this config file
    265401            inline const std::string& getFilename()
    266402                { return this->filename_; }
    267403
     404            /**
     405                @brief Stores a value in the config file. If the entry or its section doesn't exist, it's created.
     406
     407                @param section  The name of the section
     408                @param name     The name of the entry
     409                @param value    The new value
     410                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     411            */
    268412            inline void setValue(const std::string& section, const std::string& name, const std::string& value, bool bString)
    269413            {
    … …  
    271415                this->save();
    272416            }
     417            /**
     418                @brief Returns the value of a given entry in the config file. Returns a blank string if the value doesn't exist.
     419
     420                @param section  The name of the section
     421                @param name     The name of the entry
     422                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     423            */
    273424            inline const std::string& getValue(const std::string& section, const std::string& name, bool bString)
    274425            {
    … …  
    276427                return (sectionPtr ? sectionPtr->getValue(name, bString) : BLANKSTRING);
    277428            }
    278             const std::string& getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString);
    279 
     429            /**
     430                @brief Returns the value of a given entry in the config file. If it doesn't exist, the entry is created using the fallback value.
     431
     432                @param section  The name of the section
     433                @param name     The name of the entry
     434                @param fallback The value that will be used if the entry doesn't exist
     435                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     436            */
     437            inline const std::string& getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString)
     438            {
     439                const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, fallback, bString);
     440                this->saveIfUpdated();
     441                return output;
     442            }
     443
     444            /**
     445                @brief Stores the value of an element of a vector in the config file. If the entry or its section doesn't exist, it's created.
     446
     447                @param section  The name of the section
     448                @param name     The name of the vector
     449                @param index    The index of the element in the vector
     450                @param value    The new value
     451                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     452            */
    280453            inline void setValue(const std::string& section, const std::string& name, unsigned int index, const std::string& value, bool bString)
    281454            {
    … …  
    283456                this->save();
    284457            }
     458            /**
     459                @brief Returns the value of a given element of a vector in the config file. Returns a blank string if the value doesn't exist.
     460
     461                @param section  The name of the section
     462                @param name     The name of the vector
     463                @param index    The index of the element in the vector
     464                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     465            */
    285466            inline const std::string& getValue(const std::string& section, const std::string& name, unsigned int index, bool bString)
    286467            {
    … …  
    288469                return (sectionPtr ? sectionPtr->getValue(name, index, bString) : BLANKSTRING);
    289470            }
    290             const std::string& getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString);
     471            /**
     472                @brief Returns the value of a given element of a vector in the config file. If it doesn't exist, the entry is created using the fallback value.
     473
     474                @param section  The name of the section
     475                @param name     The name of the vector
     476                @param index    The index of the element in the vector
     477                @param fallback The value that will be used if the entry doesn't exist
     478                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     479            */
     480            const std::string& getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString)
     481            {
     482                const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, index, fallback, bString);
     483                this->saveIfUpdated();
     484                return output;
     485            }
    291486
    292487            void deleteVectorEntries(const std::string& section, const std::string& name, unsigned int startindex = 0);
     488            /**
     489                @brief Returns the size of a config vector.
     490                @param section  The section of the vector
     491                @param name     The name of the vector
     492            */
    293493            inline unsigned int getVectorSize(const std::string& section, const std::string& name) const
    294494            {
    … …  
    297497            }
    298498
    299             static const char* DEFAULT_CONFIG_FOLDER;
     499            static const char* DEFAULT_CONFIG_FOLDER;   ///< The folder where the default config files will be stored
    300500
    301501        protected:
    … …  
    303503            ConfigFileSection* getOrCreateSection(const std::string& section);
    304504
    305             std::list<ConfigFileSection*> sections_;
     505            std::list<ConfigFileSection*> sections_;    ///< A list of sections in this config file
    306506
    307507        private:
    308508            void saveIfUpdated();
    309             const std::string filename_;
    310             const bool bCopyFallbackFile_;
    311             bool bUpdated_;
     509
     510            const std::string filename_;                ///< The filename of this config file
     511            const bool bCopyFallbackFile_;              ///< If true, the default config file is copied into the config-directory before loading the file
     512            bool bUpdated_;                             ///< Becomes true if a section is added
    312513    };
    313514
    … …  
    316517    // SettingsConfigFile //
    317518    ////////////////////////
     519    /**
     520        @brief Child class of ConfigFile, used to store the settings of the game.
     521
     522        In addition to ConfigFile, this class provides an interface to manipulate the settings
     523        with console commands and to cache entries in instances of ConfigValueContainer.
     524
     525        SettingsConfigFile is a Singleton, meaning there's only one instance of this class
     526        (and thus only one config file that stores settings).
     527    */
    318528    class _CoreExport SettingsConfigFile // tolua_export
    319529        : public ConfigFile, public Singleton<SettingsConfigFile>
    … …  
    338548            void removeConfigValueContainer(ConfigValueContainer* container);
    339549
     550            /// Returns a set containing the names of all sections in this config file.
    340551            inline const std::set<std::string>& getSectionNames()
    341552                { return this->sectionNames_; }
     553            /// Returns the lower-bound-iterator of the @ref ConfigValueContainer "config value containers" for the given section.
    342554            inline ContainerMap::const_iterator getContainerLowerBound(const std::string section)
    343555                { return this->containers_.lower_bound(section); }
     556            /// Returns the upper-bound-iterator of the @ref ConfigValueContainer "config value containers" for the given section.
    344557            inline ContainerMap::const_iterator getContainerUpperBound(const std::string section)
    345558                { return this->containers_.upper_bound(section); }
    … …  
    351564            bool configImpl(const std::string& section, const std::string& entry, const std::string& value, bool (ConfigValueContainer::*function)(const MultiType&));
    352565
    353             ContainerMap containers_;
    354             std::set<std::string> sectionNames_;
    355             static SettingsConfigFile* singletonPtr_s;
     566            ContainerMap containers_;                   ///< Stores all @ref ConfigValueContainer "config value containers"
     567            std::set<std::string> sectionNames_;        ///< Stores all section names
     568            static SettingsConfigFile* singletonPtr_s;  ///< The singleton pointer
    356569    }; // tolua_export
    357570
    … …  
    360573    // ConfigFileManager //
    361574    ///////////////////////
     575    /**
     576        @brief Manages the different config files (settings, calibration, etc). Implemented as Singleton.
     577    */
    362578    class _CoreExport ConfigFileManager : public Singleton<ConfigFileManager>
    363579    {
    … …  
    369585            void setFilename(ConfigFileType::Value type, const std::string& filename);
    370586
     587            /// Returns the config file of a given type (settings, calibration, etc.)
    371588            inline ConfigFile* getConfigFile(ConfigFileType::Value type)
    372589            {
    … …  
    376593
    377594        private:
    378             ConfigFileManager(const ConfigFileManager&);
    379 
    380             boost::array<ConfigFile*, 3> configFiles_;
    381             static ConfigFileManager* singletonPtr_s;
     595            ConfigFileManager(const ConfigFileManager&);    ///< Copy-constructor: not implemented
     596
     597            boost::array<ConfigFile*, 3> configFiles_;      ///< Stores the config files for each type in an array (must have the same size like ConfigFileType::Value)
     598            static ConfigFileManager* singletonPtr_s;       ///< Stores the singleton-pointer
    382599    };
    383600} // tolua_export

  • code/trunk/src/libraries/core/ConfigValueContainer.h

    r6536 r7401  
    2929/**
    3030    @file
    31     @brief Definition of the ConfigValueContainer class.
     31    @ingroup Config ConfigFile
     32    @brief Declaration of the ConfigValueContainer class, caches a config-value.
    3233
    3334    The ConfigValueContainer class contains all needed information about a configurable variable:
    … …  
    7879
    7980
    80     //! The ConfigValuecontainer contains all needed information about a configurable variable.
    8181    /**
     82        @brief The ConfigValuecontainer contains all needed information about a configurable variable.
     83
    8284        The ConfigValueContainer class contains all needed information about a configurable variable:
    8385         - the name of the variable
    … …  
    117119                @param type The type of the corresponding config-file
    118120                @param identifier The identifier of the class the variable belongs to
     121                @param sectionname Name of the section the configValue should be put in.
    119122                @param varname The name of the variable
    120123                @param defvalue The default-value
     124                @param value Only needed do determine the right type.
    121125            */
    122126            template <class D, class V>
    … …  
    213217            }
    214218
    215             /** @brief Returns the name of this container. */
     219            /// Returns the name of this container.
    216220            inline const std::string& getName() const
    217221                { return this->varname_; }
    218             /** @brief Returns the name of the section this config value is in. */
     222            /// Returns the name of the section this config value is in.
    219223            inline const std::string& getSectionName() const
    220224                { return this->sectionname_; }
    221             /** @brief Returns the associated identifier (can be NULL). */
     225            /// Returns the associated identifier (can be NULL).
    222226            inline Identifier* getIdentifier() const
    223227                { return this->identifier_; }
    224             /** @brief Returns true if this config-value is a vector */
     228            /// Returns true if this config-value is a vector.
    225229            inline bool isVector() const
    226230                { return this->bIsVector_; }
    227             /** @brief Returns the vectors size (or zero if it's not a vector). */
     231            /// Returns the vectors size (or zero if it's not a vector).
    228232            inline unsigned int getVectorSize() const
    229233                { return this->valueVector_.size(); }
    … …  
    265269            void update();
    266270
    267             /** @brief Converts the config-value to a string. @return The string */
     271            /// Converts the config-value to a string.
    268272            inline std::string toString() const
    269273                { return this->value_; }
    270             /** @brief Returns the typename of the assigned config-value. @return The typename */
     274            /// Returns the typename of the assigned config-value.
    271275            inline std::string getTypename() const
    272276                { return this->value_.getTypename(); }

  • code/trunk/src/libraries/core/ConfigValueIncludes.h

    r7166 r7401  
    2828
    2929/**
    30 @file
    31 @brief
    32     Definition of macros and functions for config-values.
     30    @defgroup ConfigFile Config file
     31    @ingroup Config
     32*/
     33
     34/**
     35    @file
     36    @ingroup Config ConfigFile
     37    @brief Definition of macros and functions for config-values.
     38
     39    An example of how to use SetConfigValue():
     40
     41    Definition of a class in the header-file:
     42    @code
     43    class MyClass : public BaseObject
     44    {
     45        public:
     46            MyClass();              // Constructor
     47            void setConfigValues(); // Inherited function
     48
     49            const std::string& getName()
     50                { return this->name_; }
     51
     52            float getVersion()
     53                { return this->version_; }
     54
     55        private:
     56            std::string name_;
     57            float version_;
     58    };
     59    @endcode
     60
     61    Implementation of the class source-file:
     62    @code
     63    MyClass::MyClass()
     64    {
     65        // Macro-call to create an Identifier
     66        RegisterObject(MyClass);
     67
     68        // Function-call to assign the config-values to the new object
     69        this->setConfigValues();
     70    }
     71
     72    void MyClass::setConfigValues()
     73    {
     74        SetConfigValue(name_, "Orxonox").description("The name of the game");
     75        SetConfigValue(version_, "1.0").description("The version-number");
     76    }
     77    @endcode
     78
     79    Extract of orxonox.ini:
     80    @code
     81    [MyClass]
     82    name_ = "Orxonox"
     83    version_ = 1.1 // We have changed this value from 1.0 to 1.1
     84    @endcode
     85
     86    Some other code:
     87    @code
     88    MyObject orxonoxobject;
     89    std::cout << "Name:    " << orxonoxobject.getName() << std::endl;
     90    std::cout << "Version: " << orxonoxobject.getVersion() << std::endl;
     91    @endcode
     92
     93    Output:
     94    @code
     95    Name:    Orxonox
     96    Version: 1.1
     97    @endcode
    3398*/
    3499

  • code/trunk/src/libraries/core/Core.cc

    r7284 r7401  
    3737
    3838#include <cassert>
     39#include <fstream>
    3940#include <vector>
    4041
    … …  
    171172        // Create singletons that always exist (in other libraries)
    172173        this->rootScope_.reset(new Scope<ScopeID::Root>());
     174
     175        // Generate documentation instead of normal run?
     176        std::string docFilename;
     177        CommandLineParser::getValue("generateDoc", &docFilename);
     178        if (!docFilename.empty())
     179        {
     180            std::ofstream docFile(docFilename.c_str());
     181            if (docFile.is_open())
     182            {
     183                CommandLineParser::generateDoc(docFile);
     184                docFile.close();
     185            }
     186            else
     187                COUT(0) << "Error: Could not open file for documentation writing" << endl;
     188        }
    173189    }
    174190

  • code/trunk/src/libraries/core/Core.h

    r7266 r7401  
    2828 */
    2929
     30/**
     31    @defgroup CoreGame Core and Game
     32    @ingroup Management
     33*/
     34
     35/**
     36    @file
     37    @ingroup Management CoreGame
     38    @brief Declaration of the Core singleton which is used to configure the program basics.
     39*/
     40
    3041#ifndef _Core_H__
    3142#define _Core_H__
    … …  
    3344#include "CorePrereqs.h"
    3445
    35 #include <cassert>
    3646#include <string>
    3747#include <boost/scoped_ptr.hpp>

  • code/trunk/src/libraries/core/CoreIncludes.h

    r6423 r7401  
    2828
    2929/**
     30    @defgroup Factory RegisterObject() and CreateFactory()
     31    @ingroup Object
     32*/
     33
     34/**
    3035    @file
    31     @brief Definition of macros for Identifiers
     36    @ingroup Object Factory
     37    @brief Defines several very important macros used to register objects, create factories, and to work with identifiers.
    3238
    33     Every class needs the RegisterObject(class) macro in its constructor. If the class is an interface
    34     or the BaseObject itself, it needs the macro RegisterRootObject(class) instead.
     39    Every class needs the @c RegisterObject(class) macro in its constructor. If the class is an interface
     40    or the @c BaseObject itself, it needs the macro @c RegisterRootObject(class) instead.
    3541
    36     To allow the object being created through the factory, use the CreateFactory(class) macro outside
    37     the of the class implementation, so it gets executed before main().
     42    To allow the object being created through the factory, use the @c CreateFactory(class) macro outside
     43    of the class implementation, so it gets executed statically before @c main(). This will at the same time
     44    register @a class in the class-hierarchy. If you don't want @a class to be loadable, but still
     45    register it, call @c CreateUnloadableFactory(class).
     46
     47    Example:
     48    @code
     49    // Create the factory for MyClass
     50    CreateFactory(MyClass);
     51
     52    // Constructor:
     53    MyClass::MyClass()
     54    {
     55        // Register the object in the Identifier of MyClass
     56        RegisterObject(MyClass);
     57    }
     58    @endcode
     59
     60    This file also defines a number of other useful macros, like, for example, @c Class(class) which
     61    returns the @ref orxonox::Identifier "Identifier" of @a class, or @c ClassByString("class") which
     62    returns the Identifier of a class with name @a "class".
     63
     64    Example:
     65    @code
     66    // Assigns the Identifier of MyClass
     67    Identifier* identifier = Class(MyClass);
     68    @endcode
     69    @code
     70    // Assigns the Identifier of a class named "MyClass"
     71    Identifier* identifier = ClassByString("MyClass");
     72    @endcode
    3873*/
    3974
    … …  
    5186
    5287/**
    53     @brief Intern macro, containing the common parts of RegisterObject and RegisterRootObject.
     88    @brief Intern macro, containing the common parts of @c RegisterObject and @c RegisterRootObject.
    5489    @param ClassName The name of the class
    55     @param bRootClass True if the class is directly derived from OrxonoxClass
     90    @param bRootClass True if the class is directly derived from orxonox::OrxonoxClass
    5691*/
    5792#define InternRegisterObject(ClassName, bRootClass) \
    … …  
    6297
    6398/**
    64     @brief RegisterObject - with and without debug output.
     99    @brief Registers a newly created object in the core. Has to be called at the beginning of the constructor of @a ClassName.
    65100    @param ClassName The name of the class
    66101*/
    … …  
    69104
    70105/**
    71     @brief RegisterRootObject - with and without debug output.
     106    @brief Registers a newly created object in the core. Has to be called at the beginning of the constructor of @a ClassName.
    72107    @param ClassName The name of the class
     108
     109    In contrast to RegisterObject, this is used for classes that inherit directly from
     110    orxonox::OrxonoxClass, namely all interfaces and orxonox::BaseObject.
    73111*/
    74112#define RegisterRootObject(ClassName) \
    … …  
    101139    /**
    102140        @brief Returns the Identifier with a given name.
    103         @param String The name of the class
     141        @param name The name of the class
    104142    */
    105143    inline Identifier* ClassByString(const std::string& name)
    … …  
    110148    /**
    111149        @brief Returns the Identifier with a given lowercase name.
    112         @param String The lowercase name of the class
     150        @param name The lowercase name of the class
    113151    */
    114152    inline Identifier* ClassByLowercaseString(const std::string& name)
    … …  
    119157    /**
    120158        @brief Returns the Identifier with a given network ID.
    121         @param networkID The network ID of the class
     159        @param id The network ID of the class
    122160    */
    123161    inline Identifier* ClassByID(uint32_t id)
    … …  
    130168        @note This of course only works with OrxonoxClasses.
    131169              The only use is in conjunction with macros that don't know the class type.
    132         @param Pointer to an OrxonoxClass
     170        @param object Pointer to an OrxonoxClass
    133171    */
    134172    template <class T>

  • code/trunk/src/libraries/core/DynLib.h

    r6073 r7401  
    2929
    3030// 08/11/2009: Small adjustments for Orxonox by Fabian 'x3n' Landau
     31
     32/**
     33    @file
     34    @ingroup Management CoreGame
     35    @brief Declaration of DynLib which represents a dynamically loaded module.
     36*/
    3137
    3238#ifndef _Core_DynLib_H__
    … …  
    6167namespace orxonox
    6268{
    63     /** Resource holding data about a dynamic library.
     69    /** %Resource holding data about a dynamic library.
    6470        @remarks
    6571            This class holds the data required to get symbols from
    … …  
    6975        @since
    7076            27 January 2002
    71         @see
    72             Resource
    7377    */
    7478    class _CoreExport DynLib

  • code/trunk/src/libraries/core/DynLibManager.h

    r5738 r7401  
    3030// 08/11/2009: Small adjustments for Orxonox by Fabian 'x3n' Landau
    3131
     32/**
     33    @file
     34    @ingroup Management CoreGame
     35    @brief Declaration of DynLibManager, used to load modules at runtime.
     36*/
     37
    3238#ifndef _Core_DynLibManager_H__
    3339#define _Core_DynLibManager_H__
    … …  
    5662
    5763        public:
    58             /** Default constructor.
    59                 @note
    60                     <br>Should never be called as the singleton is automatically
    61                     created during the creation of the Root object.
    62                 @see
    63                     Root::Root
     64            /**
     65            @brief
     66                Default constructor.
     67            @note
     68                Should never be called as the singleton is automatically
     69                created during the creation of the Root object.
     70            @see
     71                Root::Root
    6472            */
    6573            DynLibManager();
    6674
    67             /** Default destructor.
    68                 @see
    69                     Root::~Root
     75            /**
     76            @brief
     77                Default destructor.
     78            @see
     79                Root::~Root
    7080            */
    7181            virtual ~DynLibManager();
    7282
    73             /** Loads the passed library.
    74                 @param
    75                     filename The name of the library. The extension can be omitted
     83            /**
     84            @brief
     85                Loads the passed library.
     86            @param filename
     87                The name of the library. The extension can be omitted
    7688            */
    7789            DynLib* load(const std::string& filename);
    7890
    79             /** Unloads the passed library.
    80             @param
    81             filename The name of the library. The extension can be omitted
     91            /**
     92            @brief
     93                Unloads the passed library.
     94            @param lib
     95                A pointer to the library object
    8296            */
    8397            void unload(DynLib* lib);

  • code/trunk/src/libraries/core/Event.cc

    r7284 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @brief Implementation of the classes Event and EventState.
     32*/
    2833
    2934#include "Event.h"

  • code/trunk/src/libraries/core/Event.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @defgroup Event Events
     31    @ingroup Core
     32*/
     33
     34/**
     35    @file
     36    @ingroup Event
     37    @brief Declaration of the classes Event and EventState.
     38*/
     39
    2940#ifndef _Event_H__
    3041#define _Event_H__
    … …  
    5465        An event state is a state of an object, which can be changed by events.
    5566        Event states are changed through functions. Possible functions headers for set event states are:
    56          - memoryless state: function()
    57          - boolean state:    function(bool state)
    58          - individual state: function(bool state, SomeClass originator)
     67         - memoryless state: <tt>function()</tt>
     68         - boolean state:    <tt>function(bool state)</tt>
     69         - individual state: <tt>function(bool state, SomeClass originator)</tt>
    5970
    6071        Note that SomeClass may be any class deriving from BaseObject. You will not receive events from originators of other classes.
    61         The actual class for SomeClass must be specified as the second argument of the XMLPortEventState macro.
     72        The actual class for SomeClass must be specified as the second argument of the XMLPortEventState() macro.
    6273
    6374        The this pointer of the affected object is hidden in the functors, because the events are processed in the BaseObject, but some

  • code/trunk/src/libraries/core/EventIncludes.h

    r7301 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup Event
     32    @brief Definition of the XMLPortEventState() macro, as well as some more useful macros.
     33*/
    2834
    2935#ifndef _EventIncludes_H__

  • code/trunk/src/libraries/core/GUIManager.cc

    r7284 r7401  
    110110        After Lua setup tolua++-elements are linked to Lua-state to give Lua access to C++-code.
    111111        Finally initial Lua code is executed (maybe we can do this with the CEGUI startup script automatically).
    112     @param renderWindow
    113         Ogre's render window. Without this, the GUI cannot be displayed.
    114112    @return true if success, otherwise false
    115113    */
    … …  
    237235    @param name
    238236        The name of the GUI
     237    @param bHidePrevious
     238        If true all displayed GUIs on the stack, that are below this GUI are hidden.
    239239
    240240        The function executes the Lua function with the same name in case the GUIManager is ready.

  • code/trunk/src/libraries/core/GUIManager.h

    r7163 r7401  
    2727 *
    2828 */
     29
     30/**
     31    @file
     32    @ingroup Graphics
     33*/
    2934
    3035#ifndef _GUIManager_H__

  • code/trunk/src/libraries/core/Game.h

    r7266 r7401  
    2929/**
    3030@file
     31@ingroup Management CoreGame
    3132@brief
    32     Declaration of Game Singleton.
     33    Declaration of Game Singleton which is responsible for running the game.
    3334 */
    3435
    … …  
    5354
    5455/**
    55 @def
     56@brief
    5657    Adds a new GameState to the Game. The second parameter is the name as string
    5758    and every following paramter is a constructor argument (which is usually non existent)

  • code/trunk/src/libraries/core/GameMode.cc

    r5929 r7401  
    3333    bool GameMode::bShowsGraphics_s = false;
    3434    bool GameMode::bPlaysSound_s    = false;
    35     bool GameMode::bHasServer_s     = false;
     35    bool GameMode::bIsServer_s      = false;
    3636    bool GameMode::bIsClient_s      = false;
    3737    bool GameMode::bIsStandalone_s  = false;

  • code/trunk/src/libraries/core/GameMode.h

    r6417 r7401  
    2929/**
    3030    @file
    31     @brief Declaration of the GameMode class.
     31    @ingroup Management CoreGame
     32    @brief Declaration of the GameMode class which stores and returns the current mode of the game.
    3233*/
    3334
    … …  
    4041namespace orxonox
    4142{
     43    /// Helper class, stores and returns the current mode of the game.
    4244    class _CoreExport GameMode
    4345    {
    … …  
    4749        public:
    4850// tolua_begin
    49             static bool showsGraphics() { return bShowsGraphics_s; }
    50             static bool playsSound()    { return bPlaysSound_s; }
    51             static bool hasServer()     { return bHasServer_s; }
    52             static bool isClient()      { return bIsClient_s; }
    53             static bool isStandalone()  { return bIsStandalone_s; }
    54             static bool isMaster()      { return bIsMaster_s; }
     51            static bool showsGraphics() { return bShowsGraphics_s; }    ///< Returns true if the game shows graphics, false if it is in text-console mode
     52            static bool playsSound()    { return bPlaysSound_s; }       ///< Returns true if the game is able to play sounds
     53            static bool isServer()      { return bIsServer_s; }         ///< Returns true if we're currently a server (online)
     54            static bool isClient()      { return bIsClient_s; }         ///< Returns true if we're currently a client (online)
     55            static bool isStandalone()  { return bIsStandalone_s; }     ///< Returns true if we're in standalone mode (offline)
     56            static bool isMaster()      { return bIsMaster_s; }         ///< Returns true if we're in control of the game (either standalone or server)
    5557// tolua_end
    5658
    57             static void setPlaysSound   (bool val) { bPlaysSound_s    = val; }
    58             static void setHasServer    (bool val) { bHasServer_s     = val; updateIsMaster(); }
    59             static void setIsClient     (bool val) { bIsClient_s      = val; updateIsMaster(); }
    60             static void setIsStandalone (bool val) { bIsStandalone_s  = val; updateIsMaster(); }
     59            static void setPlaysSound   (bool val) { bPlaysSound_s    = val; }                      ///< Defines if the game can play sounds
     60            static void setIsServer     (bool val) { bIsServer_s      = val; updateIsMaster(); }    ///< Defines if the program is in server mode (online)
     61            static void setIsClient     (bool val) { bIsClient_s      = val; updateIsMaster(); }    ///< Defines if the program is in client mode (online)
     62            static void setIsStandalone (bool val) { bIsStandalone_s  = val; updateIsMaster(); }    ///< Defines if the program is in standalone mode (offline)
    6163
    6264        private:
    … …  
    6567            ~GameMode();
    6668
     69            /// Checks if we're in control of the game (either standalone or server).
    6770            static void updateIsMaster()
    6871            {
    69                 bIsMaster_s = (bHasServer_s || bIsStandalone_s);
     72                bIsMaster_s = (bIsServer_s || bIsStandalone_s);
    7073            }
    7174
    7275            static bool bShowsGraphics_s;                   //!< global variable that tells whether to show graphics
    7376            static bool bPlaysSound_s;                      //!< global variable that tells whether to sound works
    74             static bool bHasServer_s;                       //!< global variable that tells whether this is a server
    75             static bool bIsClient_s;
    76             static bool bIsStandalone_s;
    77             static bool bIsMaster_s;
     77            static bool bIsServer_s;                        //!< global variable that tells whether this is a server (online)
     78            static bool bIsClient_s;                        //!< global variable that tells whether this is a client (online)
     79            static bool bIsStandalone_s;                    //!< global variable that tells whether the game is running in standalone mode (offline)
     80            static bool bIsMaster_s;                        //!< global variable that tells whether we're in control of the game (standalone or server)
    7881    }; // tolua_export
    7982} // tolua_export

  • code/trunk/src/libraries/core/GameState.h

    r5929 r7401  
    2929/**
    3030@file
     31@ingroup Management CoreGame
    3132@brief
    3233    Definition of GameState class.

  • code/trunk/src/libraries/core/GraphicsManager.h

    r7284 r7401  
    2929
    3030/**
     31    @defgroup Graphics Graphics and GUI
     32    @ingroup Core
     33*/
     34
     35/**
    3136@file
     37@ingroup Graphics
    3238@brief
    3339    Declaration of GraphicsManager Singleton.

  • code/trunk/src/libraries/core/Identifier.cc

    r7284 r7401  
    217217    /**
    218218        @brief Sets the name of the class.
    219         @param name The name
    220219    */
    221220    void Identifier::setName(const std::string& name)
    … …  
    253252    /**
    254253        @brief Sets the network ID to a new value and changes the entry in the ID-Identifier-map.
    255         @param id The new network ID
    256254    */
    257255    void Identifier::setNetworkID(uint32_t id)

  • code/trunk/src/libraries/core/Identifier.h

    r7284 r7401  
    2828
    2929/**
     30    @defgroup Identifier Identifier
     31    @ingroup Class
     32*/
     33
     34/**
    3035    @file
    31     @brief Definition of the Identifier class, definition and implementation of the ClassIdentifier class.
    32 
    33     The Identifier contains all needed information about the class it belongs to:
    34      - the name
    35      - a list with all objects
    36      - parents and children
    37      - the factory (if available)
    38      - the networkID that can be synchronised with the server
    39      - all configurable variables (if available)
    40 
    41     Every object has a pointer to the Identifier of its class. This allows the use isA(...),
    42     isExactlyA(...), isChildOf(...) and isParentOf(...).
    43 
    44     To create the class-hierarchy, the Identifier has some intern functions and variables.
    45 
    46     Every Identifier is in fact a ClassIdentifier, but they are derived from Identifier.
     36    @ingroup Class Identifier
     37    @brief Declaration of Identifier, definition of ClassIdentifier<T>; used to identify the class of an object.
     38
     39    @anchor IdentifierExample
     40
     41    An Identifier "identifies" the class of an object. It contains different information about
     42    the class: Its name and ID, a list of all instances of this class, a factory to create new
     43    instances of this class, and more.
     44
     45    It also contains information about the inheritance of this class: It stores a list of the
     46    Identifiers of all parent-classes as well as a list of all child-classes. These relationships
     47    can be tested using functions like @c isA(), @c isChildOf(), @c isParentOf(), and more.
     48
     49    Every Identifier is in fact a ClassIdentifier<T> (where T is the class that is identified
     50    by the Identifier), Identifier is just the common base-class.
     51
     52    Example:
     53    @code
     54    MyClass* object = new MyClass();                                            // create an instance of MyClass
     55
     56    object->getIdentifier()->getName();                                         // returns "MyClass"
     57
     58    BaseObject* other = object->getIdentifier()->fabricate(0);                  // fabricates a new instance of MyClass
     59
     60
     61    // iterate through all objects of type MyClass:
     62    ObjectListBase* objects = object->getIdentifier()->getObjects();            // get a pointer to the object-list
     63    int count;
     64    for (Iterator<BaseObject> it = objects.begin(); it != objects.end(); ++it)  // iterate through the objects
     65        ++count;
     66    COUT(0) << count << std::endl;                                              // prints "2" because we created 2 instances of MyClass so far
     67
     68
     69    // test the class hierarchy
     70    object->getIdentifier()->isA(Class(MyClass));                               // returns true
     71    object->isA(Class(MyClass));                                                // returns true (short version)
     72
     73    object->isA(Class(BaseClass));                                              // returns true if MyClass is a child of BaseClass
     74
     75    Class(ChildClass)->isChildOf(object->getIdentifier());                      // returns true if ChildClass is a child of MyClass
     76    @endcode
    4777*/
    4878
    … …  
    70100    // ###       Identifier        ###
    71101    // ###############################
    72     //! The Identifier is used to identify the class of an object and to store information about the class.
    73     /**
    74         The Identifier contains all needed information about the class it belongs to:
    75          - the name
    76          - a list with all objects
    77          - parents and children
    78          - the factory (if available)
    79          - the networkID that can be synchronised with the server
    80          - all configurable variables (if available)
    81 
    82         Every object has a pointer to the Identifier of its class. This allows the use isA(...),
    83         isExactlyA(...), isChildOf(...) and isParentOf(...).
    84 
    85         You can't directly create an Identifier, it's just the base-class for ClassIdentifier.
     102    /**
     103        @brief The Identifier is used to identify the class of an object and to store information about the class.
     104
     105        Each Identifier stores information about one class. The Identifier can then be used to identify
     106        this class. On the other hand it's also possible to get the corresponding Identifier of a class,
     107        for example by using the macro Class().
     108
     109        @see See @ref IdentifierExample "Identifier.h" for more information and some examples.
     110
     111        @note You can't directly create an Identifier, it's just the base-class of ClassIdentifier<T>.
    86112    */
    87113    class _CoreExport Identifier
    88114    {
    89115        public:
    90             /** @brief Returns the name of the class the Identifier belongs to. @return The name */
     116            /// Returns the name of the class the Identifier belongs to.
    91117            inline const std::string& getName() const { return this->name_; }
    92118            void setName(const std::string& name);
    93119
    94             /** @brief Returns the network ID to identify a class through the network. @return the network ID */
     120            /// Returns the network ID to identify a class through the network.
    95121            inline const uint32_t getNetworkID() const { return this->networkID_; }
    96122            void setNetworkID(uint32_t id);
    97123
    98             /** @brief Returns the unique ID of the class */
     124            /// Returns the unique ID of the class.
    99125            FORCEINLINE unsigned int getClassID() const { return this->classID_; }
    100126
    101             /** @brief Returns the list of all existing objects of this class. @return The list */
     127            /// Returns the list of all existing objects of this class.
    102128            inline ObjectListBase* getObjects() const { return this->objects_; }
    103129
    104             /** @brief Sets the Factory. @param factory The factory to assign */
     130            /// Sets the Factory.
    105131            inline void addFactory(Factory* factory) { this->factory_ = factory; }
    106             /** @brief Returns true if the Identifier has a Factory. */
     132            /// Returns true if the Identifier has a Factory.
    107133            inline bool hasFactory() const { return (this->factory_ != 0); }
    108134
    109135            BaseObject* fabricate(BaseObject* creator);
    110136
    111             /** @brief Returns true if the class can be loaded through XML. */
     137            /// Returns true if the class can be loaded through XML.
    112138            inline bool isLoadable() const { return this->bLoadable_; }
    113             /** @brief Set the class to be loadable through XML or not. */
     139            /// Set the class to be loadable through XML or not.
    114140            inline void setLoadable(bool bLoadable) { this->bLoadable_ = bLoadable; }
    115141
    … …  
    127153            static void createClassHierarchy();
    128154
    129             /** @brief Returns true, if a branch of the class-hierarchy is being created, causing all new objects to store their parents. @return The status of the class-hierarchy creation */
     155            /// Returns true, if a branch of the class-hierarchy is being created, causing all new objects to store their parents.
    130156            inline static bool isCreatingHierarchy() { return (hierarchyCreatingCounter_s > 0); }
    131157
    132             /** @brief Returns the parents of the class the Identifier belongs to. @return The list of all parents */
     158            /// Returns the parents of the class the Identifier belongs to.
    133159            inline const std::set<const Identifier*>& getParents() const { return this->parents_; }
    134             /** @brief Returns the begin-iterator of the parents-list. @return The begin-iterator */
     160            /// Returns the begin-iterator of the parents-list.
    135161            inline std::set<const Identifier*>::const_iterator getParentsBegin() const { return this->parents_.begin(); }
    136             /** @brief Returns the end-iterator of the parents-list. @return The end-iterator */
     162            /// Returns the end-iterator of the parents-list.
    137163            inline std::set<const Identifier*>::const_iterator getParentsEnd() const { return this->parents_.end(); }
    138164
    139             /** @brief Returns the children of the class the Identifier belongs to. @return The list of all children */
     165            /// Returns the children of the class the Identifier belongs to.
    140166            inline const std::set<const Identifier*>& getChildren() const { return this->children_; }
    141             /** @brief Returns the begin-iterator of the children-list. @return The begin-iterator */
     167            /// Returns the begin-iterator of the children-list.
    142168            inline std::set<const Identifier*>::const_iterator getChildrenBegin() const { return this->children_.begin(); }
    143             /** @brief Returns the end-iterator of the children-list. @return The end-iterator */
     169            /// Returns the end-iterator of the children-list.
    144170            inline std::set<const Identifier*>::const_iterator getChildrenEnd() const { return this->children_.end(); }
    145171
    146             /** @brief Returns the direct parents of the class the Identifier belongs to. @return The list of all direct parents */
     172            /// Returns the direct parents of the class the Identifier belongs to.
    147173            inline const std::set<const Identifier*>& getDirectParents() const { return this->directParents_; }
    148             /** @brief Returns the begin-iterator of the direct-parents-list. @return The begin-iterator */
     174            /// Returns the begin-iterator of the direct-parents-list.
    149175            inline std::set<const Identifier*>::const_iterator getDirectParentsBegin() const { return this->directParents_.begin(); }
    150             /** @brief Returns the end-iterator of the direct-parents-list. @return The end-iterator */
     176            /// Returns the end-iterator of the direct-parents-list.
    151177            inline std::set<const Identifier*>::const_iterator getDirectParentsEnd() const { return this->directParents_.end(); }
    152178
    153             /** @brief Returns the direct children the class the Identifier belongs to. @return The list of all direct children */
     179            /// Returns the direct children the class the Identifier belongs to.
    154180            inline const std::set<const Identifier*>& getDirectChildren() const { return this->directChildren_; }
    155             /** @brief Returns the begin-iterator of the direct-children-list. @return The begin-iterator */
     181            /// Returns the begin-iterator of the direct-children-list.
    156182            inline std::set<const Identifier*>::const_iterator getDirectChildrenBegin() const { return this->directChildren_.begin(); }
    157             /** @brief Returns the end-iterator of the direct-children-list. @return The end-iterator */
     183            /// Returns the end-iterator of the direct-children-list.
    158184            inline std::set<const Identifier*>::const_iterator getDirectChildrenEnd() const { return this->directChildren_.end(); }
    159185
    … …  
    170196            static void clearNetworkIDs();
    171197
    172             /** @brief Returns the map that stores all Identifiers with their names. @return The map */
     198            /// Returns the map that stores all Identifiers with their names.
    173199            static inline const std::map<std::string, Identifier*>& getStringIdentifierMap() { return Identifier::getStringIdentifierMapIntern(); }
    174             /** @brief Returns a const_iterator to the beginning of the map that stores all Identifiers with their names. @return The const_iterator */
     200            /// Returns a const_iterator to the beginning of the map that stores all Identifiers with their names.
    175201            static inline std::map<std::string, Identifier*>::const_iterator getStringIdentifierMapBegin() { return Identifier::getStringIdentifierMap().begin(); }
    176             /** @brief Returns a const_iterator to the end of the map that stores all Identifiers with their names. @return The const_iterator */
     202            /// Returns a const_iterator to the end of the map that stores all Identifiers with their names.
    177203            static inline std::map<std::string, Identifier*>::const_iterator getStringIdentifierMapEnd() { return Identifier::getStringIdentifierMap().end(); }
    178204
    179             /** @brief Returns the map that stores all Identifiers with their names in lowercase. @return The map */
     205            /// Returns the map that stores all Identifiers with their names in lowercase.
    180206            static inline const std::map<std::string, Identifier*>& getLowercaseStringIdentifierMap() { return Identifier::getLowercaseStringIdentifierMapIntern(); }
    181             /** @brief Returns a const_iterator to the beginning of the map that stores all Identifiers with their names in lowercase. @return The const_iterator */
     207            /// Returns a const_iterator to the beginning of the map that stores all Identifiers with their names in lowercase.
    182208            static inline std::map<std::string, Identifier*>::const_iterator getLowercaseStringIdentifierMapBegin() { return Identifier::getLowercaseStringIdentifierMap().begin(); }
    183             /** @brief Returns a const_iterator to the end of the map that stores all Identifiers with their names in lowercase. @return The const_iterator */
     209            /// Returns a const_iterator to the end of the map that stores all Identifiers with their names in lowercase.
    184210            static inline std::map<std::string, Identifier*>::const_iterator getLowercaseStringIdentifierMapEnd() { return Identifier::getLowercaseStringIdentifierMap().end(); }
    185211
    186             /** @brief Returns the map that stores all Identifiers with their IDs. @return The map */
     212            /// Returns the map that stores all Identifiers with their IDs.
    187213            static inline const std::map<uint32_t, Identifier*>& getIDIdentifierMap() { return Identifier::getIDIdentifierMapIntern(); }
    188             /** @brief Returns a const_iterator to the beginning of the map that stores all Identifiers with their IDs. @return The const_iterator */
     214            /// Returns a const_iterator to the beginning of the map that stores all Identifiers with their IDs.
    189215            static inline std::map<uint32_t, Identifier*>::const_iterator getIDIdentifierMapBegin() { return Identifier::getIDIdentifierMap().begin(); }
    190             /** @brief Returns a const_iterator to the end of the map that stores all Identifiers with their IDs. @return The const_iterator */
     216            /// Returns a const_iterator to the end of the map that stores all Identifiers with their IDs.
    191217            static inline std::map<uint32_t, Identifier*>::const_iterator getIDIdentifierMapEnd() { return Identifier::getIDIdentifierMap().end(); }
    192218
    … …  
    197223            virtual void updateConfigValues(bool updateChildren = true) const = 0;
    198224
    199             /** @brief Returns true if this class has at least one config value. @return True if this class has at least one config value */
     225            /// Returns true if this class has at least one config value.
    200226            inline bool hasConfigValues() const { return this->bHasConfigValues_; }
    201227
    … …  
    207233            ///// XMLPort /////
    208234            ///////////////////
    209             /** @brief Returns the map that stores all XMLPort params. @return The const_iterator */
     235            /// Returns the map that stores all XMLPort params.
    210236            inline const std::map<std::string, XMLPortParamContainer*>& getXMLPortParamMap() const { return this->xmlportParamContainers_; }
    211             /** @brief Returns a const_iterator to the beginning of the map that stores all XMLPort params. @return The const_iterator */
     237            /// Returns a const_iterator to the beginning of the map that stores all XMLPort params.
    212238            inline std::map<std::string, XMLPortParamContainer*>::const_iterator getXMLPortParamMapBegin() const { return this->xmlportParamContainers_.begin(); }
    213             /** @brief Returns a const_iterator to the end of the map that stores all XMLPort params. @return The const_iterator */
     239            /// Returns a const_iterator to the end of the map that stores all XMLPort params.
    214240            inline std::map<std::string, XMLPortParamContainer*>::const_iterator getXMLPortParamMapEnd() const { return this->xmlportParamContainers_.end(); }
    215241
    216             /** @brief Returns the map that stores all XMLPort objects. @return The const_iterator */
     242            /// Returns the map that stores all XMLPort objects.
    217243            inline const std::map<std::string, XMLPortObjectContainer*>& getXMLPortObjectMap() const { return this->xmlportObjectContainers_; }
    218             /** @brief Returns a const_iterator to the beginning of the map that stores all XMLPort objects. @return The const_iterator */
     244            /// Returns a const_iterator to the beginning of the map that stores all XMLPort objects.
    219245            inline std::map<std::string, XMLPortObjectContainer*>::const_iterator getXMLPortObjectMapBegin() const { return this->xmlportObjectContainers_.begin(); }
    220             /** @brief Returns a const_iterator to the end of the map that stores all XMLPort objects. @return The const_iterator */
     246            /// Returns a const_iterator to the end of the map that stores all XMLPort objects.
    221247            inline std::map<std::string, XMLPortObjectContainer*>::const_iterator getXMLPortObjectMapEnd() const { return this->xmlportObjectContainers_.end(); }
    222248
    … …  
    238264            void initializeClassHierarchy(std::set<const Identifier*>* parents, bool bRootClass);
    239265
    240             /** @brief Returns the map that stores all Identifiers with their names. @return The map */
     266            /// Returns the map that stores all Identifiers with their names.
    241267            static std::map<std::string, Identifier*>& getStringIdentifierMapIntern();
    242             /** @brief Returns the map that stores all Identifiers with their names in lowercase. @return The map */
     268            /// Returns the map that stores all Identifiers with their names in lowercase.
    243269            static std::map<std::string, Identifier*>& getLowercaseStringIdentifierMapIntern();
    244             /** @brief Returns the map that stores all Identifiers with their network IDs. @return The map */
     270            /// Returns the map that stores all Identifiers with their network IDs.
    245271            static std::map<uint32_t, Identifier*>& getIDIdentifierMapIntern();
    246272
    247             /** @brief Returns the children of the class the Identifier belongs to. @return The list of all children */
     273            /// Returns the children of the class the Identifier belongs to.
    248274            inline std::set<const Identifier*>& getChildrenIntern() const { return this->children_; }
    249             /** @brief Returns the direct children of the class the Identifier belongs to. @return The list of all direct children */
     275            /// Returns the direct children of the class the Identifier belongs to.
    250276            inline std::set<const Identifier*>& getDirectChildrenIntern() const { return this->directChildren_; }
    251277
    … …  
    253279
    254280        private:
    255             /** @brief Increases the hierarchyCreatingCounter_s variable, causing all new objects to store their parents. */
     281            /// Increases the hierarchyCreatingCounter_s variable, causing all new objects to store their parents.
    256282            inline static void startCreatingHierarchy() { hierarchyCreatingCounter_s++; }
    257             /** @brief Decreases the hierarchyCreatingCounter_s variable, causing the objects to stop storing their parents. */
     283            /// Decreases the hierarchyCreatingCounter_s variable, causing the objects to stop storing their parents.
    258284            inline static void stopCreatingHierarchy()  { hierarchyCreatingCounter_s--; }
    259285
    … …  
    291317    // ###     ClassIdentifier     ###
    292318    // ###############################
    293     //! The ClassIdentifier is derived from Identifier and holds all class-specific functions and variables the Identifier cannot have.
    294     /**
    295         ClassIdentifier is a Singleton, which means that only one object of a given type T exists.
     319    /**
     320        @brief The ClassIdentifier is derived from Identifier and holds all class-specific functions and variables the Identifier cannot have.
     321
     322        ClassIdentifier is a Singleton, which means that only one ClassIdentifier for a given type T exists.
    296323        This makes it possible to store information about a class, sharing them with all
    297324        objects of that class without defining static variables in every class.
    298325
    299326        To be really sure that not more than exactly one object exists (even with libraries),
    300         ClassIdentifiers are stored in the Identifier Singleton.
     327        ClassIdentifiers are stored in a static map in Identifier.
    301328    */
    302329    template <class T>
    303330    class ClassIdentifier : public Identifier
    304331    {
    305         #define SUPER_INTRUSIVE_DECLARATION_INCLUDE
    306         #include "Super.h"
     332        #ifndef DOXYGEN_SHOULD_SKIP_THIS
     333          #define SUPER_INTRUSIVE_DECLARATION_INCLUDE
     334          #include "Super.h"
     335        #endif
    307336
    308337        public:
    … …  
    387416        @brief Adds an object of the given type to the ObjectList.
    388417        @param object The object to add
     418        @param className The name of the class T
     419        @param bRootClass True if this is a root class (i.e. it inherits directly from OrxonoxClass)
    389420    */
    390421    template <class T>

  • code/trunk/src/libraries/core/Iterator.h

    r7271 r7401  
    2929/**
    3030    @file
    31     @brief Definition and implementation of the Iterator class.
    32 
    33     The Iterator of a given class allows to iterate through an ObjectList. Objects in
    34     this list are cast to the template argument of the Iterator.
     31    @ingroup Object ObjectList
     32    @brief Definition of the Iterator class, used to iterate through object-lists.
     33
     34    @anchor IteratorExample
     35
     36    @ref orxonox::Iterator "Iterator" allows to iterate through an @ref orxonox::ObjectListBase
     37    "ObjectListBase". Objects in this list are cast to the template argument @a T of Iterator<T> using
     38    @c dynamic_cast. In contrast to @ref orxonox::ObjectListIterator "ObjectListIterator<T>",
     39    @ref orxonox::Iterator "Iterator<T>" can iterate through every object-list. In practice though it
     40    is limited to objects of type @a T and its subclasses. Because of the @c dynamic_cast, this iterator
     41    is much slower than ObjectListIterator.
    3542
    3643    Usage:
     44    @code
    3745    for (Iterator<myClass> it = anyidentifier->getObjects()->begin(); it != anyidentifier->getObjects()->end(); ++it)
    3846    {
    … …  
    4048        myClass* myObject = *it;
    4149    }
     50    @endcode
    4251*/
    4352
    … …  
    5261namespace orxonox
    5362{
    54     //! The Iterator allows to iterate through a given ObjectList
     63    /**
     64        @brief The Iterator allows to iterate through a given ObjectList.
     65
     66        Independent of the object-list's type, the objects in the list are always casted
     67        to @a T using @c dynamic_cast.
     68
     69        @see See @ref IteratorExample "Iterator.h" for more information an example.
     70    */
    5571    template <class T = OrxonoxClass>
    5672    class Iterator
    … …  
    200216                @return The Iterator itself
    201217            */
    202             inline Iterator<T> operator++(int i)
     218            inline Iterator<T> operator++(int)
    203219            {
    204220                Iterator<T> copy = *this;

  • code/trunk/src/libraries/core/Language.cc

    r7284 r7401  
    168168        @brief Returns the localisation of a given entry.
    169169        @param label The label of the entry
     170        @param bError If true, an error is printed if the label doesn't exist and the default localisation is returned. If false, no error is printed and an empty string is returned.
    170171        @return The localisation
    171172    */

  • code/trunk/src/libraries/core/Language.h

    r7284 r7401  
    2828
    2929/**
     30    @defgroup Language Language
     31    @ingroup Core
     32*/
     33
     34/**
    3035    @file
    31     @brief Definition of the Language and the LanguageEntry class.
     36    @ingroup Language
     37    @brief Declaration of the Language and the LanguageEntry class, as well as some helper functions.
     38
     39    @anchor LanguageExample
    3240
    3341    The Language class is used, to get a localisation of a string in the configured language.
    … …  
    3745    Usage:
    3846     - Set the entry with the default string:
     47       @code
    3948       Language::getInstance()->addEntry("label of the entry", "the string to translate");
     49       @endcode
    4050
    4151     - Get the localisation of the entry in the configured language:
     52       @code
    4253       std::cout << Language::getInstance()->getLocalisation("name of the entry") << std::endl;
     54       @endcode
     55
     56    Example:
     57    @code
     58    int age = 20;
     59    AddLanguageEntry("user_age", "Age");
     60    std::cout << GetLocalisation("user_age") << ": " << age << std::endl;
     61    @endcode
     62
     63    Resulting output:
     64    @code
     65    Age: 20
     66    @endcode
     67
     68    The language entry is now defined in @a translation_default.lang:
     69    @code
     70    user_age=Age
     71    @endcode
     72
     73    We can add a translation for another language, for example @a translation_german.lang:
     74    @code
     75    user_age=Alter
     76    @endcode
     77
     78    Now change the language in @a orxonox.ini to "german":
     79    @code
     80    language_ = "german"
     81    @endcode
     82
     83    Now you will see the translated language entry in the resulting output of the above code:
     84    @code
     85    Alter: 20
     86    @endcode
    4387*/
    4488
    … …  
    58102    // ###      LanguageEntry      ###
    59103    // ###############################
    60     //! The LanguageEntry class stores the default- and the translated string of a given entry in the language file.
     104    /**
     105        @brief The LanguageEntry class stores the default- and the translated string of a given entry in the language file.
     106
     107        This class belongs to the Language class.
     108    */
    61109    class _CoreExport LanguageEntry
    62110    {
    … …  
    105153    // ###         Language        ###
    106154    // ###############################
    107     //! The Language class manges the language files and entries and stores the LanguageEntry objects in a map.
     155    /**
     156        @brief The Language class manges the language files and entries and stores the LanguageEntry objects in a map.
     157
     158        @see See @ref LanguageExample "Language.h" for some examples.
     159    */
    108160    class _CoreExport Language : public Singleton<Language>
    109161    {
    … …  
    134186    };
    135187
    136     //! Shortcut function for Language::addEntry
     188    /// Shortcut function for Language::addEntry
    137189    inline void AddLanguageEntry(const LanguageEntryLabel& label, const std::string& fallbackString)
    138190    {
    … …  
    140192    }
    141193
    142     //! Shortcut function for Language::getLocalisation
     194    /// Shortcut function for Language::getLocalisation
    143195    inline const std::string& GetLocalisation(const LanguageEntryLabel& label)
    144196    {
    … …  
    146198    }
    147199
    148     //! Shortcut function for Language::getLocalisation without printing an error in case the label doesn't exist
     200    /// Shortcut function for Language::getLocalisation without printing an error in case the label doesn't exist
    149201    inline const std::string& GetLocalisation_noerror(const LanguageEntryLabel& label)
    150202    {

  • code/trunk/src/libraries/core/Loader.h

    r5781 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @defgroup Loader Loader
     31    @ingroup XML
     32*/
     33
     34/**
     35    @file
     36    @ingroup XML Loader
     37*/
    2838
    2939#ifndef _Loader_H__

  • code/trunk/src/libraries/core/LuaState.h

    r7284 r7401  
    2727 *
    2828 */
     29
     30/**
     31    @defgroup Lua Lua
     32    @ingroup Core
     33*/
     34
     35/**
     36    @file
     37    @ingroup Lua
     38*/
    2939
    3040#ifndef _LuaState_H__

  • code/trunk/src/libraries/core/MemoryArchive.cc

    r6417 r7401  
    5454    }
    5555
    56     DataStreamPtr MemoryArchive::open(const String& filename) const
     56    DataStreamPtr MemoryArchive::open(const Ogre::String& filename) const
    5757    {
    5858        const FileMap& files = archives_s[this->getName()];
    … …  
    6464    }
    6565
    66     void MemoryArchive::findFiles(const String& pattern, bool bRecursive,
    67         bool bDirs, StringVector* simpleList, FileInfoList* detailList)
     66    void MemoryArchive::findFiles(const Ogre::String& pattern, bool bRecursive,
     67        bool bDirs, Ogre::StringVector* simpleList, Ogre::FileInfoList* detailList)
    6868    {
    6969        const FileMap& files = archives_s[this->getName()];
    … …  
    110110    }
    111111
    112     StringVectorPtr MemoryArchive::find(const String& pattern,
     112    StringVectorPtr MemoryArchive::find(const Ogre::String& pattern,
    113113                                            bool recursive, bool dirs)
    114114    {
    … …  
    118118    }
    119119
    120     FileInfoListPtr MemoryArchive::findFileInfo(const String& pattern,
     120    FileInfoListPtr MemoryArchive::findFileInfo(const Ogre::String& pattern,
    121121        bool recursive, bool dirs)
    122122    {
    … …  
    126126    }
    127127
    128     bool MemoryArchive::exists(const String& filename)
     128    bool MemoryArchive::exists(const Ogre::String& filename)
    129129    {
    130130        const FileMap& files = archives_s[this->getName()];

  • code/trunk/src/libraries/core/MemoryArchive.h

    r6417 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup Management Resources
     32*/
    2833
    2934#ifndef _MemoryArchive_H__

  • code/trunk/src/libraries/core/MetaObjectList.h

    r5738 r7401  
    2929/**
    3030    @file
    31     @brief Definition of the MetaObjectList class.
     31    @ingroup Object ObjectList
     32    @brief Declaration of the MetaObjectList class.
    3233
    3334    The MetaObjectList is a single-linked list, containing all list-elements and their
    … …  
    4647    // ###  MetaObjectListElement  ###
    4748    // ###############################
    48     //! The list-element of the MetaObjectList
     49    /// The list-element of the MetaObjectList
    4950    class _CoreExport MetaObjectListElement
    5051    {
    … …  
    6566    // ###     MetaObjectList      ###
    6667    // ###############################
    67     //!  The MetaObjectList contains ObjectListBaseElements and their ObjectListBases.
    6868    /**
     69        @brief The MetaObjectList contains ObjectListBaseElements and their ObjectListBases.
     70
    6971        The MetaObjectList is a single-linked list, containing all list-elements and their
    7072        lists wherein the object that owns the MetaObjectList is registered.

  • code/trunk/src/libraries/core/Namespace.cc

    r6417 r7401  
    5555    }
    5656
    57     /**
    58         @brief XML loading and saving.
    59         @param xmlelement The XML-element
    60         @param loading Loading (true) or saving (false)
    61         @return The XML-element
    62     */
    6357    void Namespace::XMLPort(Element& xmlelement, XMLPort::Mode mode)
    6458    {

  • code/trunk/src/libraries/core/Namespace.h

    r5781 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup XML Loader
     32*/
    2833
    2934#ifndef _Namespace_H__

  • code/trunk/src/libraries/core/NamespaceNode.h

    r5781 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup XML Loader
     32*/
    2833
    2934#ifndef _NamespaceNode_H__

  • code/trunk/src/libraries/core/ObjectList.h

    r7278 r7401  
    2828
    2929/**
     30    @defgroup ObjectList Object-lists and iterators
     31    @ingroup Object
     32*/
     33
     34/**
    3035    @file
    31     @brief Definition and implementation of the ObjectList class.
     36    @ingroup Object ObjectList
     37    @brief Definition of the ObjectList class, a wrapper of ObjectListBase.
    3238
    33     The ObjectList is a wrapper of an ObjectListBase of a given class.
    34     Use Iterator<class> to iterate through all objects of the class.
     39    @ref orxonox::ObjectList "ObjectList<T>" is a wrapper of an @ref orxonox::ObjectListBase
     40    "ObjectListBase" of class @a T. Use @ref orxonox::ObjectListIterator "ObjectListIterator<T>"
     41    to iterate through the list.
    3542*/
    3643
    … …  
    4956    // ###       ObjectList        ###
    5057    // ###############################
    51     //! The ObjectList contains all objects of the given class.
    5258    /**
    53         Wraps the ObjectListBase of the corresponding Identifier.
    54         Use ObjectListIterator<class> to iterate through all objects in the list.
     59        @brief The ObjectList contains all objects of the given class.
     60
     61        Wraps the ObjectListBase which contains all objects of type @a T. Use @ref ObjectListIterator
     62        "ObjectListIterator<T>" or its typedef ObjectList<T>::iterator to iterate through all objects
     63        in the list.
    5564    */
    5665    template <class T>
    … …  
    6069            typedef ObjectListIterator<T> iterator;
    6170
    62             /** @brief Returns an Iterator to the first element in the list. @return The Iterator */
     71            /// Returns an Iterator to the first element in the list.
    6372            inline static ObjectListElement<T>* begin()
    6473            {
    … …  
    6776            }
    6877
    69             /** @brief Returns an Iterator to the element after the last element in the list. @return The Iterator */
     78            /// Returns an Iterator to the element after the last element in the list.
    7079            inline static ObjectListElement<T>* end()
    7180            {
    … …  
    7483            }
    7584
    76             /** @brief Returns an Iterator to the last element in the list. @return The Iterator */
     85            /// Returns an Iterator to the last element in the list.
    7786            inline static ObjectListElement<T>* rbegin()
    7887            {
    … …  
    8190            }
    8291
    83             /** @brief Returns an Iterator to the element before the first element in the list. @return The Iterator */
     92            /// Returns an Iterator to the element before the first element in the list.
    8493            inline static ObjectListElement<T>* rend()
    8594            {

  • code/trunk/src/libraries/core/ObjectListBase.cc

    r5738 r7401  
    3030    @file
    3131    @brief Implementation of the ObjectListBase class.
    32 
    33     The ObjectListBase is a double-linked list, used by Identifiers to store all objects of a given class.
    34     Newly created objects are added through the RegisterObject-macro in its constructor.
    3532*/
    3633
    … …  
    7067    /**
    7168        @brief Increases all Iterators that currently point on the given element (because it gets removed).
    72         @param element The element that gets removed
     69        @param object The object that gets removed
    7370    */
    7471    void ObjectListBase::notifyIterators(OrxonoxClass* object) const
    … …  
    8279    /**
    8380        @brief Adds a new object to the end of the list.
    84         @param object The object to add
     81        @param element The element to add
    8582        @return The pointer to the new ObjectListBaseElement, needed by the MetaObjectList of the added object
    8683    */

  • code/trunk/src/libraries/core/ObjectListBase.h

    r5738 r7401  
    2929/**
    3030    @file
    31     @brief Definition of the ObjectListBase class.
     31    @ingroup Object ObjectList
     32    @brief Declaration of the ObjectListBase class which stores all objects of each class.
    3233
    33     The ObjectListBase is a double-linked list, used by Identifiers to store all objects of a given class.
    34     Newly created objects are added through the RegisterObject-macro in its constructor.
     34    orxonox::ObjectListBase is a double-linked list, used by @ref orxonox::Identifier "Identifiers"
     35    to store all objects of a given class. Newly created objects are added to the list through the
     36    @c RegisterObject() macro in the constructor.
    3537*/
    3638
    … …  
    4850    // ###  ObjectListBaseElement  ###
    4951    // ###############################
    50     //! The list-element of the ObjectListBase
     52    /// The list-element of the ObjectListBase
    5153    class _CoreExport ObjectListBaseElement
    5254    {
    … …  
    5456            /**
    5557                @brief Constructor: Creates the list-element with an object.
    56                 @param object The object to store
     58                @param objectBase The object to store
    5759            */
    5860            ObjectListBaseElement(OrxonoxClass* objectBase) : next_(0), prev_(0), objectBase_(objectBase) {}
    … …  
    6769    // ###    ObjectListElement    ###
    6870    // ###############################
    69     //! The list-element that actually contains the object
     71    /// The list-element that actually contains the object
    7072    template <class T>
    7173    class ObjectListElement : public ObjectListBaseElement
    … …  
    8082    // ###     ObjectListBase      ###
    8183    // ###############################
    82     //! The ObjectListBase contains all objects of a given class.
    8384    /**
    84         The ObjectListBase is used by Identifiers to store all objects of their given class.
    85         Use ObjectList<T> to get the list of all T's and Iterator<T> to iterate through them.
     85        @brief The ObjectListBase contains all objects of a given class.
     86
     87        The ObjectListBase is used by Identifiers to store all objects of their class.
     88        You can use Identifier::getObjects() to get the object-list from an Identifier.
     89        Use @ref Iterator "Iterator<T>" to iterate through them.
     90
     91        Alternatively you can also use the static helper class @ref orxonox::ObjectList "ObjectList<T>"
     92        to get the list of all objects of type @a T. Use @ref ObjectListIterator "ObjectListIterator<T>"
     93        or @ref Iterator "Iterator<T>" to iterate through them.
    8694    */
    8795    class _CoreExport ObjectListBase
    … …  
    95103            ObjectListBaseElement* add(ObjectListBaseElement* element);
    96104
     105            /// Helper struct, used to export an element and the list to an instance of Iterator.
    97106            struct Export
    98107            {
    … …  
    102111            };
    103112
    104             /** @brief Returns a pointer to the first element in the list. @return The element */
     113            /// Returns a pointer to the first element in the list. Works only with Iterator.
    105114            inline Export begin() { return ObjectListBase::Export(this, this->first_); }
    106             /** @brief Returns a pointer to the element after the last element in the list. @return The element */
     115            /// Returns a pointer to the element after the last element in the list. Works only with Iterator.
    107116            inline Export end() { return ObjectListBase::Export(this, 0); }
    108             /** @brief Returns a pointer to the last element in the list. @return The element */
     117            /// Returns a pointer to the last element in the list. Works only with Iterator.
    109118            inline Export rbegin() { return ObjectListBase::Export(this, this->last_); }
    110             /** @brief Returns a pointer to the element in front of the first element in the list. @return The element */
     119            /// Returns a pointer to the element in front of the first element in the list. Works only with Iterator.
    111120            inline Export rend() { return ObjectListBase::Export(this, 0); }
    112121

  • code/trunk/src/libraries/core/ObjectListIterator.h

    r7268 r7401  
    2929/**
    3030    @file
    31     @brief Definition and implementation of the Iterator class.
    32 
    33     The ObjectListIterator of a given class allows to iterate through the
    34     ObjectList of this class, containing all objects of that type.
    35     This is the only way to access the objects stored in an ObjectList.
     31    @ingroup Object ObjectList
     32    @brief Definition of the ObjectListIterator class, used to iterate through object-lists.
     33
     34    @anchor ObjectListIteratorExample
     35
     36    @ref orxonox::ObjectListIterator "ObjectListIterator<T>" allows to iterate through
     37    @ref orxonox::ObjectList "ObjectList<T>", containing all objects of type @a T. In contrast to
     38    @ref orxonox::Iterator "Iterator<T>", this iterator is limited to the object-list of type @a T.
     39    It is, however, much faster as it doesn't need a @c dynamic_cast.
    3640
    3741    Usage:
     42    @code
    3843    for (ObjectListIterator<myClass> it = ObjectList<myClass>::begin(); it != ObjectList<myClass>::end(); ++it)
    3944    {
    … …  
    4146        myClass* myObject = *it;
    4247    }
     48    @endcode
     49
     50    @note @ref orxonox::ObjectList::iterator "ObjectList<T>::iterator" is identical to
     51          @ref orxonox::ObjectListIterator "ObjectListIterator<T>" (it's just a typedef).
    4352*/
    4453
    … …  
    5261namespace orxonox
    5362{
    54     //! The Iterator allows to iterate through the ObjectList of a given class.
     63    /**
     64        @brief ObjectListIterator<T> allows to iterate through the ObjectList of class @a T.
     65
     66        @see See @ref ObjectListIteratorExample "ObjectListIterator.h" for more information an example.
     67    */
    5568    template <class T>
    5669    class ObjectListIterator
    … …  
    109122            /**
    110123                @brief Assigns the element of another ObjectListIterator.
    111                 @param element The other ObjectListIterator
     124                @param other The other ObjectListIterator
    112125            */
    113126            inline ObjectListIterator<T>& operator=(const ObjectListIterator<T>& other)
    … …  
    131144                @return The ObjectListIterator itself
    132145            */
    133             inline ObjectListIterator<T> operator++(int i)
     146            inline ObjectListIterator<T> operator++(int)
    134147            {
    135148                ObjectListIterator<T> copy = *this;
    … …  
    217230
    218231        private:
    219             ObjectListElement<T>* element_;        //!< The element the Iterator points at
     232            ObjectListElement<T>* element_;        //!< The element the iterator points at
    220233    };
    221234}

  • code/trunk/src/libraries/core/OrxonoxClass.cc

    r6417 r7401  
    2929/**
    3030    @file
    31     @brief Implementation of the OrxonoxClass Class.
     31    @brief Implementation of OrxonoxClass.
    3232*/
    3333
    … …  
    4141namespace orxonox
    4242{
    43     /** @brief Constructor: Sets the default values. */
     43    /**
     44        @brief Constructor: Sets the default values.
     45    */
    4446    OrxonoxClass::OrxonoxClass()
    4547    {
    … …  
    5355    }
    5456
    55     /** @brief Destructor: Deletes, if existing, the list of the parents. */
     57    /**
     58        @brief Destructor: Removes the object from the object-lists, notifies all @ref WeakPtr "weak pointers" that this object is being deleted.
     59    */
    5660    OrxonoxClass::~OrxonoxClass()
    5761    {
    … …  
    7276    }
    7377
    74     /** @brief Deletes the object if no smart pointers point to this object. Otherwise schedules the object to be deleted as soon as possible. */
     78    /**
     79        @brief Deletes the object if no @ref orxonox::SmartPtr "smart pointers" point to this object. Otherwise schedules the object to be deleted as soon as possible.
     80    */
    7581    void OrxonoxClass::destroy()
    7682    {
    … …  
    8591    }
    8692
     93    /**
     94        @brief Removes this object from the object-lists.
     95    */
    8796    void OrxonoxClass::unregisterObject()
    8897    {
    … …  
    92101    }
    93102
    94     /** @brief Returns true if the objects class is of the given type or a derivative. */
     103    /// Returns true if the object's class is of the given type or a derivative.
    95104    bool OrxonoxClass::isA(const Identifier* identifier)
    96105        { return this->getIdentifier()->isA(identifier); }
    97     /** @brief Returns true if the objects class is exactly of the given type. */
     106    /// Returns true if the object's class is exactly of the given type.
    98107    bool OrxonoxClass::isExactlyA(const Identifier* identifier)
    99108        { return this->getIdentifier()->isExactlyA(identifier); }
    100     /** @brief Returns true if the objects class is a child of the given type. */
     109    /// Returns true if the object's class is a child of the given type.
    101110    bool OrxonoxClass::isChildOf(const Identifier* identifier)
    102111        { return this->getIdentifier()->isChildOf(identifier); }
    103     /** @brief Returns true if the objects class is a direct child of the given type. */
     112    /// Returns true if the object's class is a direct child of the given type.
    104113    bool OrxonoxClass::isDirectChildOf(const Identifier* identifier)
    105114        { return this->getIdentifier()->isDirectChildOf(identifier); }
    106     /** @brief Returns true if the objects class is a parent of the given type. */
     115    /// Returns true if the object's class is a parent of the given type.
    107116    bool OrxonoxClass::isParentOf(const Identifier* identifier)
    108117        { return this->getIdentifier()->isParentOf(identifier); }
    109     /** @brief Returns true if the objects class is a direct parent of the given type. */
     118    /// Returns true if the object's class is a direct parent of the given type.
    110119    bool OrxonoxClass::isDirectParentOf(const Identifier* identifier)
    111120        { return this->getIdentifier()->isDirectParentOf(identifier); }
    112121
    113122
    114     /** @brief Returns true if the objects class is of the given type or a derivative. */
     123    /// Returns true if the object's class is of the given type or a derivative.
    115124    bool OrxonoxClass::isA(const OrxonoxClass* object)
    116125        { return this->getIdentifier()->isA(object->getIdentifier()); }
    117     /** @brief Returns true if the objects class is exactly of the given type. */
     126    /// Returns true if the object's class is exactly of the given type.
    118127    bool OrxonoxClass::isExactlyA(const OrxonoxClass* object)
    119128        { return this->getIdentifier()->isExactlyA(object->getIdentifier()); }
    120     /** @brief Returns true if the objects class is a child of the given type. */
     129    /// Returns true if the object's class is a child of the given type.
    121130    bool OrxonoxClass::isChildOf(const OrxonoxClass* object)
    122131        { return this->getIdentifier()->isChildOf(object->getIdentifier()); }
    123     /** @brief Returns true if the objects class is a direct child of the given type. */
     132    /// Returns true if the object's class is a direct child of the given type.
    124133    bool OrxonoxClass::isDirectChildOf(const OrxonoxClass* object)
    125134        { return this->getIdentifier()->isDirectChildOf(object->getIdentifier()); }
    126     /** @brief Returns true if the objects class is a parent of the given type. */
     135    /// Returns true if the object's class is a parent of the given type.
    127136    bool OrxonoxClass::isParentOf(const OrxonoxClass* object)
    128137        { return this->getIdentifier()->isParentOf(object->getIdentifier()); }
    129     /** @brief Returns true if the objects class is a direct child of the given type. */
     138    /// Returns true if the object's class is a direct child of the given type.
    130139    bool OrxonoxClass::isDirectParentOf(const OrxonoxClass* object)
    131140        { return this->getIdentifier()->isDirectParentOf(object->getIdentifier()); }

  • code/trunk/src/libraries/core/OrxonoxClass.h

    r7163 r7401  
    2828
    2929/**
     30    @defgroup OrxonoxClass OrxonoxClass
     31    @ingroup Class
     32*/
     33
     34/**
    3035    @file
    31     @brief Declaration of the OrxonoxClass Class.
     36    @ingroup Class OrxonoxClass
     37    @brief Declaration of OrxonoxClass, the base class of all objects and interfaces in Orxonox.
    3238
    3339    All objects and interfaces of the game-logic (not the engine) are derived from OrxonoxClass.
    … …  
    5359namespace orxonox
    5460{
    55     //! The class all objects and interfaces of the game-logic (not the engine) are derived from.
    5661    /**
    57         The BaseObject and Interfaces are derived with 'virtual public OrxonoxClass' from OrxonoxClass.
    58         OrxonoxClass is needed to create the class-hierarchy at startup and to store the Identifier and the MetaObjectList.
     62        @brief The class all objects and interfaces of the game-logic (not the engine) are derived from.
     63
     64        The BaseObject and Interfaces are derived with @c virtual @c public @c OrxonoxClass from OrxonoxClass.
     65        OrxonoxClass is needed to create the class-hierarchy at startup and to store the Identifier and the
     66        MetaObjectList, as well as to provide an interface for SmartPtr and WeakPtr.
    5967    */
    6068    class _CoreExport OrxonoxClass
    … …  
    7684            void unregisterObject();
    7785
    78             /** @brief Function to collect the SetConfigValue-macro calls. */
     86            /// Function to collect the SetConfigValue-macro calls.
    7987            void setConfigValues() {};
    8088
    81             /** @brief Returns the Identifier of the object. @return The Identifier */
     89            /// Returns the Identifier of the object.
    8290            inline Identifier* getIdentifier() const { return this->identifier_; }
    8391
    … …  
    8997            bool isDirectParentOf(const Identifier* identifier);
    9098
     99            /// Returns true if the object's class is of the given type or a derivative.
    91100            template <class B> inline bool isA(const SubclassIdentifier<B>* identifier)
    92101                { return this->isA(*identifier); }
     102            /// Returns true if the object's class is exactly of the given type.
    93103            template <class B> inline bool isExactlyA(const SubclassIdentifier<B>* identifier)
    94104                { return this->isExactlyA(*identifier); }
     105            /// Returns true if the object's class is a child of the given type.
    95106            template <class B> inline bool isChildOf(const SubclassIdentifier<B>* identifier)
    96107                { return this->isChildOf(*identifier); }
     108            /// Returns true if the object's class is a direct child of the given type.
    97109            template <class B> inline bool isDirectChildOf(const SubclassIdentifier<B>* identifier)
    98110                { return this->isDirectChildOf(*identifier); }
     111            /// Returns true if the object's class is a parent of the given type.
    99112            template <class B> inline bool isParentOf(const SubclassIdentifier<B>* identifier)
    100113                { return this->isParentOf(*identifier); }
     114            /// Returns true if the object's class is a direct parent of the given type.
    101115            template <class B> inline bool isDirectParentOf(const SubclassIdentifier<B>* identifier)
    102116                { return this->isDirectParentOf(*identifier); }
    … …  
    111125            virtual void clone(OrxonoxClass*& item) {}
    112126
     127            /// Returns the number of @ref orxonox::SmartPtr "smart pointers" that point to this object.
    113128            inline unsigned int getReferenceCount() const
    114129                { return this->referenceCount_; }
    … …  
    131146            }
    132147
    133             //! Version of getDerivedPointer with template
     148            /// Version of getDerivedPointer with template
    134149            template <class T> FORCEINLINE T* getDerivedPointer(unsigned int classID)
    135150            {   return static_cast<T*>(this->getDerivedPointer(classID));   }
    136             //! Const version of getDerivedPointer with template
     151            /// Const version of getDerivedPointer with template
    137152            template <class T> FORCEINLINE const T* getDerivedPointer(unsigned int classID) const
    138153            {   return const_cast<OrxonoxClass*>(this)->getDerivedPointer<T>(classID);   }
    139154
    140155        protected:
     156            /// This virtual function is called if destroy() is called and no SmartPtr points to this object. Used in some cases to create a new SmartPtr to prevent destruction.
    141157            virtual void preDestroy() {}
    142158
    143159        private:
    144             /** @brief Increments the reference counter (for smart pointers). */
     160            /// Increments the reference counter (for smart pointers).
    145161            inline void incrementReferenceCount()
    146162                { ++this->referenceCount_; }
    147             /** @brief Decrements the reference counter (for smart pointers). */
     163            /// Decrements the reference counter (for smart pointers).
    148164            inline void decrementReferenceCount()
    149165            {
    … …  
    153169            }
    154170
    155             /** @brief Register a weak pointer which points to this object. */
     171            /// Register a weak pointer which points to this object.
    156172            template <class T>
    157173            inline void registerWeakPtr(WeakPtr<T>* pointer)
    158174                { this->weakPointers_.insert(reinterpret_cast<WeakPtr<OrxonoxClass>*>(pointer)); }
    159             /** @brief Unegister a weak pointer which pointed to this object before. */
     175            /// Unegister a weak pointer which pointed to this object before.
    160176            template <class T>
    161177            inline void unregisterWeakPtr(WeakPtr<T>* pointer)
    162178                { this->weakPointers_.erase(reinterpret_cast<WeakPtr<OrxonoxClass>*>(pointer)); }
    163179
    164             Identifier* identifier_;                   //!< The Identifier of the object
    165             std::set<const Identifier*>* parents_;     //!< List of all parents of the object
    166             MetaObjectList* metaList_;                 //!< MetaObjectList, containing all ObjectLists and ObjectListElements the object is registered in
    167             int referenceCount_;                       //!< Counts the references from smart pointers to this object
    168             bool requestedDestruction_;                //!< Becomes true after someone called delete on this object
    169             std::set<WeakPtr<OrxonoxClass>*> weakPointers_; //!< All weak pointers which point to this object (and like to get notified if it dies)
     180            Identifier* identifier_;                            //!< The Identifier of the object
     181            std::set<const Identifier*>* parents_;              //!< List of all parents of the object
     182            MetaObjectList* metaList_;                          //!< MetaObjectList, containing all ObjectLists and ObjectListElements the object is registered in
     183            int referenceCount_;                                //!< Counts the references from smart pointers to this object
     184            bool requestedDestruction_;                         //!< Becomes true after someone called delete on this object
     185            std::set<WeakPtr<OrxonoxClass>*> weakPointers_;     //!< All weak pointers which point to this object (and like to get notified if it dies)
    170186
    171             //! 'Fast map' that holds this-pointers of all derived types
     187            /// 'Fast map' that holds this-pointers of all derived types
    172188            std::vector<std::pair<unsigned int, void*> > objectPointers_;
    173189    };

  • code/trunk/src/libraries/core/PathConfig.h

    r6417 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup Management Resources
     32*/
    2833
    2934#ifndef _PathConfig_H__

  • code/trunk/src/libraries/core/Resource.h

    r6746 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @defgroup Resources Resources
     31    @ingroup Management
     32*/
     33
     34/**
     35    @file
     36    @ingroup Management Resources
     37*/
    2838
    2939#ifndef _Core_Resource_H__
    … …  
    105115        /**
    106116            Find out if the named file exists.
    107         @param filename
     117        @param name
    108118            Fully qualified name of the file to test for
    109119        */
    … …  
    112122        /**
    113123            Get struct with information about path and size.
    114         @param filename
     124        @param name
    115125            Fully qualified name of the file to test for
    116126        */

  • code/trunk/src/libraries/core/SmartPtr.h

    r7268 r7401  
    2929// Inspired by boost::intrusive_ptr by Peter Dimov
    3030
     31/**
     32    @defgroup SmartPtr SmartPtr<T> and WeakPtr<T>
     33    @ingroup Object
     34*/
     35
     36/**
     37    @file
     38    @ingroup Object SmartPtr
     39    @brief Definition of SmartPtr<T>, wraps a pointer to an object and keeps it alive.
     40
     41    @anchor SmartPtrExample
     42
     43    orxonox::SmartPtr is an implementation of a smart pointer - it wraps a pointer to an
     44    object  and keeps this object alive until no SmartPtr points to this object anymore.
     45    In contrast to orxonox::SharedPtr, SmartPtr works only with classes that are derived
     46    from orxonox::OrxonoxClass, because it's an intrusive implementation, meaning the
     47    reference counter is stored in the object itself.
     48
     49    It's possible to use normal pointers and smart pointers to an object simultaneously.
     50    You don't have to use SmartPtr all the time, you can create a SmartPtr for an object
     51    at any time and also convert it back to a normal pointer if you like. This is possible
     52    because the reference counter is stored in the object itself and not in SmartPtr (in
     53    contrast to SharedPtr).
     54
     55    @b Important: If you want to delete an object, you must not use @c delete @c object but
     56    rather @c object->destroy(). This function will check if there are smart pointers
     57    pointing to the object. If yes, the object will be kept alive until all smart pointes
     58    are destroyed. If no, the object is deleted instantly.
     59
     60    If all smart pointers that point to an object are destroyed, but you never called
     61    @c object->destroy() before, the object will not be deleted! All a SmartPtr will do
     62    is to really just keep an object alive, but it will not delete it automatically
     63    unless you tried to destroy it before.
     64
     65    Example:
     66    @code
     67    class MyClass                                           // class declaration
     68    {
     69        public:
     70            void setObject(OtherClass* object)              // passes a normal pointer which will be stored in a SmartPtr
     71                { this->object_ = object; }
     72
     73            OtherClass* getObject() const                   // converts the SmartPtr to a normal pointer and returns it
     74                { return this->object_; }
     75
     76        private:
     77            SmartPtr<OtherClass> object_;                   // a pointer to an instance of OtherClass is stored in a SmartPtr
     78    };
     79    @endcode
     80    In this example we assume that OtherClass is a child of OrxonoxClass. We don't care
     81    about the inheritance of MyClass though.
     82
     83    Now we create an instance of MyClass and assign a pointer to an instance of OtherClass:
     84    @code
     85    MyClass* myclass = new MyClass();                       // create an instance of MyClass
     86    OtherClass* object = new OtherClass();                  // create an instance of OtherClass
     87    myclass->setObject(object);                             // the object is now stored in a SmartPtr inside myclass
     88
     89    object->destroy();                                      // we try to destroy object, but there's still a SmartPtr pointing at it.
     90
     91    # object still exists at this point (because a SmartPtr points at it)
     92
     93    delete myclass;                                         // now we delete myclass, which also destroys the SmartPtr
     94
     95    # object doesn't exist anymore (because the SmartPtr is now destroyed)
     96    @endcode
     97
     98    Now we look at the same example, but we first delete myclass, then destroy object:
     99    @code
     100    MyClass* myclass = new MyClass();                       // create an instance of MyClass
     101    OtherClass* object = new OtherClass();                  // create an instance of OtherClass
     102    myclass->setObject(object);                             // the object is now stored in a SmartPtr inside myclass
     103
     104    delete myclass;                                         // we delete myclass, which also destroys the SmartPtr
     105
     106    # object still exists at this point (because destroy() was not called yet)
     107
     108    object->destroy();                                      // now we try to destroy object, which works instantly
     109
     110    # object doesn't exist anymore (because we just destroyed it)
     111    @endcode
     112
     113    Note that in any case @c object->destroy() has to be called to delete the object.
     114    However if a SmartPtr points at it, the destruction is delayed until all SmartPtr
     115    are destroyed.
     116*/
     117
    31118#ifndef _SmartPtr_H__
    32119#define _SmartPtr_H__
    … …  
    42129namespace orxonox
    43130{
     131    /**
     132        @brief A smart pointer which wraps a pointer to an object and keeps this object alive as long as the smart pointer exists.
     133
     134        @see See @ref SmartPtrExample "this description" for more information and an example.
     135    */
    44136    template <class T>
    45137    class SmartPtr
    46138    {
    47139        public:
     140            /// Constructor: Initializes the smart pointer with a null pointer.
    48141            inline SmartPtr() : pointer_(0), base_(0)
    49142            {
    50143            }
    51144
     145            /// Constructor: Used to explicitly initialize the smart pointer with a null pointer
    52146            inline SmartPtr(int) : pointer_(0), base_(0)
    53147            {
    54148            }
    55149
     150            /// Constructor: Initializes the smart pointer with a pointer to an object. @param pointer The pointer @param bAddRef If true, the reference counter is increased. Don't set this to false unless you know exactly what you're doing! (for example to avoid circular references if the @c this pointer of the possessing object is stored)
    56151            inline SmartPtr(T* pointer, bool bAddRef = true) : pointer_(pointer), base_(pointer)
    57152            {
    … …  
    60155            }
    61156
     157            /// Copy-constructor
    62158            inline SmartPtr(const SmartPtr& other) : pointer_(other.pointer_), base_(other.base_)
    63159            {
    … …  
    66162            }
    67163
     164            /// Copy-constructor for smart pointers to objects of another class.
    68165            template <class O>
    69166            inline SmartPtr(const SmartPtr<O>& other) : pointer_(other.get()), base_(other.base_)
    … …  
    73170            }
    74171
     172            /// Constructor: Initializes the smart pointer with the pointer that is stored in a WeakPtr.
    75173            template <class O>
    76174            inline SmartPtr(const WeakPtr<O>& other) : pointer_(other.get()), base_(other.getBase())
    … …  
    80178            }
    81179
     180            /// Destructor: Decrements the reference counter.
    82181            inline ~SmartPtr()
    83182            {
    … …  
    86185            }
    87186
     187            /// Used to assign a null pointer.
    88188            inline SmartPtr& operator=(int)
    89189            {
    … …  
    92192            }
    93193
     194            /// Assigns a new pointer.
    94195            inline SmartPtr& operator=(T* pointer)
    95196            {
    … …  
    98199            }
    99200
     201            /// Assigns the wrapped pointer of another SmartPtr.
    100202            inline SmartPtr& operator=(const SmartPtr& other)
    101203            {
    … …  
    104206            }
    105207
     208            /// Assigns the wrapped pointer of a SmartPtr of another class
    106209            template <class O>
    107210            inline SmartPtr& operator=(const SmartPtr<O>& other)
    … …  
    111214            }
    112215
     216            /// Assigns the wrapped pointer of a WeakPtr.
    113217            template <class O>
    114218            inline SmartPtr& operator=(const WeakPtr<O>& other)
    … …  
    118222            }
    119223
     224            /// Returns the wrapped pointer as @c T*
    120225            inline T* get() const
    121226            {
    … …  
    123228            }
    124229
     230            /// Returns the wrapped pointer as @c OrxonoxClass*
    125231            inline OrxonoxClass* getBase() const
    126232            {
    … …  
    128234            }
    129235
     236            /// Implicitly converts the SmartPtr to a pointer of type @c T*
    130237            inline operator T*() const
    131238            {
    … …  
    133240            }
    134241
     242            /// Overloaded operator, returns a pointer to the stored object.
    135243            inline T* operator->() const
    136244            {
    … …  
    139247            }
    140248
     249            /// Overloaded operator, returns a reference to the stored object.
    141250            inline T& operator*() const
    142251            {
    … …  
    145254            }
    146255
     256            /// Returns true if the wrapped pointer is NULL.
    147257            inline bool operator!() const
    148258            {
    … …  
    150260            }
    151261
     262            /// Swaps the contents of two smart pointers.
    152263            inline void swap(SmartPtr& other)
    153264            {
    … …  
    164275            }
    165276
     277            /// Resets the smart pointer (equivalent to assigning a NULL pointer).
    166278            inline void reset()
    167279            {
    … …  
    170282
    171283        private:
    172             T* pointer_;
    173             OrxonoxClass* base_;
     284            T* pointer_;            ///< The wrapped pointer to an object of type @a T
     285            OrxonoxClass* base_;    ///< The wrapped pointer, casted up to OrxonoxClass (this is needed because with just a T* pointer, SmartPtr couln't be used with forward declarations)
    174286    };
    175287
     288    /// Swaps the contents of two smart pointers.
    176289    template <class T>
    177290    void swap(SmartPtr<T>& a, SmartPtr<T>& b)
    … …  
    180293    }
    181294
     295    /// Uses a static_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new SmartPtr<T>.
    182296    template <class T, class U>
    183297    SmartPtr<T> static_pointer_cast(const SmartPtr<U>& p)
    … …  
    186300    }
    187301
     302    /// Uses a const_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new SmartPtr<T>.
    188303    template <class T, class U>
    189304    SmartPtr<T> const_pointer_cast(const SmartPtr<U>& p)
    … …  
    192307    }
    193308
     309    /// Uses a dynamic_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new SmartPtr<T>.
    194310    template <class T, class U>
    195311    SmartPtr<T> dynamic_pointer_cast(const SmartPtr<U>& p)

  • code/trunk/src/libraries/core/SubclassIdentifier.h

    r7268 r7401  
    2929/**
    3030    @file
     31    @ingroup Class Identifier
    3132    @brief Definition of SubclassIdentifier.
     33
     34    @anchor SubclassIdentifierExample
    3235
    3336    SubclassIdentifier is a separated class, acting like an Identifier, but has a given class.
    3437    You can only assign Identifiers of exactly the given class or of a derivative to a SubclassIdentifier.
     38
     39    Example:
     40
     41    You can assign an Identifier either through the constructor or by using the assignment @c operator=:
     42    @code
     43    SubclassIdentifier<BaseClass> identifier = Class(SubClass);
     44    @endcode
     45
     46    The @c operator-> is overloaded an returns the assigned Identifier. That way you can just call
     47    functions of the assigned Identifier by using @c ->function():
     48    @code
     49    SubclassIdentifier<BaseClass> identifier = Class(SubClass);
     50    identifier->getName();      // returns "SubClass"
     51    @endcode
     52
     53    There are two possibilities to create an object out of a SubclassIdentifier: Either you just use
     54    the @c fabricate() function of the assigned Identifier through the overloaded @c operator->, which
     55    returns a @c BaseObject* pointer, or you use the function of SubclassIdentifier, this time by using
     56    @c operator., which returns a @c BaseClass* pointer (@a BaseClass is the baseclass specified by the
     57    template argument):
     58    @code
     59    identifier->fabricate();    // calls Identifier::fabricate(), creates a SubClass, returns a BaseObject* pointer
     60
     61    identifier.fabricate();     // calls SubclassIdentifier::fabricate(), creates a SubClass, returns a BaseClass* pointer
     62    @endcode
    3563*/
    3664
    … …  
    4977    // ###   SubclassIdentifier    ###
    5078    // ###############################
    51     //! The SubclassIdentifier acts almost like an Identifier, but has some prerequisites.
    5279    /**
     80        @brief The SubclassIdentifier acts almost like an Identifier, but has some prerequisites.
     81
    5382        You can only assign an Identifier that belongs to a class T (or derived) to a SubclassIdentifier<T>.
    54         If you assign something else, the program aborts.
    55         Because we know the minimum type, a dynamic_cast is done, which makes it easier to create a new object.
     83        If you assign something else, the program prints an error.
     84
     85        Because we know the base-type, a @c dynamic_cast is done, which makes it easier to create a new object.
     86
     87        @see See @ref SubclassIdentifierExample "SubclassIdentifier.h" for some examples.
    5688    */
    5789    template <class T>
    … …  
    5991    {
    6092        public:
    61             /**
    62                 @brief Constructor: Automaticaly assigns the Identifier of the given class.
    63             */
     93            /// Constructor: Automaticaly assigns the Identifier of the given class.
    6494            SubclassIdentifier()
    6595            {
    … …  
    6797            }
    6898
    69             /**
    70                 @brief Constructor: Assigns the given Identifier.
    71                 @param identifier The Identifier
    72             */
     99            /// Constructor: Assigns the given Identifier.
    73100            SubclassIdentifier(Identifier* identifier)
    74101            {
    … …  
    76103            }
    77104
    78             /**
    79                 @brief Copyconstructor: Assigns the identifier of the other SubclassIdentifier.
    80                 @param identifier The other SublcassIdentifier
    81             */
     105            /// Copyconstructor: Assigns the identifier of another SubclassIdentifier.
    82106            template <class O>
    83107            SubclassIdentifier(const SubclassIdentifier<O>& identifier)
    … …  
    113137            }
    114138
    115             /**
    116                 @brief Overloading of the = operator: assigns the identifier of the other SubclassIdentifier.
    117                 @param identifier The other SublcassIdentifier
    118             */
     139            /// Overloading of the = operator: assigns the identifier of another SubclassIdentifier.
    119140            template <class O>
    120141            SubclassIdentifier<T>& operator=(const SubclassIdentifier<O>& identifier)
    … …  
    123144            }
    124145
    125             /**
    126                 @brief Overloading of the * operator: returns the assigned identifier.
    127             */
     146            /// Overloading of the * operator: returns the assigned identifier.
    128147            inline Identifier* operator*() const
    129148            {
    … …  
    131150            }
    132151
    133             /**
    134                 @brief Overloading of the -> operator: returns the assigned identifier.
    135             */
     152            /// Overloading of the -> operator: returns the assigned identifier.
    136153            inline Identifier* operator->() const
    137154            {
    … …  
    139156            }
    140157
    141             /**
    142                 @brief Returns the assigned identifier. This allows you to assign a SubclassIdentifier to a normal Identifier*.
    143             */
     158            /// Returns the assigned identifier. This allows you to assign a SubclassIdentifier to a normal Identifier*.
    144159            inline operator Identifier*() const
    145160            {
    … …  
    147162            }
    148163
    149             /**
    150                 @brief Creates a new object of the type of the assigned Identifier and dynamic_casts it to the minimal type given by T.
    151                 @return The new object
    152             */
     164            /// Creates a new object of the type of the assigned Identifier and dynamic_casts it to the minimal type given by T.
    153165            T* fabricate(BaseObject* creator) const
    154166            {
    … …  
    181193            }
    182194
    183             /** @brief Returns the assigned identifier. @return The identifier */
     195            /// Returns the assigned identifier.
    184196            inline Identifier* getIdentifier() const
    185197                { return this->identifier_; }

  • code/trunk/src/libraries/core/Super.h

    r7163 r7401  
    2828
    2929/**
     30    @defgroup Super Super
     31    @ingroup Class
     32*/
     33
     34/**
    3035    @file
    31     @brief Definition of all super-function related macros.
    32 
    33     This file defines all macros needed to add a new "super-function".
    34     If you add a super-function, you can call SUPER(myclass, functionname) inside your
    35     code and the function of the parentclass gets called. This is comparable with
    36     super.functionname() in Java or other languages.
    37 
    38     This works only with virtual functions that return nothing (void) and belong to
    39     classes that have an Identifier. Arguments however are supported.
    40 
    41     To add a new super-function, you have process 4 steps:
    42 
    43     1) Add a new SUPER macro
    44        This allows you to call the super-function in your code.
    45        Location: This file (Super.h), marked with --> HERE <-- comments (1/3)
    46 
    47     2) Call the SUPER_FUNCTION_GLOBAL_DECLARATION_PART1/2 macros.
    48        This defines some global classes and templates, needed to create and call the super-functions.
    49        Location: This file (Super.h), marked with --> HERE <-- comments (2/3)
    50 
    51     3) Call the SUPER_INTRUSIVE_DECLARATION macro.
    52        This will be included into the declaration of ClassIdentifier<T>.
    53        Location: This file (Super.h), marked with --> HERE <-- comments (3/3)
    54 
    55     4) Call the SUPER_FUNCTION macro.
     36    @ingroup Class Super
     37    @brief Definition of all super-function related macros, used to call functions of the base class.
     38
     39    This file defines all macros needed to add a new "super-function". If you add
     40    a super-function, you can call <tt>SUPER(myclass, functionname, arguments)</tt>
     41    inside your code and the function of the parent-class gets called. This is comparable
     42    to <tt>super.functionname(arguments)</tt> in Java or other languages.
     43
     44    This works only with virtual functions that return nothing (@c void) and belong to
     45    classes that have an @ref orxonox::Identifier "Identifier". Arguments however are
     46    supported, there's no limitation for their number and type, except that the type has
     47    to be known in Super.h.
     48
     49    To add a new super-function, you have to process 4 steps:
     50
     51    -# Add a new @c SUPER macro <br />
     52       This allows you to call the super-function in your code. <br />
     53       Location: This file (Super.h), marked with "--> HERE <--" comments (1/3)
     54    -# Call the @c SUPER_FUNCTION_GLOBAL_DECLARATION_PART1/2 macros. <br />
     55       This defines some global classes and templates, needed to create and call the super-functions. <br />
     56       Location: This file (Super.h), marked with "--> HERE <--" comments (2/3)
     57    -# Call the @c SUPER_INTRUSIVE_DECLARATION macro. <br />
     58       This will be included into the declaration of @c ClassIdentifier<T>. <br />
     59       Location: This file (Super.h), marked with "--> HERE <--" comments (3/3)
     60    -# Call the @c SUPER_FUNCTION macro. <br />
    5661       This defines a partially specialized template that will decide if a class is "super" to another class.
    57        If the check returns true, a SuperFunctionCaller gets created, which will be used by the SUPER macro.
     62       If the check returns true, a @c SuperFunctionCaller gets created, which will be used by the @c SUPER macro.
    5863       You have to add this into the header-file of the baseclass of the super-function (the class that first
    5964       implements the function), below the class declaration. You can't call it directly in this file, because
    60        otherwise you had to include the headerfile right here, which would cause some ugly backdependencies,
    61        include loops and slower compilation.
    62        Dont forget to include Super.h in the header-file.
     65       otherwise you had to include the headerfile right here, which would cause some ugly back-dependencies,
     66       include loops and slower compilation. <br />
     67       Dont forget to include Super.h in the header-file. <br />
    6368       Location: The header-file of the baseclass (Baseclass.h), below the class declaration
    6469*/
    … …  
    205210    */
    206211
    207     // SUPER-macro: Calls Parent::functionname() where Parent is the direct parent of classname
     212    /// SUPER-macro: Calls Parent::functionname(...) where Parent is the direct parent of @a classname
    208213    #ifdef ORXONOX_COMPILER_MSVC
    209214        #define SUPER(classname, functionname, ...) \

  • code/trunk/src/libraries/core/Template.h

    r7163 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @defgroup Template Template
     31    @ingroup XML
     32*/
     33
     34/**
     35    @file
     36    @ingroup XML Template
     37*/
    2838
    2939#ifndef _Template_H__

  • code/trunk/src/libraries/core/Thread.h

    r7284 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup ThreadPool
     32*/
    2833
    2934#ifndef _Thread_H__

  • code/trunk/src/libraries/core/ThreadPool.h

    r7284 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @defgroup ThreadPool Thread pool
     31    @ingroup Core
     32*/
     33
     34/**
     35    @file
     36    @ingroup ThreadPool
     37*/
    2838
    2939#ifndef _ThreadPool_H__

  • code/trunk/src/libraries/core/ToluaInterface.h

    r5738 r7401  
    2929/**
    3030@file
     31@ingroup Lua
     32@brief
    3133    This is required because tolua would parse this macro in LuaState.h and fail
    3234*/

  • code/trunk/src/libraries/core/WeakPtr.h

    r7284 r7401  
    2929// Inspired by boost::intrusive_ptr by Peter Dimov
    3030
     31/**
     32    @file
     33    @ingroup Object SmartPtr
     34    @brief Definition of WeakPtr<T>, wraps a pointer to an object.
     35
     36    @anchor WeakPtrExample
     37
     38    A WeakPtr wraps a pointer to an object. If the object gets deleted, the WeakPtr becomes
     39    NULL. This can be used to store pointers to objects without knowing when they will be
     40    destroyed.
     41
     42    WeakPtr works only with objects that are derived from orxonox::OrxonoxClass, because
     43    WeakPtr is intrusive and registers itself in the stored object, to get a notification if
     44    the object is being deleted.
     45
     46    Example:
     47    @code
     48    MyClass* object = new MyClass();                    // create an instance of MyClass
     49
     50    WeakPtr<MyClass> pointer = object;                  // create a WeakPtr and assign the object
     51
     52    if (pointer)                                        // checks if pointer is not NULL (which is true)
     53        pointer->someFunction();                        // calls MyClass::someFunction()
     54
     55    object->destroy();                                  // calls destroy() which deletes the object
     56
     57    if (pointer)                                        // checks if pointer is not NULL (which is now false)
     58        pointer->someFunction();                        // this will not be executed
     59    @endcode
     60    In this example we assumed that MyClass is derived of OrxonoxClass (otherwise it couldn't
     61    be used with a WeakPtr).
     62
     63    A callback can be registerd with the WeakPtr that will be called if the object gets deleted.
     64    @code
     65    void myCallback()                                   // definition of the callback function
     66    {
     67        COUT(0) << "Object destroyed" << std::endl;
     68    }
     69
     70    MyClass* object = new MyClass();                    // create an instance of MyClass
     71
     72    WeakPtr<MyClass> pointer = object;                  // create a WeakPtr and assign the object
     73
     74    pointer.setCallback(createFunctor(&myCallback));    // defines a callback
     75
     76    object->destroy();                                  // calls destroy() which deletes the object. prints "Object destroyed" to the console
     77    @endcode
     78*/
     79
    3180#ifndef _WeakPtr_H__
    3281#define _WeakPtr_H__
    … …  
    4190namespace orxonox
    4291{
     92    /**
     93        @brief WeakPtr wraps a pointer to an object, which becomes NULL if the object is deleted.
     94
     95        @see See @ref WeakPtrExample "this description" for more information and an example.
     96    */
    4397    template <class T>
    4498    class WeakPtr
    … …  
    47101
    48102        public:
     103            /// Constructor: Initializes the weak pointer with a null pointer.
    49104            inline WeakPtr() : pointer_(0), base_(0), callback_(0)
    50105            {
    51106            }
    52107
     108            /// Constructor: Used to explicitly initialize the weak pointer with a null pointer
    53109            inline WeakPtr(int) : pointer_(0), base_(0), callback_(0)
    54110            {
    55111            }
    56112
     113            /// Constructor: Initializes the weak pointer with a pointer to an object.
    57114            inline WeakPtr(T* pointer) : pointer_(pointer), base_(pointer), callback_(0)
    58115            {
    … …  
    61118            }
    62119
     120            /// Copy-constructor
    63121            inline WeakPtr(const WeakPtr& other) : pointer_(other.pointer_), base_(other.base_), callback_(0)
    64122            {
    … …  
    67125            }
    68126
     127            /// Copy-constructor for weak pointers to objects of another class.
    69128            template <class O>
    70129            inline WeakPtr(const WeakPtr<O>& other) : pointer_(other.get()), base_(other.base_), callback_(0)
    … …  
    74133            }
    75134
     135            /// Destructor
    76136            inline ~WeakPtr()
    77137            {
    … …  
    81141            }
    82142
     143            /// Used to assign a null pointer.
    83144            inline WeakPtr& operator=(int)
    84145            {
    … …  
    87148            }
    88149
     150            /// Assigns a new pointer.
    89151            inline WeakPtr& operator=(T* pointer)
    90152            {
    … …  
    93155            }
    94156
     157            /// Assigns the wrapped pointer of another WeakPtr.
    95158            inline WeakPtr& operator=(const WeakPtr& other)
    96159            {
    … …  
    99162            }
    100163
     164            /// Assigns the wrapped pointer of a WeakPtr of another class
    101165            template <class O>
    102166            inline WeakPtr& operator=(const WeakPtr<O>& other)
    … …  
    106170            }
    107171
     172            /// Returns the wrapped pointer as @c T*
    108173            inline T* get() const
    109174            {
    … …  
    111176            }
    112177
     178            /// Returns the wrapped pointer as @c OrxonoxClass*
    113179            inline OrxonoxClass* getBase() const
    114180            {
    … …  
    116182            }
    117183
     184            /// Implicitly converts the WeakPtr to a pointer of type @c T*
    118185            inline operator T*() const
    119186            {
    … …  
    121188            }
    122189
     190            /// Overloaded operator, returns a pointer to the stored object.
    123191            inline T* operator->() const
    124192            {
    … …  
    127195            }
    128196
     197            /// Overloaded operator, returns a reference to the stored object.
    129198            inline T& operator*() const
    130199            {
    … …  
    133202            }
    134203
     204            /// Returns true if the wrapped pointer is NULL.
    135205            inline bool operator!() const
    136206            {
    … …  
    138208            }
    139209
     210            /// Swaps the contents of two weak pointers.
    140211            inline void swap(WeakPtr& other)
    141212            {
    … …  
    162233            }
    163234
     235            /// Resets the weak pointer (equivalent to assigning a NULL pointer).
    164236            inline void reset()
    165237            {
    … …  
    167239            }
    168240
     241            /// Registers a callback that will be executed if the stored object is destroyed.
    169242            inline void setCallback(const FunctorPtr& callback)
    170243            {
    … …  
    172245            }
    173246
     247            /// Returns the registered callback.
    174248            inline const FunctorPtr& getCallback() const
    175249            {
    … …  
    178252
    179253        private:
     254            /// Will be called by OrxonoxClass::~OrxonoxClass() if the stored object is deleted. Resets the wrapped pointer and executes the callback.
    180255            inline void objectDeleted()
    181256            {
    … …  
    186261            }
    187262
    188             T* pointer_;
    189             OrxonoxClass* base_;
    190             FunctorPtr callback_;
     263            T* pointer_;            ///< The wrapped pointer to an object of type @a T
     264            OrxonoxClass* base_;    ///< The wrapped pointer, casted up to OrxonoxClass (this is needed because with just a T* pointer, WeakPtr couln't be used with forward declarations)
     265            FunctorPtr callback_;   ///< This callback will be executed if the stored object is deleted
    191266    };
    192267
     268    /// Swaps the contents of two weak pointers.
    193269    template <class T>
    194270    void swap(WeakPtr<T>& a, WeakPtr<T>& b)
    … …  
    197273    }
    198274
     275    /// Uses a static_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new WeakPtr<T>.
    199276    template <class T, class U>
    200277    WeakPtr<T> static_pointer_cast(const WeakPtr<U>& p)
    … …  
    203280    }
    204281
     282    /// Uses a const_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new WeakPtr<T>.
    205283    template <class T, class U>
    206284    WeakPtr<T> const_pointer_cast(const WeakPtr<U>& p)
    … …  
    209287    }
    210288
     289    /// Uses a dynamic_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new WeakPtr<T>.
    211290    template <class T, class U>
    212291    WeakPtr<T> dynamic_pointer_cast(const WeakPtr<U>& p)

  • code/trunk/src/libraries/core/WindowEventListener.h

    r5781 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup Graphics
     32*/
    2833
    2934#ifndef _WindowEventListener_H__

  • code/trunk/src/libraries/core/XMLFile.h

    r6417 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup XML XMLPort
     32*/
    2833
    2934#ifndef _XMLFile_H__

  • code/trunk/src/libraries/core/XMLNameListener.h

    r5781 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup XML XMLPort
     32*/
     33
    2934#ifndef _XMLNameListener_H__
    3035#define _XMLNameListener_H__

  • code/trunk/src/libraries/core/XMLPort.h

    r7284 r7401  
    2828
    2929/**
     30    @defgroup XMLPort XMLPort
     31    @ingroup XML
     32*/
     33
     34/**
    3035    @file
     36    @ingroup XML XMLPort
    3137    @brief Declaration of the XMLPort helper classes and macros.
    3238
    … …  
    6975
    7076    In the XML file, a param or attribute will be set like this:
     77    @code
    7178    <classname paramname="value" />
     79    @endcode
    7280
    7381    The macro will then call loadfunction(value) to set the given value (or call savefunction() to
    … …  
    8896
    8997    In the XML file, a param or attribute will be set like this:
     98    @code
    9099    <classname paramname="value" />
     100    @endcode
    91101
    92102    The macro will then store "value" in the variable or read it when saving.
    … …  
    148158    @param paramname The name of the attribute
    149159    @param loadfunction The function to set the attribute inside of the member object.
    150     @param loadfunction The function to get the attribute from the member object
     160    @param savefunction The function to get the attribute from the member object
     161    @param xmlelement The XML-element that is parsed by this macro
     162    @param mode Loading or saving
    151163
    152164    Sometimes you'll have a member object in your class, which has it's own load- and savefunctions.
    153165    With this macro, you can simply use them instead of writing your own functions.
    154166
    155     @example
     167    Example:
    156168    Your class is called SpaceShip and this class has an object (myPilot_) of class Pilot. Pilot has a name
    157169    and two functions, setName(name) and getName(). Now you want an attribute "pilotname" in your
    … …  
    196208    @param sectionname The name of the subsection in the XML file that encloses the sub-objects ("" means no subsection)
    197209    @param loadfunction The function to add a new object to the class
    198     @param loadfunction The function to get all added objects from the class
     210    @param savefunction The function to get all added objects from the class
    199211    @param xmlelement The XMLElement (received through the XMLPort function)
    200212    @param mode The mode (load/save) (received through the XMLPort function)
    … …  
    210222    likely the best option, so this is usually true.
    211223
    212     @note
     224    @details
    213225    The load- and savefunctions have to follow an exactly defined protocol.
    214226    Loadfunction:
    215227      The loadfunction gets a pointer to the object.
    216       > void loadfunction(objectclass* pointer);
     228      @code
     229      void loadfunction(objectclass* pointer);
     230      @endcode
    217231
    218232    Savefunction:
    … …  
    220234      gets called again, but with index + 1. It's the functions responsibility to do something smart
    221235      with the index and to return 0 if all objects were returned.
    222       > objectclass* savefunction(unsigned int index) const;
     236      @code
     237      objectclass* savefunction(unsigned int index) const;
     238      @endcode
    223239
    224240      Possible implementation:
     241      @code
    225242        objectclass* savefunction(unsigned int index) const
    226243        {
    … …  
    230247            return 0;
    231248        }
    232 
    233     @example
     249      @endcode
     250
     251    Example:
    234252    Possible usage of the macro:
    235     > XMLPortObject(SpaceShip, Weapon, "weapons", addWeapon, getWeapon, xmlelement, mode, false, true);
     253    @code
     254    XMLPortObject(SpaceShip, Weapon, "weapons", addWeapon, getWeapon, xmlelement, mode, false, true);
     255    @endcode
    236256
    237257    Now you can add weapons through the XML file:
     258    @code
    238259    <SpaceShip someattribute="..." ...>
    239260      <weapons>
    … …  
    243264      </weapons>
    244265    </SpaceShip>
     266    @endcode
    245267
    246268    Note that "weapons" is the subsection. This allows you to add more types of sub-objects. In our example,

  • code/trunk/src/libraries/core/command/ArgumentCompleter.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @defgroup ArgumentCompletion Argument completion
     31    @ingroup Command
     32*/
     33
     34/**
     35    @file
     36    @ingroup Command ArgumentCompletion
     37    @brief Definition of the orxonox::ArgumentCompleter class that is used to execute @ref ArgumentCompletionFunctions.h "argument completion functions".
     38
     39    An ArgumentCompleter can be assigned to an orxonox::ConsoleCommand using
     40    @ref orxonox::ConsoleCommand::argumentCompleter "argumentCompleter()".
     41    The ArgumentCompleter calls an argument completion function that is defined
     42    in ArgumentCompletionFunctions.h. This can be used to list possible arguments
     43    for console commands and to allow auto-completion.
     44
     45    Instances of ArgumentCompleter are usually not created manually but rather
     46    by the macros defined in ArgumentCompletionFunctions.h. There you'll also
     47    find some examples.
     48
     49    @see See the @ref ArgumentCompletionExample "examples".
     50*/
     51
    2952#ifndef _ArgumentCompleter_H__
    3053#define _ArgumentCompleter_H__
    … …  
    3558namespace orxonox
    3659{
     60    /**
     61        @brief This class executes an argument completion function and returns a list of the possible arguments.
     62
     63        ArgumentCompleter is used to wrap argument completion functions as defined
     64        in ArgumentCompletionFunctions.h and can be assigned to a ConsoleCommand to
     65        create a list of possible arguments.
     66
     67        @see See ArgumentCompleter.h for more information.
     68        @see See @ref ArgumentCompletionExample "ArgumentCompletionFunctions.h" for an example.
     69    */
    3770    class _CoreExport ArgumentCompleter
    3871    {
    3972        public:
    40             ArgumentCompleter(ArgumentCompletionList (*function) (void), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(0), function_0_(function) {}
    41             ArgumentCompleter(ArgumentCompletionList (*function) (const std::string& param1), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(1), function_1_(function) {}
    42             ArgumentCompleter(ArgumentCompletionList (*function) (const std::string& param1, const std::string& param2), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(2), function_2_(function) {}
    43             ArgumentCompleter(ArgumentCompletionList (*function) (const std::string& param1, const std::string& param2, const std::string& param3), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(3), function_3_(function) {}
    44             ArgumentCompleter(ArgumentCompletionList (*function) (const std::string& param1, const std::string& param2, const std::string& param3, const std::string& param4), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(4), function_4_(function) {}
    45             ArgumentCompleter(ArgumentCompletionList (*function) (const std::string& param1, const std::string& param2, const std::string& param3, const std::string& param4, const std::string& param5), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(5), function_5_(function) {}
     73            ArgumentCompleter(ArgumentCompletionList (*function) (void), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(0), function_0_(function) {} ///< Constructor, assigns a function-pointer with no arguments.
     74            ArgumentCompleter(ArgumentCompletionList (*function) (const std::string& param1), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(1), function_1_(function) {} ///< Constructor, assigns a function-pointer with one argument.
     75            ArgumentCompleter(ArgumentCompletionList (*function) (const std::string& param1, const std::string& param2), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(2), function_2_(function) {} ///< Constructor, assigns a function-pointer with two arguments.
     76            ArgumentCompleter(ArgumentCompletionList (*function) (const std::string& param1, const std::string& param2, const std::string& param3), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(3), function_3_(function) {} ///< Constructor, assigns a function-pointer with three arguments.
     77            ArgumentCompleter(ArgumentCompletionList (*function) (const std::string& param1, const std::string& param2, const std::string& param3, const std::string& param4), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(4), function_4_(function) {} ///< Constructor, assigns a function-pointer with four arguments.
     78            ArgumentCompleter(ArgumentCompletionList (*function) (const std::string& param1, const std::string& param2, const std::string& param3, const std::string& param4, const std::string& param5), bool bUseMultipleWords) : bUseMultipleWords_(bUseMultipleWords), paramCount_(5), function_5_(function) {} ///< Constructor, assigns a function-pointer with five arguments.
    4679
     80            /**
     81                @brief Calls the argument completion function with a maximum of five parameters.
     82                @return Returns the list of possible arguments, created by the argument completion function
     83            */
    4784            ArgumentCompletionList operator()(const std::string& param1 = "", const std::string& param2 = "", const std::string& param3 = "", const std::string& param4 = "", const std::string& param5 = "")
    4885            {
    … …  
    66103            }
    67104
     105            /// Returns true if the argument completion list supports multiple words.
    68106            inline bool useMultipleWords() const
    69107                { return this->bUseMultipleWords_; }
    70108
    71109        private:
    72             bool bUseMultipleWords_;
    73             unsigned char paramCount_;
    74             ArgumentCompletionList (*function_0_) (void);
    75             ArgumentCompletionList (*function_1_) (const std::string& param1);
    76             ArgumentCompletionList (*function_2_) (const std::string& param1, const std::string& param2);
    77             ArgumentCompletionList (*function_3_) (const std::string& param1, const std::string& param2, const std::string& param3);
    78             ArgumentCompletionList (*function_4_) (const std::string& param1, const std::string& param2, const std::string& param3, const std::string& param4);
    79             ArgumentCompletionList (*function_5_) (const std::string& param1, const std::string& param2, const std::string& param3, const std::string& param4, const std::string& param5);
     110            bool bUseMultipleWords_;    ///< If true, the argument completion list supports multiple words
     111            unsigned char paramCount_;  ///< The number of parameters of the argument completion function
     112            ArgumentCompletionList (*function_0_) (void);   ///< Function-pointer for an argument completion function with no arguments
     113            ArgumentCompletionList (*function_1_) (const std::string& param1);   ///< Function-pointer for an argument completion function with one argument
     114            ArgumentCompletionList (*function_2_) (const std::string& param1, const std::string& param2);   ///< Function-pointer for an argument completion function with two arguments
     115            ArgumentCompletionList (*function_3_) (const std::string& param1, const std::string& param2, const std::string& param3);   ///< Function-pointer for an argument completion function with three arguments
     116            ArgumentCompletionList (*function_4_) (const std::string& param1, const std::string& param2, const std::string& param3, const std::string& param4);   ///< Function-pointer for an argument completion function with four arguments
     117            ArgumentCompletionList (*function_5_) (const std::string& param1, const std::string& param2, const std::string& param3, const std::string& param4, const std::string& param5);   ///< Function-pointer for an argument completion function with five arguments
    80118    };
    81119}

  • code/trunk/src/libraries/core/command/ArgumentCompletionFunctions.cc

    r7284 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @brief Implementation of all argument completion functions
     32*/
    2833
    2934#include "ArgumentCompletionFunctions.h"
    … …  
    5358    namespace autocompletion
    5459    {
     60        /**
     61            @brief Fallback implementation, returns an empty list.
     62        */
    5563        ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(fallback)()
    5664        {
    … …  
    6068        namespace detail
    6169        {
     70            /**
     71                @brief Returns true if a group of console commands is visible (i.e. if at least one command in this group is visible).
     72            */
    6273            bool groupIsVisible(const std::map<std::string, ConsoleCommand*>& group, bool bOnlyShowHidden)
    6374            {
    … …  
    6980            }
    7081
     82            /**
     83                @brief Returns a list of all console command groups AND all console command shortcuts.
     84                @param fragment The last argument
     85                @param bOnlyShowHidden If true, only hidden groups and commands are returned
     86            */
    7187            ArgumentCompletionList _groupsandcommands(const std::string& fragment, bool bOnlyShowHidden)
    7288            {
     89                // note: this function returns only arguments that begin with "fragment", which would't be necessary for the
     90                //       auto-completion, but it's necessary to place the line-break "\n" between groups and commands
     91                //       only if both groups AND commands are in the list.
     92
    7393                ArgumentCompletionList groupList;
    7494                std::string fragmentLC = getLowercase(fragment);
    7595
     96                // get all the groups that are visible (except the shortcut group "")
    7697                const std::map<std::string, std::map<std::string, ConsoleCommand*> >& commands = ConsoleCommand::getCommands();
    7798                for (std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = commands.begin(); it_group != commands.end(); ++it_group)
    … …  
    79100                        groupList.push_back(ArgumentCompletionListElement(it_group->first, getLowercase(it_group->first)));
    80101
     102                // now add all shortcuts (in group "")
    81103                std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = commands.find("");
    82104                if (it_group != commands.end())
    83105                {
     106                    // add a line-break if the list isn't empty
    84107                    if (!groupList.empty())
    85108                        groupList.push_back(ArgumentCompletionListElement("", "", "\n"));
    86109
     110                    // add the shortcuts
    87111                    for (std::map<std::string, ConsoleCommand*>::const_iterator it_command = it_group->second.begin(); it_command != it_group->second.end(); ++it_command)
    88112                        if (it_command->second->isActive() && it_command->second->hasAccess() && (!it_command->second->isHidden())^bOnlyShowHidden && (fragmentLC == "" || getLowercase(it_command->first).find_first_of(fragmentLC) == 0))
    … …  
    90114                }
    91115
     116                // if no shortcut was added, remove the line-break again
    92117                if (!groupList.empty() && groupList.back().getDisplay() == "\n")
    93118                    groupList.pop_back();
    … …  
    96121            }
    97122
     123            /**
     124                @brief Returns a list of all console commands in a given group.
     125                @param fragment The last argument
     126                @param group The group's name
     127                @param bOnlyShowHidden If true, only hidden console commands are returned
     128            */
    98129            ArgumentCompletionList _subcommands(const std::string& fragment, const std::string& group, bool bOnlyShowHidden)
    99130            {
    … …  
    102133                std::string groupLC = getLowercase(group);
    103134
     135                // find the iterator of the given group
    104136                std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = ConsoleCommand::getCommands().begin();
    105137                for ( ; it_group != ConsoleCommand::getCommands().end(); ++it_group)
    … …  
    107139                        break;
    108140
     141                // add all commands in the group to the list
    109142                if (it_group != ConsoleCommand::getCommands().end())
    110143                {
    … …  
    118151        }
    119152
     153        /**
     154            @brief Returns a list of all console command groups AND all console command shortcuts.
     155        */
    120156        ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(groupsandcommands)(const std::string& fragment)
    121157        {
    … …  
    123159        }
    124160
     161        /**
     162            @brief Returns a list of all console commands in a given group.
     163        */
    125164        ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(subcommands)(const std::string& fragment, const std::string& group)
    126165        {
    … …  
    128167        }
    129168
     169        /**
     170            @brief Returns a list of commands and groups and also supports auto-completion of the arguments of these commands.
     171
     172            This is a multi-word function, because commands are composed of 1-2 words and additional arguments.
     173        */
    130174        ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI(command)(const std::string& fragment)
    131175        {
    … …  
    145189        }
    146190
     191        /**
     192            @brief Returns a list of hidden commands and groups and also supports auto-completion of the arguments of these commands.
     193
     194            This is a multi-word function, because commands are composed of 1-2 words and additional arguments.
     195
     196            This function makes commands visible that would usually be hidden.
     197        */
    147198        ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI(hiddencommand)(const std::string& fragment)
    148199        {
    … …  
    170221        }
    171222
     223        /**
     224            @brief Returns possible files and directories and also supports files in arbitrary deeply nested subdirectories.
     225
     226            This function returns files and directories in the given path. This allows to
     227            navigate iteratively through the file system. The first argument @a fragment
     228            is used to get the current path.
     229        */
    172230        ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(files)(const std::string& fragment)
    173231        {
    … …  
    211269        }
    212270
     271        /**
     272            @brief Returns the sections of the config file.
     273        */
    213274        ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(settingssections)()
    214275        {
    … …  
    222283        }
    223284
     285        /**
     286            @brief Returns the entries in a given section of the config file.
     287        */
    224288        ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(settingsentries)(const std::string& fragment, const std::string& section)
    225289        {
    … …  
    235299        }
    236300
     301        /**
     302            @brief Returns the current value of a given value in a given section of the config file.
     303        */
    237304        ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(settingsvalue)(const std::string& fragment, const std::string& entry, const std::string& section)
    238305        {
    … …  
    255322        }
    256323
     324        /**
     325            @brief Returns a list of indexes of the available Tcl threads (see TclThreadManager).
     326        */
    257327        ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(tclthreads)()
    258328        {

  • code/trunk/src/libraries/core/command/ArgumentCompletionFunctions.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command ArgumentCompletion
     32    @brief Declaration of all argument completion functions and macros used to define them.
     33
     34    @anchor ArgumentCompletionExample
     35
     36    Argument completion functions are used to create a list of possible arguments
     37    for an orxonox::ConsoleCommand. These functions are usually wrapped by an instance
     38    of orxonox::ArgumentCompleter.
     39
     40    Argument completion functions can be declared and implemented by using the macros
     41    ARGUMENT_COMPLETION_FUNCTION_DECLARATION() and ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()
     42    respectively. They are necessary because they don't simply define the function, but they also
     43    create a static helper function that returns an instance of orxonox::ArgumentCompleter which
     44    wraps the defined function. This allows easier referencing of argument completion functions
     45    by simply calling autocompletion::functionname().
     46
     47    Argument completion functions can take up to 5 arguments, all of type std::string.
     48    The first argument is always the current argument which is being entered by the user
     49    in the shell. The second argument is the argument before, so in fact arguments from
     50    the shell are sent in reversed order to the argument completion function. This is
     51    necessary because the number of arguments can be variable
     52
     53    Example: The user types the following into the shell:
     54    @code
     55    $ commandname argument1 argument2 argum
     56    @endcode
     57    Then he presses the @a tab key to print the possible arguments. Now the argument
     58    completion function for the @a third argument of @a commandname will be called in
     59    the following way:
     60    @code
     61    list = argcompfunction3("argum", "argument2", "argument1");
     62    @endcode
     63
     64    Usually each argument is one word (without whitespaces in it), but some argument completion
     65    functions need more than one word. This can be achieved by using ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI().
     66    In this case all supernumerous words are passed to the first (!) argument.
     67
     68    An example to show how to declare, implement, and use an argument completion function:
     69    @code
     70    // ArgumentCompletionFunctions.h:
     71    // ------------------------------
     72
     73    // Declaration of the function:
     74    ARGUMENT_COMPLETION_FUNCTION_DECLARATION(month)(const std::string& fragment);
     75
     76    // ArgumentCompletionFunctions.cc:
     77    // -------------------------------
     78
     79    // Implementation of the function
     80    ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(month)(const std::string& fragment)
     81    {
     82        ArgumentCompletionList list;
     83
     84        // check if the first part of the argument is a number - if yes, the user likely wants to enter the month as a number
     85        if (isNumber(fragment))
     86        {
     87            for (int month = 1; month <= 12; ++month)
     88                list.push_back(ArgumentCompletionListElement(multi_cast<std::string>(month)));
     89        }
     90        else
     91        {
     92            list.push_back(ArgumentCompletionListElement("January",   "january"));
     93            list.push_back(ArgumentCompletionListElement("February",  "february"));
     94            list.push_back(ArgumentCompletionListElement("March",     "march"));
     95            list.push_back(ArgumentCompletionListElement("April",     "april"));
     96            list.push_back(ArgumentCompletionListElement("May",       "may"));
     97            list.push_back(ArgumentCompletionListElement("June",      "june"));
     98            list.push_back(ArgumentCompletionListElement("July",      "july"));
     99            list.push_back(ArgumentCompletionListElement("August",    "august"));
     100            list.push_back(ArgumentCompletionListElement("September", "september"));
     101            list.push_back(ArgumentCompletionListElement("October",   "october"));
     102            list.push_back(ArgumentCompletionListElement("November",  "november"));
     103            list.push_back(ArgumentCompletionListElement("December",  "december"));
     104        }
     105
     106        return list;
     107    }
     108
     109    // SomeFile:
     110    // ---------
     111
     112    // A class to manage the date:
     113    class Date
     114    {
     115        public:
     116            static void setDate(int day, const std::string& month, int year);
     117    };
     118
     119    // Define a console command that needs a date. Add argument completion for the month:
     120    SetConsoleCommand("setDate", &Date::setDate).argumentCompleter(1, autocompletion::month());
     121    @endcode
     122
     123    This example defines an argument completion function that returns a list of possible
     124    months. If the first part of the argument is a number, it returns the numbers 1-12,
     125    otherwise the name of the months are returned. Note how the list is composed by
     126    instances of orxonox::ArgumentCompletionListElement. For the name of the months,
     127    two strings are provided, one in normal case and one in lower case. See the documentation
     128    of orxonox::ArgumentCompletionListElement for more information about this.
     129
     130    Also note that the argument completion list is assigned to the console command by using
     131    @ref orxonox::ConsoleCommand::argumentCompleter "argumentCompleter()". The first argument
     132    is the index of the argument:
     133     - 0 is the first argument (@a day)
     134     - 1 is the second argument (@a month)
     135     - 2 is the third argument (@a year)
     136
     137    @a day and @a year don't need an argument completion function as they are just integers.
     138
     139    The function @c autocompletion::month() is automatically created by the macros
     140    ARGUMENT_COMPLETION_FUNCTION_DECLARATION() and ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()
     141    and returns an orxonox::ArgumentCompleter that wraps the defined argument completion function.
     142
     143    The implemented argument completion function uses only one argument, the fragment of the
     144    currently entered argument. More complex functions can also use the previous arguments
     145    to return different arguments depending on the other arguments (for example to list the
     146    members of a class, where the class-name is the first argument and the member the second).
     147*/
     148
    29149#ifndef _ArgumentCompletionFunctions_H__
    30150#define _ArgumentCompletionFunctions_H__
    … …  
    33153#include "ArgumentCompleter.h"
    34154
    35 
     155/**
     156    @brief Used to declare an argument completion function with name @a functionname.
     157    @param functionname The name of the function, will also be used for the implementation of the function.
     158
     159    The macro also defines a static function that returns an orxonox::ArgumentCompleter
     160    which wraps the defined function. This can be accessed by calling autocompletion::functionname();
     161*/
    36162#define ARGUMENT_COMPLETION_FUNCTION_DECLARATION(functionname) \
    37163    _CoreExport ArgumentCompleter* functionname(); \
    38164    _CoreExport ArgumentCompletionList acf_##functionname
    39165
     166/**
     167    @brief Used to implement an argument completion function.
     168    @param functionname The name of the function
     169*/
    40170#define ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(functionname) \
    41171    _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, false)
     172
     173/**
     174    @brief Used to implement an argument completion function which allows multiple words.
     175    @param functionname The name of the function
     176*/
    42177#define ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI(functionname) \
    43178    _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, true)
    44179
     180/// Internal macro
    45181#define _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, bUseMultipleWords) \
    46182    ArgumentCompleter* functionname() \
    … …  
    52188    ArgumentCompletionList acf_##functionname
    53189
     190/// Calls an argument completion function. Used for functions that return the results of another argument completion function.
    54191#define ARGUMENT_COMPLETION_FUNCTION_CALL(functionname) acf_##functionname
    55192

  • code/trunk/src/libraries/core/command/ArgumentCompletionListElement.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command ArgumentCompletion
     32    @brief Definition of ArgumentCompletionList, which is  used in @ref ArgumentCompletionFunctions.h "argument completion functions", and its element.
     33*/
     34
    2935#ifndef _ArgumentCompletionListElement_H__
    3036#define _ArgumentCompletionListElement_H__
    … …  
    3743namespace orxonox
    3844{
    39     const int ACL_MODE_NORMAL    = 1;
    40     const int ACL_MODE_COMPARABLE = 2;
    41     const int ACL_MODE_DISPLAY   = 4;
     45    const int ACL_MODE_NORMAL     = 1;  ///< A flag, used if there's a normal string
     46    const int ACL_MODE_COMPARABLE = 2;  ///< A flag, used if there's a different string used to compare
     47    const int ACL_MODE_DISPLAY    = 4;  ///< A flag, used if there's a different string used to be displayed
    4248
    4349    typedef std::list<ArgumentCompletionListElement> ArgumentCompletionList;
    4450
     51    /**
     52        @brief This class is used in argument completion lists and contains up to three different strings, used in different situations.
     53
     54        A list containing elements of type ArgumentCompletionListElement is returned by
     55        an @ref ArgumentCompletionFunctions.h "argument completion function". These elements
     56        are composed of up to three strings with different usage:
     57         - normal: What is used as the actual argument
     58         - comparable: What is used to compere the argument to the input of the user (usually lowercase, except for case-sensitive arguments)
     59         - display: This is displayed in the list of possible arguments - can differ from what is actually used for better readability
     60
     61        @remarks An element with an empty ("") 'comparable' string will be ignored by the argument
     62        completion algorithms, but it's 'display' string will still be printed in the list. This
     63        can be used to add additional information, whitespaces, linebreaks or whatever is needed
     64        to format the output.
     65    */
    4566    class _CoreExport ArgumentCompletionListElement
    4667    {
    4768        public:
     69            /// Constructor: Normal, comparable, and display string are all the same.
    4870            ArgumentCompletionListElement(const std::string& normalcase) : mode_(ACL_MODE_NORMAL), normal_(normalcase) {}
     71            /// Constructor: Normal and display string are the same, a different (usually lowercase) string is used for comparison.
    4972            ArgumentCompletionListElement(const std::string& normalcase, const std::string& lowercase) : mode_(ACL_MODE_NORMAL | ACL_MODE_COMPARABLE), normal_(normalcase), comparable_(lowercase) {}
     73            /// Constructor: Normal, comparable, and display are all different strings.
    5074            ArgumentCompletionListElement(const std::string& normalcase, const std::string& lowercase, const std::string& display) : mode_(ACL_MODE_NORMAL | ACL_MODE_COMPARABLE | ACL_MODE_DISPLAY), normal_(normalcase), comparable_(lowercase), display_(display) {}
    5175
     76            /// Returns the normal string which is used as the actual argument.
    5277            const std::string& getString() const
    5378                { return this->normal_; }
     79            /// Returns the comparable string which is used to compare arguments and user input
    5480            const std::string& getComparable() const
    5581                { return (this->mode_ & ACL_MODE_COMPARABLE) ? this->comparable_ : this->normal_; }
     82            /// Returns the display string which is used in the displayed list of possible arguments
    5683            const std::string& getDisplay() const
    5784                { return (this->mode_ & ACL_MODE_DISPLAY) ? this->display_ : this->normal_; }
    5885
     86            /// Returns true if there's a different string for comparison.
    5987            bool hasComparable() const
    6088                { return (this->mode_ & ACL_MODE_COMPARABLE); }
     89            /// Returns true if there's a different string to display.
    6190            bool hasDisplay() const
    6291                { return (this->mode_ & ACL_MODE_DISPLAY); }
    6392
     93            /// Overloaded operator for usage in maps and sets.
    6494            bool operator<(const ArgumentCompletionListElement& other) const
    6595                { return (this->getComparable() < other.getComparable()); }
    6696
    6797        private:
    68             unsigned char mode_;
    69             std::string normal_;
    70             std::string comparable_;
    71             std::string display_;
     98            unsigned char mode_;        ///< The flags
     99            std::string normal_;        ///< The normal string
     100            std::string comparable_;    ///< The comparable (usually lowercase) string
     101            std::string display_;       ///< The string to display
    72102    };
    73103}

  • code/trunk/src/libraries/core/command/CommandEvaluation.cc

    r7286 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of CommandEvaluation
     32*/
     33
    2934#include "CommandEvaluation.h"
    3035
    … …  
    3540namespace orxonox
    3641{
     42    /**
     43        @brief Constructor: Initializes the command evaluation with an empty command.
     44    */
    3745    CommandEvaluation::CommandEvaluation()
    3846    {
    … …  
    4048    }
    4149
     50    /**
     51        @brief Initializes all values.
     52    */
    4253    void CommandEvaluation::initialize(const std::string& command)
    4354    {
    … …  
    4960        this->bPossibleArgumentsRetrieved_ = false;
    5061        this->possibleArguments_.clear();
    51         this->bEvaluatedParams_ = false;
    52         this->bTriedToEvaluatedParams_ = false;
    53         this->numberOfEvaluatedParams_ = 0;
    54 
     62        this->bEvaluatedArguments_ = false;
     63        this->bTriedToEvaluatedArguments_ = false;
     64        this->numberOfEvaluatedArguments_ = 0;
     65
     66        // split the command into tokens
    5567        this->tokens_.split(command, " ", SubString::WhiteSpaces, false, '\\', true, '"', true, '{', '}', true, '\0');
    5668    }
    5769
     70    /**
     71        @brief Returns the number of tokens according to the definition of CommandExecutor (which counts also an empty argument at the end of the string).
     72    */
    5873    unsigned int CommandEvaluation::getNumberOfArguments() const
    5974    {
    6075        unsigned int count = this->tokens_.size();
    61         if (count > 0 && this->string_[this->string_.size() - 1] != ' ')
     76
     77        // If the last char in the string is a space character (or the string is empty), add +1 to the number of tokens, because this counts as an additional (but empty) argument
     78        if (count == 0 || this->string_[this->string_.size() - 1] == ' ')
     79            return count + 1;
     80        else
    6281            return count;
     82    }
     83
     84    /**
     85        @brief Returns the last argument (which is the one the user currently enters into the shell).
     86    */
     87    const std::string& CommandEvaluation::getLastArgument() const
     88    {
     89        // the string is empty or ends with a space character, the user is just about to enter a new argument (but its still empty). return a blank string in this case.
     90        if (this->tokens_.size() == 0 || this->string_[this->string_.size() - 1] == ' ')
     91            return BLANKSTRING;
    6392        else
    64             return count + 1;
    65     }
    66 
    67     const std::string& CommandEvaluation::getLastArgument() const
    68     {
    69         if (this->tokens_.size() > 0 && this->string_[this->string_.size() - 1] != ' ')
    7093            return this->tokens_.back();
    71         else
    72             return BLANKSTRING;
    73     }
    74 
     94    }
     95
     96    /**
     97        @brief Returns the token with the given index (or a blank string if it doesn't exist).
     98    */
    7599    const std::string& CommandEvaluation::getToken(unsigned int i) const
    76100    {
    … …  
    81105    }
    82106
     107    /**
     108        @brief Executes the command which was evaluated by this object.
     109        @return Returns the error code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
     110    */
    83111    int CommandEvaluation::execute()
    84112    {
    … …  
    88116    }
    89117
     118    /**
     119        @brief Executes the command which was evaluated by this object and returns its return-value.
     120        @param error A pointer to an integer (or NULL) which will be used to write error codes to (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
     121        @return Returns the result of the command (or MT_Type::Null if there is no return value)
     122    */
    90123    MultiType CommandEvaluation::query(int* error)
    91124    {
     125        // check if an error value was passed by reference
    92126        if (error)
    93127        {
     128            // Determine the error-code and return if it is not Success
     129
    94130            *error = CommandExecutor::Success;
    95131
    … …  
    105141        }
    106142
     143        // check if it's possible to execute the command
    107144        if (this->execCommand_ && this->execCommand_->isActive() && this->execCommand_->hasAccess())
    108145        {
    109             if (!this->bTriedToEvaluatedParams_)
    110                 this->evaluateParams(false);
    111 
    112             if (this->bEvaluatedParams_)
    113             {
    114                 COUT(6) << "CE_execute (evaluation): " << this->execCommand_->getName() << " with " << this->numberOfEvaluatedParams_ << " params: " << this->param_[0] << ' ' << this->param_[1] << ' ' << this->param_[2] << ' ' << this->param_[3] << ' ' << this->param_[4] << std::endl;
    115                 switch (this->numberOfEvaluatedParams_)
     146            // if the arguments weren't evaluated yet, do it now.
     147            if (!this->bTriedToEvaluatedArguments_)
     148                this->evaluateArguments(false);
     149
     150            // check if the argument evaluation succeded
     151            if (this->bEvaluatedArguments_)
     152            {
     153                COUT(6) << "CE_execute (evaluation): " << this->execCommand_->getName() << " with " << this->numberOfEvaluatedArguments_ << " arguments: " << this->arguments_[0] << ' ' << this->arguments_[1] << ' ' << this->arguments_[2] << ' ' << this->arguments_[3] << ' ' << this->arguments_[4] << std::endl;
     154
     155                // pass as many arguments to the executor as were evaluated (thus the executor can still use additional default values)
     156                switch (this->numberOfEvaluatedArguments_)
    116157                {
    117158                    case 0:  return (*this->execCommand_->getExecutor())();
    118                     case 1:  return (*this->execCommand_->getExecutor())(this->param_[0]);
    119                     case 2:  return (*this->execCommand_->getExecutor())(this->param_[0], this->param_[1]);
    120                     case 3:  return (*this->execCommand_->getExecutor())(this->param_[0], this->param_[1], this->param_[2]);
    121                     case 4:  return (*this->execCommand_->getExecutor())(this->param_[0], this->param_[1], this->param_[2], this->param_[3]);
     159                    case 1:  return (*this->execCommand_->getExecutor())(this->arguments_[0]);
     160                    case 2:  return (*this->execCommand_->getExecutor())(this->arguments_[0], this->arguments_[1]);
     161                    case 3:  return (*this->execCommand_->getExecutor())(this->arguments_[0], this->arguments_[1], this->arguments_[2]);
     162                    case 4:  return (*this->execCommand_->getExecutor())(this->arguments_[0], this->arguments_[1], this->arguments_[2], this->arguments_[3]);
    122163                    case 5:
    123                     default: return (*this->execCommand_->getExecutor())(this->param_[0], this->param_[1], this->param_[2], this->param_[3], this->param_[4]);
     164                    default: return (*this->execCommand_->getExecutor())(this->arguments_[0], this->arguments_[1], this->arguments_[2], this->arguments_[3], this->arguments_[4]);
    124165                }
    125166            }
    … …  
    128169        }
    129170
     171        // return a null value in case of an error
    130172        return MT_Type::Null;
    131173    }
    132174
    133     int CommandEvaluation::evaluateParams(bool bPrintError)
    134     {
    135         this->bTriedToEvaluatedParams_ = true;
    136 
     175    /**
     176        @brief Evaluates the arguments of the command.
     177        @param bPrintError If true, the function prints an error message if it doesn't succeed
     178        @return Returns the error code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
     179    */
     180    int CommandEvaluation::evaluateArguments(bool bPrintError)
     181    {
     182        this->bTriedToEvaluatedArguments_ = true;
     183
     184        // check if there's a command to execute
    137185        if (!this->execCommand_)
    138186        {
    139187            if (bPrintError)
    140                 COUT(1) << "Error: Can't evaluate params, no console command assigned." << std::endl;
     188                COUT(1) << "Error: Can't evaluate arguments, no console command assigned." << std::endl;
    141189            return CommandExecutor::Error;
    142190        }
    143191
    144192        int error;
    145         this->numberOfEvaluatedParams_ = this->execCommand_->getExecutor()->evaluateParams(this->tokens_.subSet(this->execArgumentsOffset_), this->param_, &error, " ");
     193
     194        // try to evaluate the arguments using the executor of the evaluated command.
     195        // the arguments are currently stored as strings in token_, but afterwards they will be converted to the right type and stored in arguments_
     196        this->numberOfEvaluatedArguments_ = this->execCommand_->getExecutor()->evaluateArguments(this->tokens_.subSet(this->execArgumentsOffset_), this->arguments_, &error, " ");
     197
     198        // check if an error occurred
    146199        if (!error)
    147             this->bEvaluatedParams_ = true;
     200            this->bEvaluatedArguments_ = true;
    148201        else if (bPrintError)
    149             COUT(1) << "Error: Can't evaluate params, not enough arguments given." << std::endl;
     202            COUT(1) << "Error: Can't evaluate arguments, not enough arguments given." << std::endl;
    150203
    151204        return error;
    152205    }
    153206
    154     void CommandEvaluation::setEvaluatedParameter(unsigned int index, const MultiType& param)
     207    /**
     208        @brief Replaces an evaluated argument with a new value.
     209        @param index The index of the parameter (the first argument has index 0)
     210        @param arg The new value of the parameter
     211    */
     212    void CommandEvaluation::setEvaluatedArgument(unsigned int index, const MultiType& arg)
    155213    {
    156214        if (index < MAX_FUNCTOR_ARGUMENTS)
    157             this->param_[index] = param;
    158     }
    159 
    160     MultiType CommandEvaluation::getEvaluatedParameter(unsigned int index) const
     215            this->arguments_[index] = arg;
     216    }
     217
     218    /**
     219        @brief Returns the evaluated argument with given index.
     220        @param index The index of the argument (the first argument has index 0)
     221    */
     222    MultiType CommandEvaluation::getEvaluatedArgument(unsigned int index) const
    161223    {
    162224        if (index < MAX_FUNCTOR_ARGUMENTS)
    163             return this->param_[index];
     225            return this->arguments_[index];
    164226
    165227        return MT_Type::Null;
    166228    }
    167229
     230    /**
     231        @brief Completes the given command string using the list of possible arguments.
     232        @return Returns the completed command string
     233
     234        This is called by the shell if the user presses the @a tab key. The currently entered
     235        argument will be completed as good as possible by using the argument completion list
     236        of the evaluated command.
     237    */
    168238    std::string CommandEvaluation::complete()
    169239    {
     240        // check if it's possible to complete the command
    170241        if (!this->hintCommand_ || !this->hintCommand_->isActive())
    171242            return this->string_;
    172243
     244        // get the list of possible arguments
    173245        if (!this->bPossibleArgumentsRetrieved_)
    174246            this->retrievePossibleArguments();
    175247
     248        // if the list is empty, return the current command string
    176249        if (CommandEvaluation::getSize(this->possibleArguments_) == 0)
    177250        {
    … …  
    180253        else
    181254        {
     255            // get the first part of the command string from the beginning up to the last space character
    182256            std::string output = this->string_.substr(0, this->string_.find_last_of(' ') + 1);
     257
     258            // add the common begin of all possible arguments
    183259            output += CommandEvaluation::getCommonBegin(this->possibleArguments_);
     260
     261            // return the resulting string
    184262            return output;
    185263        }
    186264    }
    187265
     266    /**
     267        @brief Returns a string containing hints or possible arguments for the evaluated command.
     268
     269        This is called by the shell if the user presses the @a tab key. It prints a list of
     270        possible arguments or other hints, returned by the argument completion list of the
     271        evaluated command. If there's no such list, the syntax of the command is returned.
     272    */
    188273    std::string CommandEvaluation::hint()
    189274    {
     275        // check if it's possible to get hints for this command
    190276        if (!this->hintCommand_ || !this->hintCommand_->isActive())
    191277            return "";
    192278
     279        // get the list of possible arguments
    193280        if (!this->bPossibleArgumentsRetrieved_)
    194281            this->retrievePossibleArguments();
    195282
     283        // return the list of possible arguments if:
     284        //   a) it contains at least one non-empty argument
     285        //   b) it contains an entry that may be empty (not an actual argument, just a helping text) AND the command is valid
    196286        if (CommandEvaluation::getSize(this->possibleArguments_) > 0 || (!this->possibleArguments_.empty() && this->isValid()))
    197287            return CommandEvaluation::dump(this->possibleArguments_);
    198288
     289        // at this point there's no valid argument in the list, so check if the command is actually valid
    199290        if (this->isValid())
    200291        {
     292            // yes it is - return the syntax of the command
    201293            return CommandEvaluation::dump(this->hintCommand_);
    202294        }
    203295        else
    204296        {
     297            // no the command is not valid
    205298            if (this->getNumberOfArguments() > 2)
    206299            {
     300                // the user typed 2+ arguments, but they don't name a command - print an error
    207301                return std::string("Error: There is no command with name \"") + this->getToken(0) + " " + this->getToken(1) + "\".";
    208302            }
    209303            else
    210304            {
     305                // the user typed 1-2 arguments, check what he tried to type and print a suitable error
    211306                std::string groupLC = getLowercase(this->getToken(0));
    212307                for (std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = ConsoleCommand::getCommandsLC().begin(); it_group != ConsoleCommand::getCommandsLC().end(); ++it_group)
    … …  
    219314    }
    220315
     316    /**
     317        @brief If the command couln't be evaluated because it doesn't exist, print a suggestion for
     318        a command that looks close to the entered command (useful if the user mistyped the command).
     319    */
    221320    std::string CommandEvaluation::getCommandSuggestion() const
    222321    {
    … …  
    227326        unsigned int nearestDistance = (unsigned int)-1;
    228327
     328        // iterate through all groups and their commands and calculate the distance to the current command. keep the best.
    229329        for (std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = ConsoleCommand::getCommandsLC().begin(); it_group != ConsoleCommand::getCommandsLC().end(); ++it_group)
    230330        {
    … …  
    244344        }
    245345
     346        // now also iterate through all shortcuts and keep the best if it's better than the one found above.
    246347        std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = ConsoleCommand::getCommandsLC().find("");
    247348        if (it_group !=  ConsoleCommand::getCommandsLC().end())
    … …  
    259360        }
    260361
     362        // return the command that's closest to the current one.
    261363        return nearestCommand;
    262364    }
    263365
     366    /**
     367        @brief Gets the possible arguments for the command in its current state.
     368    */
    264369    void CommandEvaluation::retrievePossibleArguments()
    265370    {
    266371        this->bPossibleArgumentsRetrieved_ = true;
     372
     373        // we use the hintCommand_ to get possible arguments. get the index of the last argument. limit the index if its greater than the number of arguments supported by the command.
    267374        unsigned int argumentID = std::min(this->getNumberOfArguments() - this->hintArgumentsOffset_, this->hintCommand_->getExecutor()->getParamCount());
     375
     376        // get the argument completer for the given argument index
    268377        ArgumentCompleter* ac = this->hintCommand_->getArgumentCompleter(argumentID - 1);
    269378
     379        // check if an argument completer exists
    270380        if (ac)
    271381        {
    272             MultiType param[MAX_FUNCTOR_ARGUMENTS];
    273 
     382            MultiType arg[MAX_FUNCTOR_ARGUMENTS];
     383
     384            // the index of the last argument in the command string that is supported by this argument completer
    274385            size_t max = this->hintArgumentsOffset_ + this->hintCommand_->getExecutor()->getParamCount();
    275386
     387            // write the argument strings to the argument array (in reversed order, as required by the argument completion function)
    276388            for (size_t i = 0; i < argumentID; ++i)
    277                 param[i] = this->getToken(std::min(this->getNumberOfArguments(), (unsigned int)max) - i - 1);
    278 
     389                arg[i] = this->getToken(std::min(this->getNumberOfArguments(), (unsigned int)max) - i - 1);
     390
     391            // check if there are more arguments given by the user than supported
    279392            if (this->getNumberOfArguments() > max)
    280393            {
     394                // yes - now check if multiple words are supported by the argument completer
    281395                if (ac->useMultipleWords())
    282396                {
     397                    // yes - join the surplus arguments
    283398                    std::string surplusArguments = this->tokens_.subSet(max - 1).join();
    284399                    if (this->string_[this->string_.size() - 1] == ' ')
    285400                        surplusArguments += ' ';
    286401
    287                     this->possibleArguments_ = (*ac)(surplusArguments, param[1], param[2], param[3], param[4]);
     402                    // pass all surplus arguments as the first argument to the argument completer
     403                    this->possibleArguments_ = (*ac)(surplusArguments, arg[1], arg[2], arg[3], arg[4]);
     404
     405                    // strip the list using the last argument
    288406                    CommandEvaluation::strip(this->possibleArguments_, this->getToken(this->getNumberOfArguments() - 1));
    289407                }
     408                else
     409                {
     410                    // no - the user typed more arguments than supported, no action
     411                }
    290412            }
    291413            else
    292414            {
    293                 this->possibleArguments_ = (*ac)(param[0], param[1], param[2], param[3], param[4]);
    294                 CommandEvaluation::strip(this->possibleArguments_, param[0]);
    295             }
    296         }
    297     }
    298 
     415                // no - so simply call the argument completer and get the list of arguments
     416                this->possibleArguments_ = (*ac)(arg[0], arg[1], arg[2], arg[3], arg[4]);
     417
     418                // strip the list using the last argument (stored arg[0])
     419                CommandEvaluation::strip(this->possibleArguments_, arg[0]);
     420            }
     421        }
     422    }
     423
     424    /**
     425        @brief Returns the size of an argument completion list - empty ("") arguments are not counted.
     426    */
    299427    /* static */ size_t CommandEvaluation::getSize(const ArgumentCompletionList& list)
    300428    {
    … …  
    306434    }
    307435
     436    /**
     437        @brief Removes all elements from the list that don't start with @a fragment.
     438        @param list The argument completion list
     439        @param fragment The argument that is currently entered by the user and that needs to be completed
     440    */
    308441    /* static */ void CommandEvaluation::strip(ArgumentCompletionList& list, const std::string& fragment)
    309442    {
    310443        std::string fragmentLC = getLowercase(fragment);
    311444
     445        // iterate through the list
    312446        for (ArgumentCompletionList::iterator it = list.begin(); it != list.end(); )
    313447        {
    314448            const std::string& entry = it->getComparable();
    315449
     450            // check if the argument is empty - if yes, keep it always in the list
    316451            if (entry == "")
    317452            {
    … …  
    320455            }
    321456
     457            // check the length of the argument - arguments smaller than 'fragment' are always erased
    322458            if (entry.size() < fragmentLC.size())
    323459            {
    … …  
    326462            else
    327463            {
     464                // compare the argument char by char with 'fragment'
    328465                bool bErase = false;
    329466                for (size_t i = 0; i < fragmentLC.size(); ++i)
    … …  
    344481    }
    345482
     483    /**
     484        @brief Returns the commond begin of all arguments in the list.
     485    */
    346486    /* static */ std::string CommandEvaluation::getCommonBegin(const ArgumentCompletionList& list)
    347487    {
    348488        if (CommandEvaluation::getSize(list) == 0)
    349489        {
     490            // no (non-empty) values in the list, return an empty string
    350491            return "";
    351492        }
    352493        else if (CommandEvaluation::getSize(list) == 1)
    353494        {
     495            // only one (non-empty) value in the list - search it and return it
    354496            for (ArgumentCompletionList::const_iterator it = list.begin(); it != list.end(); ++it)
    355497            {
    356498                if (it->getComparable() != "")
    357499                {
     500                    // arguments that have a separate string to be displayed need a little more care - just return them without modification. add a space character to the others.
    358501                    if (it->hasDisplay())
    359502                        return (it->getString());
    … …  
    367510        else
    368511        {
     512            // multiple arguments in the list - iterate through it and find the common begin of all arguments
    369513            std::string output;
    370514            for (unsigned int i = 0; true; i++)
    371515            {
    372                 char tempComparable = 0;
    373                 char temp = 0;
     516                char tempComparable = '\0';
     517                char temp = '\0';
    374518                for (ArgumentCompletionList::const_iterator it = list.begin(); it != list.end(); ++it)
    375519                {
    … …  
    377521                    const std::string& argument = it->getString();
    378522
     523                    // ignore empty arguments
    379524                    if (argumentComparable == "")
    380525                        continue;
    … …  
    382527                    if (argument.size() > i)
    383528                    {
    384                         if (tempComparable == 0)
     529                        if (tempComparable == '\0')
    385530                        {
     531                            // the first entry is always taken
    386532                            tempComparable = argumentComparable[i];
    387533                            temp = argument[i];
    … …  
    389535                        else
    390536                        {
     537                            // all other entries need comparison to the first entry
    391538                            if (tempComparable != argumentComparable[i])
    392539                                return output;
    393                             else if (temp != argument[i])
     540                            else if (temp != argument[i]) // the comparables match, but the normal chars don't - switch to comparable only
    394541                                temp = tempComparable;
    395542                        }
    … …  
    406553    }
    407554
     555    /**
     556        @brief Joins the elements of the given list to a string.
     557    */
    408558    /* static */ std::string CommandEvaluation::dump(const ArgumentCompletionList& list)
    409559    {
    … …  
    413563            output += it->getDisplay();
    414564
     565            // add a space character between two elements for all non-empty arguments
    415566            if (it->getComparable() != "")
    416567                output += ' ';
    … …  
    419570    }
    420571
     572    /**
     573        @brief Returns a string that explains the syntax of the given command.
     574    */
    421575    /* static */ std::string CommandEvaluation::dump(const ConsoleCommand* command)
    422576    {
     577        // get the name of the command
    423578        std::string output = command->getName();
     579
     580        // check if there are parameters
    424581        if (command->getExecutor()->getParamCount() > 0)
    425582            output += ": ";
    426583
     584        // iterate through the parameters
    427585        for (unsigned int i = 0; i < command->getExecutor()->getParamCount(); i++)
    428586        {
     587            // separate the parameters with a space character
    429588            if (i != 0)
    430589                output += ' ';
    431590
     591            // print default values in [], others in {} braces
    432592            if (command->getExecutor()->defaultValueSet(i))
    433593                output += '[';
    … …  
    435595                output += '{';
    436596
     597            // add the type-name of the parameter
    437598            output += command->getExecutor()->getTypenameParam(i);
    438599
     600            // print the default value if available
    439601            if (command->getExecutor()->defaultValueSet(i))
    440602                output += '=' + command->getExecutor()->getDefaultValue(i).getString() + ']';

  • code/trunk/src/libraries/core/command/CommandEvaluation.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @defgroup CommandExecEval Command execution and evaluation
     31    @ingroup Command
     32*/
     33
     34/**
     35    @file
     36    @ingroup Command CommandExecEval
     37    @brief Declaration of the orxonox::CommandEvaluation class which is returned by orxonox::CommandExecutor::evaluate().
     38
     39    The orxonox::CommandEvaluation class gathers all information about a command-string. It is used
     40    internally by orxonox::CommandExecutor and can also be returned by it to provide more information
     41    about a command. It's also possible to evaluate the arguments of a command to execute it faster.
     42
     43    @see See @ref CommandExecutorExample "this description" for an example.
     44*/
     45
    2946#ifndef _CommandEvaluation_H__
    3047#define _CommandEvaluation_H__
    … …  
    4158namespace orxonox
    4259{
     60    /**
     61        @brief CommandEvaluation is used to gather information about a command and to evaluate its arguments
     62
     63        This class provides several information about a command-string, for example the
     64        evaluated ConsoleCommand, but also other information like hints if the command
     65        is not yet finished.
     66
     67        @note You don't have to call evaluateArguments() manually, it's also done automatically
     68        if you call the command the first time. However you can of course do it at any earlier
     69        time, for example to return an error message if it doesn't work.
     70
     71        @remarks execCommand_ and hintCommand_ can be different in this case: There are multiple
     72        commands avaliable, let's say "tcl", "tclexecute", and "tclquery". The user enters
     73        "tcl", which is already a valid command. Now execCommand_ points to the "tcl"-command,
     74        but hintCommand_ still points to the autocompletion command of CommandExecutor, because
     75        the auto-completion list must still return the three possible commands, "tcl tclexecute tclquery"
     76        because the user may want to execute "tclquery" and needs auto-completion.
     77
     78        @see See @ref CommandExecutorExample "this description" for an example.
     79    */
    4380    class _CoreExport CommandEvaluation
    4481    {
    … …  
    5693            std::string getCommandSuggestion() const;
    5794
    58             int evaluateParams(bool bPrintError = false);
     95            int evaluateArguments(bool bPrintError = false);
    5996
     97            /// Returns true if the command evaluation contains a valid command that can be executed.
    6098            inline bool isValid() const
    6199                { return (this->execCommand_ != 0); }
    62100
     101            /// Returns the console command that was evaluated by this object.
    63102            inline const ConsoleCommand* getConsoleCommand() const
    64103                { return this->execCommand_; }
    65104
    66             void setEvaluatedParameter(unsigned int index, const MultiType& param);
    67             MultiType getEvaluatedParameter(unsigned int index) const;
     105            void setEvaluatedArgument(unsigned int index, const MultiType& arg);
     106            MultiType getEvaluatedArgument(unsigned int index) const;
    68107
     108            /**
     109                @brief Returns a list of possible arguments for the given command.
     110
     111                Note that the command's arguments may not be complete yet, so in this case
     112                this list returns the possibilities. They can then be used to display a list
     113                of the possible arguments or to apply auto-completion.
     114            */
    69115            const ArgumentCompletionList& getPossibleArguments() const
    70116                { return this->possibleArguments_; }
    71117
     118            /// Returns the number of possible arguments. Empty ("") arguments are not counted.
    72119            size_t getPossibleArgumentsSize() const
    73120                { return CommandEvaluation::getSize(this->possibleArguments_); }
    … …  
    90137            static std::string getCommonBegin(const ArgumentCompletionList& list);
    91138
    92             const ConsoleCommand* execCommand_;
    93             const ConsoleCommand* hintCommand_;
    94             SubString tokens_;
    95             std::string string_;
    96             unsigned int execArgumentsOffset_;
    97             unsigned int hintArgumentsOffset_;
    98             bool bPossibleArgumentsRetrieved_;
    99             ArgumentCompletionList possibleArguments_;
     139            const ConsoleCommand* execCommand_;             ///< The command that will be executed (can be NULL if the command is not valid)
     140            const ConsoleCommand* hintCommand_;             ///< The command that is used to display hints and argument lists (can be different to execCommand_ in some cases)
     141            SubString tokens_;                              ///< The single words of the command string, split into tokens
     142            std::string string_;                            ///< The original command string, entered by the user in the shell
     143            unsigned int execArgumentsOffset_;              ///< The index of the first argument in tokens_ used to execute the command
     144            unsigned int hintArgumentsOffset_;              ///< The index of the first argument in tokens_ used to display hints and argument lists
     145            bool bPossibleArgumentsRetrieved_;              ///< True if the list of possible arguments was already retrieved
     146            ArgumentCompletionList possibleArguments_;      ///< List of possible arguments for the command in the current state
    100147
    101             bool bEvaluatedParams_;
    102             bool bTriedToEvaluatedParams_;
    103             unsigned int numberOfEvaluatedParams_;
    104             MultiType param_[MAX_FUNCTOR_ARGUMENTS];
     148            bool bEvaluatedArguments_;                      ///< True if the arguments of the command have been evaluated (and stored in arguments_)
     149            bool bTriedToEvaluatedArguments_;               ///< True if an attempt was started to evaluate the arguments (but not necessarily successful)
     150            unsigned int numberOfEvaluatedArguments_;       ///< The number of evaluated arguments (ranges from 0 to MAX_FUNCTOR_ARGUMENTS)
     151            MultiType arguments_[MAX_FUNCTOR_ARGUMENTS];    ///< The evaluated arguments (the arguments from string_ or tokens_ converted to the right type)
    105152    };
    106153}

  • code/trunk/src/libraries/core/command/CommandExecutor.cc

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of CommandExecutor
     32*/
     33
    2934#include "CommandExecutor.h"
    3035
    … …  
    4954        .argumentCompleter(1, autocompletion::command());
    5055
     56    /**
     57        @brief Returns a reference to the only instance of CommandExecutor.
     58    */
    5159    /* static */ CommandExecutor& CommandExecutor::getInstance()
    5260    {
    … …  
    5563    }
    5664
     65    /**
     66        @brief Executes a command.
     67        @param command A string containing the command
     68        @param useTcl If true, the command is passed to tcl (see TclBind)
     69        @return Returns the error-code (see @ref CommandExecutorErrorCodes "error codes")
     70    */
    5771    /* static */ int CommandExecutor::execute(const std::string& command, bool useTcl)
    5872    {
    … …  
    6276    }
    6377
     78    /**
     79        @brief Executes a command and returns its return-value.
     80        @param command A string containing the command
     81        @param error A pointer to a value (or NULL) where the error-code should be written to (see @ref CommandExecutorErrorCodes "error codes")
     82        @param useTcl If true, the command is passed to tcl (see TclBind)
     83        @return Returns the return-value of the command (if any - MT_Type::Null otherwise)
     84    */
    6485    /* static */ MultiType CommandExecutor::queryMT(const std::string& command, int* error, bool useTcl)
    6586    {
    6687        if (useTcl)
     88        {
     89            // pass the command to tcl
    6790            return TclBind::eval(command, error);
     91        }
    6892        else
    6993        {
    7094            CommandEvaluation evaluation;
     95
     96            // try to get the command evaluation from the cache
    7197            if (!CommandExecutor::getInstance().getCached(command, evaluation))
    7298            {
     99                // it wasn't in the cache - evaluate the command
    73100                evaluation = CommandExecutor::evaluate(command);
    74                 evaluation.evaluateParams();
     101
     102                // evaluate its arguments
     103                evaluation.evaluateArguments();
     104
     105                // write the evaluation to the cache
    75106                CommandExecutor::getInstance().cache(command, evaluation);
    76107            }
    77108
     109            // query the command and return its return-value
    78110            return evaluation.query(error);
    79111        }
    80112    }
    81113
     114    /**
     115        @brief Executes a command and returns its return-value as string.
     116        @param command A string containing the command
     117        @param error A pointer to a value (or NULL) where the error-code should be written to (see @ref CommandExecutorErrorCodes "error codes")
     118        @param useTcl If true, the command is passed to tcl (see TclBind)
     119        @return Returns the return-value of the command converted to a string (or "" if there's no return value)
     120    */
    82121    /* static */ std::string CommandExecutor::query(const std::string& command, int* error, bool useTcl)
    83122    {
    … …  
    85124    }
    86125
     126    /**
     127        @brief Evaluates the given command.
     128        @param command A string containing the command
     129        @return Returns an instance of CommandEvaluation, which contains the evaluated ConsoleCommand, if the command is valid.
     130
     131        Evaluates the given command string and returns an instance of CommandEvaluation.
     132        If the command is valid, this contains the evaluated ConsoleCommand. Otherwise it
     133        can still be used to print hints or complete the command.
     134
     135        @note Tcl commands can not be evaluated. You have to pass them to execute() or to
     136        TclBind directly.
     137    */
    87138    /* static */ CommandEvaluation CommandExecutor::evaluate(const std::string& command)
    88139    {
     140        // initialize the command evaluation
    89141        CommandEvaluation evaluation;
    90142        evaluation.initialize(command);
    91143
     144        // assign the fallback-command to get hints about the possible commands and groups
    92145        evaluation.hintCommand_ = ConsoleCommand::getCommand(__CC_CommandExecutor_name, __CC_autocomplete_name);
    93146
     147        // check if there's at least one argument
    94148        if (evaluation.getNumberOfArguments() >= 1)
    95149        {
     150            // try to get a command from the first token
    96151            evaluation.execCommand_ = ConsoleCommand::getCommandLC(evaluation.getToken(0));
    97152            if (evaluation.execCommand_)
    … …  
    99154            else if (evaluation.getNumberOfArguments() >= 2)
    100155            {
     156                // try to get a command from the first two tokens
    101157                evaluation.execCommand_ = ConsoleCommand::getCommandLC(evaluation.getToken(0), evaluation.getToken(1));
    102158                if (evaluation.execCommand_)
    … …  
    105161        }
    106162
     163        // if a valid command was found and the user is already entering arguments, overwrite hintCommand_ with execCommand_
    107164        if (evaluation.execCommand_ && evaluation.getNumberOfArguments() > evaluation.execArgumentsOffset_)
    108165        {
    … …  
    114171    }
    115172
     173    /**
     174        @brief Gets an evaluated command from the cache.
     175        @param command The command that should be looked up in the cache
     176        @param evaluation Reference to a CommandEvaluation that will be used to return the cached evaluation.
     177        @return Returns true if the command was found in the cache
     178    */
    116179    bool CommandExecutor::getCached(const std::string& command, CommandEvaluation& evaluation)
    117180    {
    … …  
    119182            return false;
    120183
     184        // check if the command is in the cache
    121185        std::map<std::string, CacheEntry>::iterator it = this->cache_.find(command);
    122186        if (it != this->cache_.end())
    … …  
    134198    }
    135199
     200    /**
     201        @brief Writes a command evaluation for a given command to the cache.
     202    */
    136203    void CommandExecutor::cache(const std::string& command, const CommandEvaluation& evaluation)
    137204    {
    … …  
    156223    }
    157224
     225    /**
     226        @brief This function is used as console command which executes commands that are usually hidden.
     227
     228        The argument completion function of this console commands is used to find
     229        and enter hidden commands and their arguments.
     230    */
    158231    /* static */ MultiType CommandExecutor::unhide(const std::string& command)
    159232    {
    … …  
    161234    }
    162235
     236    /**
     237        @brief This function is used as console command which saves a command and optionally also it's arguments as a new console command with a new name.
     238        @param alias The name of the new command alias
     239        @param command The existing command and (optionally) its arguments
     240    */
    163241    /* static */ void CommandExecutor::alias(const std::string& alias, const std::string& command)
    164242    {
     243        // first check if the given command is valid, else print an error
    165244        CommandEvaluation evaluation = CommandExecutor::evaluate(command);
    166245        if (evaluation.isValid())
    167246        {
     247            // it is valid - copy the executor of this command
    168248            ExecutorPtr executor = new Executor(*evaluation.getConsoleCommand()->getExecutor().get());
    169249
    170             if (!evaluation.evaluateParams())
     250            // evaluate the arguments and if this returns no error, store them as default values
     251            if (!evaluation.evaluateArguments())
    171252            {
    172253                for (size_t i = 0; i < MAX_FUNCTOR_ARGUMENTS; ++i)
    173                     executor->setDefaultValue(i, evaluation.getEvaluatedParameter(i));
    174             }
    175 
     254                    executor->setDefaultValue(i, evaluation.getEvaluatedArgument(i));
     255            }
     256
     257            // split the alias in tokens
    176258            SubString tokens(alias, " ");
    177259
     260            // check if the alias already exists - print an error and return if it does
    178261            if ((tokens.size() == 1 && ConsoleCommand::getCommand(tokens[0])) || (tokens.size() == 2 && ConsoleCommand::getCommand(tokens[0], tokens[1])))
    179262            {
    … …  
    182265            }
    183266
     267            // create a new console command with the given alias as its name
    184268            if (tokens.size() == 1)
    185269                createConsoleCommand(tokens[0], executor);

  • code/trunk/src/libraries/core/command/CommandExecutor.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command CommandExecEval
     32    @brief Declaration of the orxonox::CommandExecutor class which is used to execute and evaluate @ref orxonox::ConsoleCommand "console commands".
     33
     34    @anchor CommandExecutorExample
     35
     36    orxonox::CommandExecutor can be used to execute console commands (see orxonox::ConsoleCommand).
     37    Commands are strings that can be entered by the user in the shell or they can be part of a
     38    script.
     39
     40    A command can be passed to orxonox::CommandExecutor::execute() which will execute them - eiter
     41    directly, or - if requested - passes it to Tcl. See orxonox::TclBind for more information.
     42    Appart from execute() the command can also be passed to orxonox::CommandExecutor::query() which
     43    behaves the same except for that it returns the return value of the command.
     44
     45    If you don't want to execute the command, but rather gather more information about it, pass it
     46    to orxonox::CommandExecutor::evaluate(). This function returns an instance of
     47    orxonox::CommandEvaluation. This class provides more information about the command, for example
     48    the evaluated instance of orxonox::ConsoleCommand. Its also possible to gather hints about the
     49    command or to complete the command-string by using argument completion functions. More than that
     50    the command evaluation can also evaluate the arguments, which allows faster execution of the
     51    command.
     52
     53    Example:
     54    @code
     55    CommandExecutor::execute("log test");               // writes "test" to the console
     56    CommandExecutor::execute("log [expr 1+1]");         // writes "2" to the console - expr is a Tcl command
     57
     58    CommandExecutor::query("expr 1+1");                 // returns "2"
     59    CommandExecutor::queryMT("expr 1+1");               // returns 2
     60    @endcode
     61
     62    And another example about how to use evaluate():
     63    @code
     64    CommandEvaluation evaluation;
     65    evaluation = CommandExecutor::evaluate("log test"); // returns an evaluation of "log test"
     66
     67    evaluation.execute();                               // writes "test" to the console
     68    evaluation.hint();                                  // returns "log: {string}"
     69    @endcode
     70
     71    @anchor CommandExecutorErrorCodes
     72
     73    @b Error @b codes:
     74
     75    orxonox::CommandExecutor defines a number of error codes that are returned
     76    by different functions that operate with commands:
     77
     78     - CommandExecutor::Success: No error
     79     - CommandExecutor::Error: The command doesn't exist
     80     - CommandExecutor::Incomplete: The command needs more arguments
     81     - CommandExecutor::Deactivated: The command is not active
     82     - CommandExecutor::Denied: The command needs a different @ref orxonox::AccessLevel "access level"
     83*/
     84
    2985#ifndef _CommandExecutor_H__
    3086#define _CommandExecutor_H__
    … …  
    4298namespace orxonox
    4399{
     100    /**
     101        @brief This class is used to execute and evaluate command-strings.
     102
     103        CommandExecutor executes command-strings and returns evaluated commands. It's
     104        also possible to execute Tcl commands if the corresponding argument of execute()
     105        is true.
     106
     107        @see See @ref CommandExecutorExample "this description" for more information and some examples.
     108    */
    44109    class _CoreExport CommandExecutor
    45110    {
    … …  
    53118            static CommandEvaluation evaluate(const std::string& command);
    54119
    55             static const int Success = 0;
    56             static const int Error = 1;
    57             static const int Incomplete = 2;
    58             static const int Deactivated = 3;
    59             static const int Denied = 4;
     120            static const int Success = 0;       ///< Error code for "success" (or no error)
     121            static const int Error = 1;         ///< Error code if the command doesn't exist
     122            static const int Incomplete = 2;    ///< Error code if the command needs more arguments
     123            static const int Deactivated = 3;   ///< Error code if the command is not active
     124            static const int Denied = 4;        ///< Error code if the command needs a different access level
    60125
    61126            static MultiType unhide(const std::string& command);
    62127            static void alias(const std::string& alias, const std::string& command);
    63             static void _autocomplete(const std::string& group, const std::string& name) {}
     128            static void _autocomplete(const std::string& group, const std::string& name) {} ///< Pseudo console command used whenever no real command is available. In these cases this command provides auto-completion for console commands and groups.
    64129
    65130        private:
    66             CommandExecutor() {}
    67             CommandExecutor(const CommandExecutor& other);
    68             ~CommandExecutor() {}
     131            CommandExecutor() {}                            ///< Empty constructor
     132            CommandExecutor(const CommandExecutor& other);  ///< Not implemented copy-constructor
     133            ~CommandExecutor() {}                           ///< Empty destructor
    69134
    70135            static CommandExecutor& getInstance();
    … …  
    73138            void cache(const std::string& command, const CommandEvaluation& evaluation);
    74139
     140            /// Helper struct, used to store cached entries
    75141            struct CacheEntry
    76142            {
    77                 CommandEvaluation evaluation_;
    78                 std::list<std::string>::iterator iterator_;
     143                CommandEvaluation evaluation_;                  ///< The command evaluation which is stored in the cache
     144                std::list<std::string>::iterator iterator_;     ///< The iterator of the corresponding element in cachelist_, used for faster access
    79145            };
    80146
    81             std::map<std::string, CacheEntry> cache_;
    82             std::list<std::string> cachelist_;
     147            std::map<std::string, CacheEntry> cache_;   ///< A map that connects command strings and evaluated commands in the cache
     148            std::list<std::string> cachelist_;          ///< A list used to sort the elements in the cache by their age
    83149    }; // tolua_export
    84150} // tolua_export

  • code/trunk/src/libraries/core/command/ConsoleCommand.cc

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the ConsoleCommand class.
     32*/
     33
    2934#include "ConsoleCommand.h"
    3035
    … …  
    3641namespace orxonox
    3742{
     43    /**
     44        @brief Constructor: Initializes all values and registers the command.
     45        @param group The group of the command
     46        @param name The name of the command
     47        @param executor The executor of the command
     48        @param bInitialized If true, the executor is used for both, the definition of the function-header AND to executute the command. If false, the command is inactive and needs to be assigned a function before it can be used.
     49    */
    3850    ConsoleCommand::ConsoleCommand(const std::string& group, const std::string& name, const ExecutorPtr& executor, bool bInitialized)
    3951    {
    … …  
    4557        this->baseFunctor_ = executor->getFunctor();
    4658
    47         this->argumentCompleter_[0] = 0;
    48         this->argumentCompleter_[1] = 0;
    49         this->argumentCompleter_[2] = 0;
    50         this->argumentCompleter_[3] = 0;
    51         this->argumentCompleter_[4] = 0;
     59        for (size_t i = 0; i < MAX_FUNCTOR_ARGUMENTS; ++i)
     60            this->argumentCompleter_[i] = 0;
    5261
    5362        this->keybindMode_ = KeybindMode::OnPress;
    … …  
    6069    }
    6170
     71    /**
     72        @brief Destructor: Unregisters the command.
     73    */
    6274    ConsoleCommand::~ConsoleCommand()
    6375    {
    … …  
    6577    }
    6678
     79    /**
     80        @brief Registers the command with the same name, but without group, as shortcut.
     81    */
    6782    ConsoleCommand& ConsoleCommand::addShortcut()
    6883    {
    … …  
    7186    }
    7287
     88    /**
     89        @brief Registers the command with an alias as shortcut.
     90    */
    7391    ConsoleCommand& ConsoleCommand::addShortcut(const std::string&  name)
    7492    {
    … …  
    7795    }
    7896
     97    /**
     98        @brief Registers the command in a different group but with the same name.
     99    */
    79100    ConsoleCommand& ConsoleCommand::addGroup(const std::string& group)
    80101    {
    … …  
    83104    }
    84105
     106    /**
     107        @brief Registers an alias of the command in a different group with a different name.
     108    */
    85109    ConsoleCommand& ConsoleCommand::addGroup(const std::string& group, const std::string&  name)
    86110    {
    … …  
    89113    }
    90114
     115    /**
     116        @brief Returns true if the command can be executed right now.
     117
     118        This returns only true, if the following conditions are met:
     119         - The command is active
     120         - The command has an executor
     121         - The executor has a functor
     122         - The functor is static or has an object
     123    */
    91124    bool ConsoleCommand::isActive() const
    92125    {
    … …  
    94127    }
    95128
     129    /**
     130        @brief Returns true if the current state of the game matches the required access level.
     131    */
    96132    bool ConsoleCommand::hasAccess() const
    97133    {
    … …  
    101137            case AccessLevel::Standalone: return GameMode::isStandalone();
    102138            case AccessLevel::Master:     return GameMode::isMaster();
    103             case AccessLevel::Server:     return GameMode::hasServer();
     139            case AccessLevel::Server:     return GameMode::isServer();
    104140            case AccessLevel::Client:     return GameMode::isClient();
    105             case AccessLevel::Online:     return (GameMode::hasServer() || GameMode::isClient());
     141            case AccessLevel::Online:     return (GameMode::isServer() || GameMode::isClient());
    106142            case AccessLevel::Offline:    return GameMode::isStandalone();
    107143            case AccessLevel::None:       return false;
    … …  
    110146    }
    111147
     148    /**
     149        @brief Returns true if the headers of the given functor match the declaration of this command.
     150    */
    112151    bool ConsoleCommand::headersMatch(const FunctorPtr& functor)
    113152    {
     153        // get the minimum of the number of parameters of both commands
    114154        unsigned int minparams = std::min(this->baseFunctor_->getParamCount(), functor->getParamCount());
    115155
     156        // if the reduced headers don't match -> return false
    116157        if (this->baseFunctor_->getHeaderIdentifier(minparams) != functor->getHeaderIdentifier(minparams))
    117158            return false;
     159        // if the reduced headers match and the new functor has less or equal parameters -> return true
    118160        else if (functor->getParamCount() <= this->baseFunctor_->getParamCount())
    119161            return true;
     162        // the headers match but the new functor has more arguments and there is no executor with default-values -> return false
    120163        else if (!this->executor_)
    121164            return false;
     165        // the headers match but the new functor has more arguments, check if the executor has enough default-values
    122166        else
    123167        {
    … …  
    135179    }
    136180
     181    /**
     182        @brief Returns true if the headers of the given executor match the declaration of this command.
     183    */
    137184    bool ConsoleCommand::headersMatch(const ExecutorPtr& executor)
    138185    {
     186        // get the minimum of the number of parameters of both commands
    139187        unsigned int minparams = std::min(this->baseFunctor_->getParamCount(), executor->getParamCount());
    140188
     189        // if the reduced headers don't match -> return false
    141190        if (this->baseFunctor_->getHeaderIdentifier(minparams) != executor->getFunctor()->getHeaderIdentifier(minparams))
    142191            return false;
     192        // if the reduced headers match and the new functor has less or equal parameters -> return true
    143193        else if (executor->getParamCount() <= this->baseFunctor_->getParamCount())
    144194            return true;
     195        // the headers match but the new functor has more arguments, check if the new executor has enough default-values
    145196        else
    146197        {
    … …  
    158209    }
    159210
     211    /**
     212        @brief Changes the executor.
     213        @param executor The new executor
     214        @param bForce If true, the executor is always assigned, even if the headers don't match
     215        @return Returns true if the assignment was successful
     216    */
    160217    bool ConsoleCommand::setFunction(const ExecutorPtr& executor, bool bForce)
    161218    {
     219        // assign the executor if a) it's a null-pointer, b) its functor is a null-pointer, c) it's forced, d) the headers match
    162220        if (!executor || !executor->getFunctor() || bForce || this->headersMatch(executor))
    163221        {
     222            // assign the executor and clear the object stack (because it's also a new function)
    164223            this->executor_ = executor;
    165224            this->objectStack_.clear();
    … …  
    173232    }
    174233
     234    /**
     235        @brief Changes the functor of the current executor.
     236        @param functor The new functor
     237        @param bForce If true, the functor is always assigned, even if the headers don't match
     238        @return Returns true if the assignment was successful
     239    */
    175240    bool ConsoleCommand::setFunction(const FunctorPtr& functor, bool bForce)
    176241    {
     242        // assign the functor if a) it's a null-pointer, b) it's forced, c) the headers match
    177243        if (!functor || bForce || this->headersMatch(functor))
    178244        {
     245            // assign the functor (create a new executor if necessary) and clear the object stack
    179246            if (this->executor_)
    180247                this->executor_->setFunctor(functor);
    … …  
    192259    }
    193260
     261    /**
     262        @brief Pushes a new executor to the command-stack.
     263        @param executor The new executor
     264        @param bForce If true, the executor is always assigned, even if the headers don't match
     265    */
    194266    void ConsoleCommand::pushFunction(const ExecutorPtr& executor, bool bForce)
    195267    {
     268        // prepare the old function to be put on the stack
    196269        Command command;
    197270        command.executor_ = this->executor_;
    … …  
    200273        command.objectStack_ = this->objectStack_;
    201274
     275        // check if the new executor can be assigned and push the old function to the stack
    202276        if (this->setFunction(executor, bForce))
    203277            this->commandStack_.push(command);
    204278    }
    205279
     280    /**
     281        @brief Pushes a new functor to the command-stack.
     282        @param functor The new functor
     283        @param bForce If true, the functor is always assigned, even if the headers don't match
     284    */
    206285    void ConsoleCommand::pushFunction(const FunctorPtr& functor, bool bForce)
    207286    {
     287        // prepare the old function to be put on the stack
    208288        Command command;
    209289        command.executor_ = this->executor_;
    … …  
    212292        command.objectStack_ = this->objectStack_;
    213293
     294        // check if the new functor can be assigned and push the old function to the stack
    214295        if (this->setFunction(functor, bForce))
    215296            this->commandStack_.push(command);
    216297    }
    217298
     299    /**
     300        @brief Pushes a copy of the current executor and functor on the stack.
     301    */
    218302    void ConsoleCommand::pushFunction()
    219303    {
    … …  
    224308    }
    225309
     310    /**
     311        @brief Removes the current function from the stack and restores the old state.
     312    */
    226313    void ConsoleCommand::popFunction()
    227314    {
    228315        Command command;
     316
     317        // check if there's a function on the stack
    229318        if (!this->commandStack_.empty())
    230319        {
     320            // yes it is - assign it to command and remove it from the stack
    231321            command = this->commandStack_.top();
    232322            this->commandStack_.pop();
    233323        }
    234324
     325        // restore the old executor (and also restore its functor in case this was changed in the meantime)
    235326        this->executor_ = command.executor_;
    236327        if (command.executor_)
    … …  
    239330    }
    240331
     332    /**
     333        @brief Sets the functor to NULL (which also deactivates the command).
     334    */
    241335    void ConsoleCommand::resetFunction()
    242336    {
    … …  
    246340    }
    247341
     342    /**
     343        @brief Returns the current executor which can be used to execute the command.
     344    */
    248345    const ExecutorPtr& ConsoleCommand::getExecutor() const
    249346    {
    … …  
    251348    }
    252349
     350    /**
     351        @brief Changes the current object that is used to execute member-functions.
     352        @return Returns true if the object was successfully changed
     353    */
    253354    bool ConsoleCommand::setObject(void* object)
    254355    {
    255         if (this->executor_)
    256         {
     356        // check if there's an executor
     357        if (this->executor_)
     358        {
     359            // check if there's a functor
    257360            if (this->executor_->getFunctor())
    258361            {
     362                // change the object
    259363                this->executor_->getFunctor()->setRawObjectPointer(object);
    260364                return true;
    … …  
    269373    }
    270374
     375    /**
     376        @brief Push a new object to the object-stack.
     377    */
    271378    void ConsoleCommand::pushObject(void* object)
    272379    {
    … …  
    276383    }
    277384
     385    /**
     386        @brief Removes the current object from the stack an restores the old object.
     387    */
    278388    void ConsoleCommand::popObject()
    279389    {
    … …  
    287397    }
    288398
     399    /**
     400        @brief Returns the current object pointer that is used to execute member-functions.
     401    */
    289402    void* ConsoleCommand::getObject() const
    290403    {
    … …  
    295408    }
    296409
    297     ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& param1)
    298     {
    299         if (this->executor_)
    300             this->executor_->setDefaultValues(param1);
     410    /**
     411        @brief Changes the default values of the current executor.
     412    */
     413    ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& arg1)
     414    {
     415        if (this->executor_)
     416            this->executor_->setDefaultValues(arg1);
    301417        else
    302418            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    305421    }
    306422
    307     ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& param1, const MultiType& param2)
    308     {
    309         if (this->executor_)
    310             this->executor_->setDefaultValues(param1, param2);
     423    /**
     424        @brief Changes the default values of the current executor.
     425    */
     426    ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& arg1, const MultiType& arg2)
     427    {
     428        if (this->executor_)
     429            this->executor_->setDefaultValues(arg1, arg2);
    311430        else
    312431            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    315434    }
    316435
    317     ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3)
    318     {
    319         if (this->executor_)
    320             this->executor_->setDefaultValues(param1, param2, param3);
     436    /**
     437        @brief Changes the default values of the current executor.
     438    */
     439    ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3)
     440    {
     441        if (this->executor_)
     442            this->executor_->setDefaultValues(arg1, arg2, arg3);
    321443        else
    322444            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    325447    }
    326448
    327     ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4)
    328     {
    329         if (this->executor_)
    330             this->executor_->setDefaultValues(param1, param2, param3, param4);
     449    /**
     450        @brief Changes the default values of the current executor.
     451    */
     452    ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4)
     453    {
     454        if (this->executor_)
     455            this->executor_->setDefaultValues(arg1, arg2, arg3, arg4);
    331456        else
    332457            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    335460    }
    336461
    337     ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5)
    338     {
    339         if (this->executor_)
    340             this->executor_->setDefaultValues(param1, param2, param3, param4, param5);
     462    /**
     463        @brief Changes the default values of the current executor.
     464    */
     465    ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5)
     466    {
     467        if (this->executor_)
     468            this->executor_->setDefaultValues(arg1, arg2, arg3, arg4, arg5);
    341469        else
    342470            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    345473    }
    346474
    347     ConsoleCommand& ConsoleCommand::defaultValue(unsigned int index, const MultiType& param)
    348     {
    349         if (this->executor_)
    350             this->executor_->setDefaultValue(index, param);
     475    /**
     476        @brief Changes the default value of the argument with given index of the current executor.
     477        @param index The index of the argument (the first argument has index 0)
     478        @param arg The new default value
     479    */
     480    ConsoleCommand& ConsoleCommand::defaultValue(unsigned int index, const MultiType& arg)
     481    {
     482        if (this->executor_)
     483            this->executor_->setDefaultValue(index, arg);
    351484        else
    352485            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    355488    }
    356489
    357     ConsoleCommand& ConsoleCommand::argumentCompleter(unsigned int param, ArgumentCompleter* completer)
    358     {
    359         if (param < 5)
    360             this->argumentCompleter_[param] = completer;
    361         else
    362             COUT(2) << "Warning: Couldn't add autocompletion-function for param " << param << " in console command \"" << this->baseName_ << "\": index out of bound." << std::endl;
    363 
    364         return *this;
    365     }
    366 
    367     ArgumentCompleter* ConsoleCommand::getArgumentCompleter(unsigned int param) const
    368     {
    369         if (param < 5)
    370             return this->argumentCompleter_[param];
     490    /**
     491        @brief Changes the argument completer for the given argument.
     492        @param index The index of the argument (the first argument has index 0)
     493        @param completer The new argument completer
     494    */
     495    ConsoleCommand& ConsoleCommand::argumentCompleter(unsigned int index, ArgumentCompleter* completer)
     496    {
     497        if (index < 5)
     498            this->argumentCompleter_[index] = completer;
     499        else
     500            COUT(2) << "Warning: Couldn't add autocompletion-function for index " << index << " in console command \"" << this->baseName_ << "\": index out of bound." << std::endl;
     501
     502        return *this;
     503    }
     504
     505    /**
     506        @brief Returns the argument completer for the argument with given index.
     507    */
     508    ArgumentCompleter* ConsoleCommand::getArgumentCompleter(unsigned int index) const
     509    {
     510        if (index < 5)
     511            return this->argumentCompleter_[index];
    371512        else
    372513            return 0;
    373514    }
    374515
     516    /**
     517        @brief Sets the description of this command.
     518    */
    375519    ConsoleCommand& ConsoleCommand::description(const std::string& description)
    376520    {
    … …  
    380524    }
    381525
     526    /**
     527        @brief Returns the description of this command.
     528    */
    382529    const std::string& ConsoleCommand::getDescription() const
    383530    {
    … …  
    385532    }
    386533
    387     ConsoleCommand& ConsoleCommand::descriptionParam(unsigned int param, const std::string& description)
    388     {
    389         if (param < MAX_FUNCTOR_ARGUMENTS)
    390         {
    391             this->descriptionParam_[param] = std::string("ConsoleCommandDescription::" + this->baseName_ + "::param" + multi_cast<std::string>(param));
    392             AddLanguageEntry(this->descriptionParam_[param], description);
    393         }
    394         return *this;
    395     }
    396 
    397     const std::string& ConsoleCommand::getDescriptionParam(unsigned int param) const
    398     {
    399         if (param < MAX_FUNCTOR_ARGUMENTS)
    400             return GetLocalisation_noerror(this->descriptionParam_[param]);
     534    /**
     535        @brief Sets the description for an argument with given index.
     536    */
     537    ConsoleCommand& ConsoleCommand::descriptionParam(unsigned int index, const std::string& description)
     538    {
     539        if (index < MAX_FUNCTOR_ARGUMENTS)
     540        {
     541            this->descriptionParam_[index] = std::string("ConsoleCommandDescription::" + this->baseName_ + "::param" + multi_cast<std::string>(index));
     542            AddLanguageEntry(this->descriptionParam_[index], description);
     543        }
     544        return *this;
     545    }
     546
     547    /**
     548        @brief Returns the description for the argument with given index.
     549    */
     550    const std::string& ConsoleCommand::getDescriptionParam(unsigned int index) const
     551    {
     552        if (index < MAX_FUNCTOR_ARGUMENTS)
     553            return GetLocalisation_noerror(this->descriptionParam_[index]);
    401554
    402555        return this->descriptionParam_[0];
    403556    }
    404557
     558    /**
     559        @brief Sets the description for the return-value.
     560    */
    405561    ConsoleCommand& ConsoleCommand::descriptionReturnvalue(const std::string& description)
    406562    {
    … …  
    410566    }
    411567
    412     const std::string& ConsoleCommand::getDescriptionReturnvalue(int param) const
     568    /**
     569        @brief Returns the description for the return-value.
     570    */
     571    const std::string& ConsoleCommand::getDescriptionReturnvalue(int index) const
    413572    {
    414573        return GetLocalisation_noerror(this->descriptionReturnvalue_);
    415574    }
    416575
     576    /**
     577        @brief Returns the command with given group an name.
     578        @param group The group of the requested command
     579        @param name The group of the requested command
     580        @param bPrintError If true, an error is printed if the command doesn't exist
     581    */
    417582    /* static */ const ConsoleCommand* ConsoleCommand::getCommand(const std::string& group, const std::string& name, bool bPrintError)
    418583    {
     584        // find the group
    419585        std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = ConsoleCommand::getCommandMap().find(group);
    420586        if (it_group != ConsoleCommand::getCommandMap().end())
    421587        {
     588            // find the name
    422589            std::map<std::string, ConsoleCommand*>::const_iterator it_name = it_group->second.find(name);
    423590            if (it_name != it_group->second.end())
    424591            {
     592                // return the pointer
    425593                return it_name->second;
    426594            }
    … …  
    436604    }
    437605
     606    /**
     607        @brief Returns the command with given group an name in lowercase.
     608        @param group The group of the requested command in lowercase
     609        @param name The group of the requested command in lowercase
     610        @param bPrintError If true, an error is printed if the command doesn't exist
     611    */
    438612    /* static */ const ConsoleCommand* ConsoleCommand::getCommandLC(const std::string& group, const std::string& name, bool bPrintError)
    439613    {
    … …  
    441615        std::string nameLC = getLowercase(name);
    442616
     617        // find the group
    443618        std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = ConsoleCommand::getCommandMapLC().find(groupLC);
    444619        if (it_group != ConsoleCommand::getCommandMapLC().end())
    445620        {
     621            // find the name
    446622            std::map<std::string, ConsoleCommand*>::const_iterator it_name = it_group->second.find(nameLC);
    447623            if (it_name != it_group->second.end())
    448624            {
     625                // return the pointer
    449626                return it_name->second;
    450627            }
    … …  
    460637    }
    461638
     639    /**
     640        @brief Returns the static map that stores all console commands.
     641    */
    462642    /* static */ std::map<std::string, std::map<std::string, ConsoleCommand*> >& ConsoleCommand::getCommandMap()
    463643    {
    … …  
    466646    }
    467647
     648    /**
     649        @brief Returns the static map that stores all console commands in lowercase.
     650    */
    468651    /* static */ std::map<std::string, std::map<std::string, ConsoleCommand*> >& ConsoleCommand::getCommandMapLC()
    469652    {
    … …  
    472655    }
    473656
     657    /**
     658        @brief Registers a new command with given group an name by adding it to the command map.
     659    */
    474660    /* static */ void ConsoleCommand::registerCommand(const std::string& group, const std::string& name, ConsoleCommand* command)
    475661    {
    … …  
    477663            return;
    478664
     665        // check if a command with this name already exists
    479666        if (ConsoleCommand::getCommand(group, name) != 0)
    480667        {
    … …  
    486673        else
    487674        {
     675            // add the command to the map
    488676            ConsoleCommand::getCommandMap()[group][name] = command;
    489677            ConsoleCommand::getCommandMapLC()[getLowercase(group)][getLowercase(name)] = command;
    … …  
    491679    }
    492680
     681    /**
     682        @brief Removes the command from the command map.
     683    */
    493684    /* static */ void ConsoleCommand::unregisterCommand(ConsoleCommand* command)
    494685    {
     686        // iterate through all groups
    495687        for (std::map<std::string, std::map<std::string, ConsoleCommand*> >::iterator it_group = ConsoleCommand::getCommandMap().begin(); it_group != ConsoleCommand::getCommandMap().end(); )
    496688        {
     689            // iterate through all commands of each group
    497690            for (std::map<std::string, ConsoleCommand*>::iterator it_name = it_group->second.begin(); it_name != it_group->second.end(); )
    498691            {
     692                // erase the command
    499693                if (it_name->second == command)
    500694                    it_group->second.erase(it_name++);
    … …  
    503697            }
    504698
     699            // erase the group if it is empty now
    505700            if (it_group->second.empty())
    506701                ConsoleCommand::getCommandMap().erase(it_group++);
    … …  
    509704        }
    510705
     706        // now the same for the lowercase-map:
     707
     708        // iterate through all groups
    511709        for (std::map<std::string, std::map<std::string, ConsoleCommand*> >::iterator it_group = ConsoleCommand::getCommandMapLC().begin(); it_group != ConsoleCommand::getCommandMapLC().end(); )
    512710        {
     711            // iterate through all commands of each group
    513712            for (std::map<std::string, ConsoleCommand*>::iterator it_name = it_group->second.begin(); it_name != it_group->second.end(); )
    514713            {
     714                // erase the command
    515715                if (it_name->second == command)
    516716                    it_group->second.erase(it_name++);
    … …  
    519719            }
    520720
     721            // erase the group if it is empty now
    521722            if (it_group->second.empty())
    522723                ConsoleCommand::getCommandMapLC().erase(it_group++);
    … …  
    526727    }
    527728
     729    /**
     730        @brief Deletes all commands
     731    */
    528732    /* static */ void ConsoleCommand::destroyAll()
    529733    {
     734        // delete entries until the map is empty
    530735        while (!ConsoleCommand::getCommandMap().empty() && !ConsoleCommand::getCommandMap().begin()->second.empty())
    531736            delete ConsoleCommand::getCommandMap().begin()->second.begin()->second;

  • code/trunk/src/libraries/core/command/ConsoleCommand.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @defgroup ConsoleCommand Console commands
     31    @ingroup Command
     32*/
     33
     34/**
     35    @file
     36    @ingroup Command ConsoleCommand
     37    @brief Declaration of the orxonox::ConsoleCommand class and the SetConsoleCommand() macro.
     38
     39    @anchor ConsoleCommandExample
     40
     41    Console commands can be used to write scripts, use key-bindings or simply to be
     42    entered into the shell by the user. Instances of orxonox::ConsoleCommand define
     43    the function of a command, and also more information like, for example, if it is
     44    active, default values, and possible arguments.
     45
     46    Commands need to be registered to the system statically on startup by using the
     47    SetConsoleCommand() or DeclareConsoleCommand() macros outside of a function.
     48    This ensures that commands are known to the system at any time, so they can be
     49    evaluated (see orxonox::CommandExecutor::evaluate()), for example for key-bindings.
     50
     51    Example:
     52    @code
     53    void myCoutFunction(const std::string& text)        // Define a static function
     54    {
     55        COUT(0) << "Text: " << text << std::endl;       // Print the text to the console
     56    }
     57
     58    SetConsoleCommand("cout", &myCoutFunction);         // Register the function as command with name "cout"
     59    @endcode
     60
     61    Now you can open the shell and execute the command:
     62    @code
     63    $ cout Hello World
     64    @endcode
     65
     66    Internally this command is now passed to orxonox::CommandExecutor::execute():
     67    @code
     68    CommandExecutor::execute("cout HelloWorld");
     69    @endcode
     70
     71    CommandExecutor searches for a command with name "cout" and passes the arguments
     72    "Hello World" to it. Because we registered myCoutFunction() with this command,
     73    as a result the following text will be printed to the console:
     74    @code
     75    Text: Hello World
     76    @endcode
     77
     78    You can add more attributes to the ConsoleCommand, by using the command-chain feature
     79    of SetConsoleCommand(). For example like this:
     80    @code
     81    SetConsoleCommand("cout", &myCoutFunction)
     82        .addGroup("output", "text")
     83        .accessLevel(AccessLevel::Offline)
     84        .defaultValues("no text");
     85    @endcode
     86
     87    Open the shell again and try it:
     88    @code
     89    $ cout Hello World
     90    Text: Hello World
     91    $ output text Hello World
     92    Text: Hello World
     93    $ cout
     94    Text: no text
     95    @endcode
     96
     97    If you execute it online (note: the access level is "Offline"), you will see the
     98    following (or something similar):
     99    @code
     100    $ cout Hello World
     101    Error: Can't execute command "cout", access denied.
     102    @endcode
     103
     104    If a command is executed, the arguments are passed to an underlying function,
     105    whitch is wrapped by an orxonox::Functor which again is wrapped by an orxonox::Executor.
     106    The Functor contains the function-pointer, as well as the object-pointer in
     107    case of a non-static member-function. The executor stores possible default-values
     108    for each argument of the function.
     109
     110    The function of a command can be changed at any time. It's possible to just exchange
     111    the function-pointer of the underlying Functor if the headers of the functions are
     112    exactly the same. But you can also exchange the Functor itself or even completely
     113    replace the Executor. Also the other attributes of a ConsoleCommand can be modified
     114    during the game, for example it can be activated or deactivated.
     115
     116    To do so, the function ModifyConsoleCommand() has to be used. It returns an instance
     117    of orxonox::ConsoleCommand::ConsoleCommandManipulator which has an interface similar to
     118    orxonox::ConsoleCommand, but with slight differences. You can use it the same way like
     119    SetConsoleCommand(), meaning you can use command-chains to change different attributes at
     120    the same time. ModifyConsoleCommand() must not be executed statically, but rather in a
     121    function at some point of the execution of the program.
     122
     123    Example:
     124    @code
     125    void myOtherCoutFunction(const std::string& text)                       // Define a new static function
     126    {
     127        COUT(0) << "Uppercase: " << getUppercase(text) << std::endl;        // Print the text in uppercase to the console
     128    }
     129
     130    {
     131        // ...                                                              // somewhere in the code
     132
     133        ModifyConsoleCommand("cout").setFunction(&myOtherCoutFunction);     // Modify the underlying function of the command
     134
     135        // ...
     136    }
     137    @endcode
     138
     139    If you now enter the command into the shell, you'll see a different behavior:
     140    @code
     141    $ cout Hello World
     142    Uppercase: HELLO WORLD
     143    $ cout
     144    Uppercase: NO TEXT
     145    @endcode
     146
     147    A few important notes about changing functions:
     148
     149    Instead of changing the function with setFunction(), you can also create a command-stack
     150    by using pushFunction() and popFunction(). It's important to note a few things about that,
     151    because the underlying structure of Executor and Functor has a few pitfalls:
     152     - If you push a new function-pointer, the same executor as before will be used (and, if
     153       the headers match, even the same functor can be used, which is very fast)
     154     - If you push a new Functor, the same executor as before will be used
     155     - If you push a new Executor, everything is changed
     156
     157    Note that the executor contains the @b default @b values, so if you just exchange the
     158    Functor, the default values remain the same. However if you decide to change the default
     159    values at any point of the stack, <b>this will also change the default values on all
     160    other stack-levels</b> that share the same executor. If you don't like this behavior,
     161    you have to explicitly push a new executor before changing the default values, either by
     162    calling pushFunction(executor) or by calling pushFunction(void) which pushes a copy of
     163    the current executor to the stack.
     164
     165    Another important point are object pointers in case of non-static member-functions.
     166    Whenever you set or push a new function, <b>you must add the object pointer again</b>
     167    because objects are stored in the Functor which is usually exchanged if you change
     168    the function.
     169
     170    You can also use a stack for objects, but note that this <b>object-stack is different for each
     171    function</b> - so if you set a new function, the object-stack will be cleared. If you push
     172    a new function, the old object-stack is stored in the stack, so it can be restored if
     173    you pop the function.
     174
     175    %DeclareConsoleCommand():
     176
     177    Appart from SetConsoleCommand() you can also call DeclareConsoleCommand(). In contrast
     178    to SetConsoleCommand(), this doesn't assign a function to the command. Indeed you have
     179    to pass a function-pointer to DeclareConsoleCommand(), but it is only used to determine
     180    the header of the future command-function. This allows to declare a command statically,
     181    thus it's possible to evaluate key-bindings of this command, but the actual function
     182    can be assigned at a later point.
     183
     184    Example:
     185    @code
     186    DeclareConsoleCommand("cout", &prototype::void__string);
     187    @endcode
     188
     189    If you try to execute the command now, you see the following (or something similar):
     190    @code
     191    $ cout Hello World
     192    Error: Can't execute command "cout", command is not active.
     193    @endcode
     194
     195    You first have to assign a function to use the command:
     196    @code
     197    {
     198        // ...
     199
     200        ModifyConsoleCommand("cout").setFunction(&myCoutFunction);
     201
     202        // ...
     203    }
     204    @endcode
     205
     206    Now you can use it:
     207    @code
     208    $ cout Hello World
     209    Text: Hello World
     210    @endcode
     211
     212    Note that the initial function prototype::void__string is defined in the namespace
     213    orxonox::prototype. If there's no function with the desired header, you can extend
     214    the collection of functions or simply use another function that has the same header.
     215*/
     216
    29217#ifndef _ConsoleCommand_H__
    30218#define _ConsoleCommand_H__
    … …  
    42230
    43231
     232/**
     233    @brief Defines a console command. The macro is overloaded for 2-4 parameters.
     234
     235    This is an overloaded macro. Depending on the number of arguments a different
     236    overloaded implementation of the macro will be chosen.
     237
     238    Console commands created with SetConsoleCommand() become active immediately and
     239    the given function-pointer (and optionally the object) will be used to execute
     240    the command.
     241*/
    44242#define SetConsoleCommand(...) \
    45243    BOOST_PP_EXPAND(BOOST_PP_CAT(SetConsoleCommand, ORXONOX_VA_NARGS(__VA_ARGS__))(__VA_ARGS__))
     244/**
     245    @brief This macro is executed if you call SetConsoleCommand() with 2 arguments.
     246    @param name The name (string) of the console command
     247    @param functionpointer The function-pointer of the corresponding command-function
     248*/
    46249#define SetConsoleCommand2(name, functionpointer) \
    47250    SetConsoleCommandGeneric("", name, orxonox::createFunctor(functionpointer))
     251/**
     252    @brief This macro is executed if you call SetConsoleCommand() with 3 arguments.
     253    @param group The group (string) of the console command
     254    @param name The name (string) of the console command
     255    @param functionpointer The function-pointer of the corresponding command-function
     256*/
    48257#define SetConsoleCommand3(group, name, functionpointer) \
    49258    SetConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer))
     259/**
     260    @brief This macro is executed if you call SetConsoleCommand() with 4 arguments.
     261    @param group The group (string) of the console command
     262    @param name The name (string) of the console command
     263    @param functionpointer The function-pointer of the corresponding command-function
     264    @param object The object that will be assigned to the command. Used for member-functions.
     265*/
    50266#define SetConsoleCommand4(group, name, functionpointer, object) \
    51267    SetConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer, object))
    52268
     269/// Internal macro
    53270#define SetConsoleCommandGeneric(group, name, functor) \
    54271    static orxonox::ConsoleCommand& BOOST_PP_CAT(__consolecommand_, __LINE__) = (*orxonox::createConsoleCommand(group, name, orxonox::createExecutor(functor)))
    55272
    56273
     274/**
     275    @brief Declares a console command. The macro is overloaded for 2-3 parameters.
     276
     277    This is an overloaded macro. Depending on the number of arguments a different
     278    overloaded implementation of the macro will be chosen.
     279
     280    Console commands created with DeclareConsoleCommand() don't use the the given
     281    function-pointer to execute the command, it is only used to define the header
     282    of the future command-function. The command is inactive until you manually
     283    set a function with orxonox::ModifyConsoleCommand(). You can use a different
     284    function-pointer than in the final command, as long as it has the same header.
     285*/
    57286#define DeclareConsoleCommand(...) \
    58287    BOOST_PP_EXPAND(BOOST_PP_CAT(DeclareConsoleCommand, ORXONOX_VA_NARGS(__VA_ARGS__))(__VA_ARGS__))
     288/**
     289    @brief This macro is executed if you call DeclareConsoleCommand() with 2 arguments.
     290    @param name The name (string) of the console command
     291    @param functionpointer The function-pointer of an arbitrary function that has the same header as the final function
     292*/
    59293#define DeclareConsoleCommand2(name, functionpointer) \
    60294    DeclareConsoleCommandGeneric("", name, orxonox::createFunctor(functionpointer))
     295/**
     296    @brief This macro is executed if you call DeclareConsoleCommand() with 3 arguments.
     297    @param group The group (string) of the console command
     298    @param name The name (string) of the console command
     299    @param functionpointer The function-pointer of an arbitrary function that has the same header as the final function
     300*/
    61301#define DeclareConsoleCommand3(group, name, functionpointer) \
    62302    DeclareConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer))
    63 #define DeclareConsoleCommand4(group, name, functionpointer, object) \
    64     DeclareConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer, object))
    65 
     303
     304/// Internal macro
    66305#define DeclareConsoleCommandGeneric(group, name, functor) \
    67306    static orxonox::ConsoleCommand& BOOST_PP_CAT(__consolecommand_, __LINE__) = (*orxonox::createConsoleCommand(group, name, orxonox::createExecutor(functor), false))
    … …  
    70309namespace orxonox
    71310{
     311    /**
     312        @brief A small collection of functions that can be used in DeclareConsoleCommand() if
     313        you don't want to use the real function-pointer.
     314    */
    72315    namespace prototype
    73316    {
    … …  
    78321    namespace AccessLevel
    79322    {
     323        /**
     324            @brief Possible access levels: A command can only be executed if the program is in the state which is requested by the access level.
     325        */
    80326        enum Enum
    81327        {
    … …  
    91337    }
    92338
     339    /**
     340        @brief The ConsoleCommand class stores all information about a console command which can be executed by CommandExecutor.
     341
     342        Console commands can be entered by the user into the shell, called in scripts, or
     343        used for key-bindings. They are simple text strings that can be executed by
     344        CommandExecutor. CommandExecutor will search for a ConsoleCommand with the given
     345        group and name and will execute it's Executor (which again calls the Functor and
     346        this finally calls the command-function).
     347
     348        @see See @ref ConsoleCommandExample "ConsoleCommand.h" for more information and some examples.
     349    */
    93350    class _CoreExport ConsoleCommand
    94351    {
    95352        friend struct ConsoleCommandManipulator;
    96353
     354        /**
     355            @brief Helper class that is used to put the current state of the ConsoleCommand on a stack.
     356        */
    97357        struct Command
    98358        {
    99             ExecutorPtr executor_;
    100             FunctorPtr functor_;
    101             std::vector<void*> objectStack_;
     359            ExecutorPtr executor_;              ///< The executor
     360            FunctorPtr functor_;                ///< The function that is used with the executor - has to be stored separatley because the executor is often used with different functors
     361            std::vector<void*> objectStack_;    ///< The object stack
    102362        };
    103363
    104364        public:
     365            /**
     366                @brief Helper class that is used to manipulate console commands.
     367
     368                An instance of this class is returned if you call the ModifyConsoleCommand macro.
     369                This class provides an interface which wraps some functions of ConsoleCommand. It
     370                allows access to some private functions like setFunction() (that can't be called
     371                right after SetConsoleCommand()) but it also hides some functions that shouln't be
     372                called after the static declaration like addShortcut() or description().
     373
     374                @see See @ref ConsoleCommandExample "ConsoleCommand.h" for more information and examples.
     375            */
    105376            struct ConsoleCommandManipulator
    106377            {
    107378                public:
     379                    /// Constructor: Creates a manipulator for a given ConsoleCommand.
    108380                    ConsoleCommandManipulator(const ConsoleCommand* command) : command_(const_cast<ConsoleCommand*>(command)) {}
    109381
     382                    /// Changes the current function of the command. @param function The new function-pointer @param bForce If true, the new function-pointer is always assigned, even if the headers don't match
    110383                    template <class F>
    111384                    inline ConsoleCommandManipulator& setFunction(F function, bool bForce = false)
    … …  
    113386                            if (this->command_)
    114387                            {
     388                                // check if the headers match. If they do, only change the function-pointer of the current Functor instead of creating a new Functor
    115389                                if (this->command_->getExecutor() && this->command_->getExecutor()->getFunctor() && this->command_->getExecutor()->getFunctor()->getFullIdentifier() == typeid(F))
    116390                                {
    … …  
    123397                            return *this;
    124398                        }
     399                    /// Changes the current function of the command. @param function The new function-pointer @param object The new object-pointer (for member-functions) @param bForce If true, the new function-pointer is always assigned, even if the headers don't match
    125400                    template <class F, class O>
    126401                    inline ConsoleCommandManipulator& setFunction(F function, O* object, bool bForce = false)
    … …  
    128403                            if (this->command_)
    129404                            {
     405                                // check if the headers match. If they do, only change the function-pointer of the current Functor instead of creating a new Functor
    130406                                if (this->command_->getExecutor() && this->command_->getExecutor()->getFunctor() && this->command_->getExecutor()->getFunctor()->getFullIdentifier() == typeid(F))
    131407                                {
    … …  
    139415                            return *this;
    140416                        }
     417                    /// Changes the current Functor of the command. @param functor The new Functor @param bForce If true, the new Functor is always assigned, even if the headers don't match
    141418                    inline ConsoleCommandManipulator& setFunction(const FunctorPtr& functor, bool bForce = false)
    142419                        { if (this->command_) { this->command_->setFunction(functor, bForce); } return *this; }
     420                    /// Changes the current Executor of the command. @param executor The new Executor @param bForce If true, the new Executor is always assigned, even if the headers don't match
    143421                    inline ConsoleCommandManipulator& setFunction(const ExecutorPtr& executor, bool bForce = false)
    144422                        { if (this->command_) { this->command_->setFunction(executor, bForce); } return *this; }
    145423
     424                    /// Pushes a copy of the current Executor on the command-stack, that can be altered without changing the old Executor. @details This function is especially useful if you don't wan't to change the function, but only the default values of the executor.
    146425                    inline ConsoleCommandManipulator& pushFunction()
    147426                        { if (this->command_) { this->command_->pushFunction(); } return *this; }
     427                    /// Pushes a new function on the command-stack. @param function The new function-pointer @param bForce If true, the new function-pointer is always assigned, even if the headers don't match
    148428                    template <class F>
    149429                    inline ConsoleCommandManipulator& pushFunction(F function, bool bForce = false)
    150430                        { if (this->command_) { this->command_->pushFunction(createFunctor(function), bForce); } return *this; }
     431                    /// Pushes a new function on the command-stack. @param function The new function-pointer @param object The new object-pointer (for member-functions) @param bForce If true, the new function-pointer is always assigned, even if the headers don't match
    151432                    template <class F, class O>
    152433                    inline ConsoleCommandManipulator& pushFunction(F function, O* object, bool bForce = false)
    153434                        { if (this->command_) { this->command_->pushFunction(createFunctor(function, object), bForce); } return *this; }
     435                    /// Pushes a new Functor on the command-stack. @param functor The new Functor @param bForce If true, the new Functor is always assigned, even if the headers don't match
    154436                    inline ConsoleCommandManipulator& pushFunction(const FunctorPtr& functor, bool bForce = false)
    155437                        { if (this->command_) { this->command_->pushFunction(functor, bForce); } return *this; }
     438                    /// Pushes a new Executor on the command-stack. @param executor The new Executor @param bForce If true, the new Executor is always assigned, even if the headers don't match
    156439                    inline ConsoleCommandManipulator& pushFunction(const ExecutorPtr& executor, bool bForce = false)
    157440                        { if (this->command_) { this->command_->pushFunction(executor, bForce); } return *this; }
    158441
     442                    /// Removes the current function from the stack and restores the old state. If there's no other function on the stack, the command is deactivated.
    159443                    inline ConsoleCommandManipulator& popFunction()
    160444                        { if (this->command_) { this->command_->popFunction(); } return *this; }
    161445
     446                    /// Sets the current function-pointer to NULL, which also deactivates the command.
    162447                    inline ConsoleCommandManipulator& resetFunction()
    163448                        { if (this->command_) { this->command_->resetFunction(); } return *this; }
    164449
     450                    /// Changes the current object (used for member-functions).
    165451                    inline ConsoleCommandManipulator& setObject(void* object)
    166452                        { if (this->command_) { this->command_->setObject(object); } return *this; }
     453                    /// Pushes a new object on the object-stack.
    167454                    inline ConsoleCommandManipulator& pushObject(void* object)
    168455                        { if (this->command_) { this->command_->pushObject(object); } return *this; }
     456                    /// Removes the current object from the object-stack and restores the old object (or NULL if there's no object left on the stack).
    169457                    inline ConsoleCommandManipulator& popObject()
    170458                        { if (this->command_) { this->command_->popObject(); } return *this; }
    171459
     460                    /// Changes the activity of the command.
    172461                    inline ConsoleCommandManipulator& setActive(bool bActive)
    173462                        { if (this->command_) { this->command_->setActive(bActive); } return *this; }
     463                    /// Activates the command.
    174464                    inline ConsoleCommandManipulator& activate()
    175465                        { return this->setActive(true); }
     466                    /// Deactivates the command.
    176467                    inline ConsoleCommandManipulator& deactivate()
    177468                        { return this->setActive(false); }
    178469
     470                    /// Changes the visibility of the command.
    179471                    inline ConsoleCommandManipulator& setHidden(bool bHidden)
    180472                        { if (this->command_) { this->command_->setHidden(bHidden); } return *this; }
     473                    /// Hides the command (can still be executed, but is not visible in the list of available commands).
    181474                    inline ConsoleCommandManipulator& hide()
    182475                        { return this->setHidden(true); }
     476                    /// Makes the command visible.
    183477                    inline ConsoleCommandManipulator& show()
    184478                        { return this->setHidden(false); }
    185479
    186                     inline ConsoleCommandManipulator& defaultValues(const MultiType& param1)
    187                         { if (this->command_) { this->command_->defaultValues(param1); } return *this; }
    188                     inline ConsoleCommandManipulator& defaultValues(const MultiType& param1, const MultiType& param2)
    189                         { if (this->command_) { this->command_->defaultValues(param1, param2); } return *this; }
    190                     inline ConsoleCommandManipulator& defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3)
    191                         { if (this->command_) { this->command_->defaultValues(param1, param2, param3); } return *this; }
    192                     inline ConsoleCommandManipulator& defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4)
    193                         { if (this->command_) { this->command_->defaultValues(param1, param2, param3, param4); } return *this; }
    194                     inline ConsoleCommandManipulator& defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5)
    195                         { if (this->command_) { this->command_->defaultValues(param1, param2, param3, param4, param5); } return *this; }
    196                     inline ConsoleCommandManipulator& defaultValue(unsigned int index, const MultiType& param)
    197                         { if (this->command_) { this->command_->defaultValue(index, param); } return *this; }
    198 
     480                    /// Changes the default values of the current executor (doesn't modify executors on deeper levels of the command-stack).
     481                    inline ConsoleCommandManipulator& defaultValues(const MultiType& arg1)
     482                        { if (this->command_) { this->command_->defaultValues(arg1); } return *this; }
     483                    /// Changes the default values of the current executor (doesn't modify executors on deeper levels of the command-stack).
     484                    inline ConsoleCommandManipulator& defaultValues(const MultiType& arg1, const MultiType& arg2)
     485                        { if (this->command_) { this->command_->defaultValues(arg1, arg2); } return *this; }
     486                    /// Changes the default values of the current executor (doesn't modify executors on deeper levels of the command-stack).
     487                    inline ConsoleCommandManipulator& defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3)
     488                        { if (this->command_) { this->command_->defaultValues(arg1, arg2, arg3); } return *this; }
     489                    /// Changes the default values of the current executor (doesn't modify executors on deeper levels of the command-stack).
     490                    inline ConsoleCommandManipulator& defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4)
     491                        { if (this->command_) { this->command_->defaultValues(arg1, arg2, arg3, arg4); } return *this; }
     492                    /// Changes the default values of the current executor (doesn't modify executors on deeper levels of the command-stack).
     493                    inline ConsoleCommandManipulator& defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5)
     494                        { if (this->command_) { this->command_->defaultValues(arg1, arg2, arg3, arg4, arg5); } return *this; }
     495                    /// Changes the default value of the argument with given index of the current executor (doesn't modify executors on deeper levels of the command-stack).
     496                    inline ConsoleCommandManipulator& defaultValue(unsigned int index, const MultiType& arg)
     497                        { if (this->command_) { this->command_->defaultValue(index, arg); } return *this; }
     498
     499                    /// Changes the access level of the command.
    199500                    inline ConsoleCommandManipulator& accessLevel(AccessLevel::Enum level)
    200501                        { if (this->command_) { this->command_->accessLevel(level); } return *this; }
    201502
    202                     inline ConsoleCommandManipulator& argumentCompleter(unsigned int param, ArgumentCompleter* completer)
    203                         { if (this->command_) { this->command_->argumentCompleter(param, completer); } return *this; }
    204 
     503                    /// Changes the argument completer for the given parameter.
     504                    inline ConsoleCommandManipulator& argumentCompleter(unsigned int index, ArgumentCompleter* completer)
     505                        { if (this->command_) { this->command_->argumentCompleter(index, completer); } return *this; }
     506
     507                    /// Defines the command to be an input command.
    205508                    inline ConsoleCommandManipulator& setAsInputCommand()
    206509                        { if (this->command_) { this->command_->setAsInputCommand(); } return *this; }
     510                    /// Changes the keybind mode of the command.
    207511                    inline ConsoleCommandManipulator& keybindMode(KeybindMode::Value mode)
    208512                        { if (this->command_) { this->command_->keybindMode(mode); } return *this; }
     513                    /// Sets the input configured param to the given index.
    209514                    inline ConsoleCommandManipulator& inputConfiguredParam(int index)
    210515                        { if (this->command_) { this->command_->inputConfiguredParam(index); } return *this; }
    211516
    212517                private:
    213                     ConsoleCommand* command_;
     518                    ConsoleCommand* command_;   ///< The command which is being manipulated by this object
    214519            };
    215520
    … …  
    223528            ConsoleCommand& addGroup(const std::string& group, const std::string&  name);
    224529
     530            /// Returns the name that was first used for this command.
    225531            inline const std::string& getName() const
    226532                { return this->baseName_; }
    227533
    228534            const ExecutorPtr& getExecutor() const;
     535            /// Returns the functor that defines the required header for this command (but isn't necessarily executed).
    229536            inline const FunctorPtr& getBaseFunctor() const
    230537                { return this->baseFunctor_; }
    231538
     539            /// Changes the activity of the command.
    232540            inline ConsoleCommand& setActive(bool bActive)
    233541                { this->bActive_ = bActive; return *this; }
     542            /// Activates the command.
    234543            inline ConsoleCommand& activate()
    235544                { return this->setActive(true); }
     545            /// Deactivates the command.
    236546            inline ConsoleCommand& deactivate()
    237547                { return this->setActive(false); }
    238548
     549            /// Changes the visibility of the command.
    239550            inline ConsoleCommand& setHidden(bool bHidden)
    240551                { this->bHidden_ = bHidden; return *this; }
     552            /// Hides the command (can still be executed, but is not visible in the list of available commands).
    241553            inline ConsoleCommand& hide()
    242554                { return this->setHidden(true); }
     555            /// Makes the command visible.
    243556            inline ConsoleCommand& show()
    244557                { return this->setHidden(false); }
    … …  
    246559            bool isActive() const;
    247560            bool hasAccess() const;
     561            /// Returns true if the command is currently hidden.
    248562            inline bool isHidden() const
    249563                { return this->bHidden_; }
    … …  
    252566            const std::string& getDescription() const;
    253567
    254             ConsoleCommand& descriptionParam(unsigned int param, const std::string& description);
    255             const std::string& getDescriptionParam(unsigned int param) const;
     568            ConsoleCommand& descriptionParam(unsigned int index, const std::string& description);
     569            const std::string& getDescriptionParam(unsigned int index) const;
    256570
    257571            ConsoleCommand& descriptionReturnvalue(const std::string& description);
    258             const std::string& getDescriptionReturnvalue(int param) const;
    259 
    260             ConsoleCommand& defaultValues(const MultiType& param1);
    261             ConsoleCommand& defaultValues(const MultiType& param1, const MultiType& param2);
    262             ConsoleCommand& defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3);
    263             ConsoleCommand& defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4);
    264             ConsoleCommand& defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5);
    265             ConsoleCommand& defaultValue(unsigned int index, const MultiType& param);
    266 
     572            const std::string& getDescriptionReturnvalue(int index) const;
     573
     574            ConsoleCommand& defaultValues(const MultiType& arg1);
     575            ConsoleCommand& defaultValues(const MultiType& arg1, const MultiType& arg2);
     576            ConsoleCommand& defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3);
     577            ConsoleCommand& defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4);
     578            ConsoleCommand& defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5);
     579            ConsoleCommand& defaultValue(unsigned int index, const MultiType& arg);
     580
     581            /// Changes the access level of the command.
    267582            inline ConsoleCommand& accessLevel(AccessLevel::Enum level)
    268583                { this->accessLevel_ = level; return *this; }
     584            /// Returns the access level of the command.
    269585            inline AccessLevel::Enum getAccessLevel() const
    270586                { return this->accessLevel_; }
    271587
    272             ConsoleCommand& argumentCompleter(unsigned int param, ArgumentCompleter* completer);
    273             ArgumentCompleter* getArgumentCompleter(unsigned int param) const;
    274 
     588            ConsoleCommand& argumentCompleter(unsigned int index, ArgumentCompleter* completer);
     589            ArgumentCompleter* getArgumentCompleter(unsigned int index) const;
     590
     591            /// Defines the command to be an input command
    275592            inline ConsoleCommand& setAsInputCommand()
    276593            {
    … …  
    281598            }
    282599
     600            /// Changes the keybind mode.
    283601            inline ConsoleCommand& keybindMode(KeybindMode::Value mode)
    284602                { this->keybindMode_ = mode; return *this; }
     603            /// Returns the keybind mode
    285604            inline KeybindMode::Value getKeybindMode() const
    286605                { return this->keybindMode_; }
    287606
     607            /// Changes the input configured param to the given index.
    288608            inline ConsoleCommand& inputConfiguredParam(int index)
    289609                { this->inputConfiguredParam_ = index; return *this; }
     610            /// Returns the input configured param.
    290611            inline int getInputConfiguredParam_() const
    291612                { return this->inputConfiguredParam_; }
    292613
     614            /// Returns a manipulator for this command.
    293615            inline ConsoleCommandManipulator getManipulator() const
    294616                { return this; }
    … …  
    311633            void* getObject() const;
    312634
    313             bool bActive_;
    314             bool bHidden_;
    315             AccessLevel::Enum accessLevel_;
    316             std::string baseName_;
    317             FunctorPtr baseFunctor_;
    318 
    319             ExecutorPtr executor_;
    320             std::stack<Command> commandStack_;
    321             std::vector<void*> objectStack_;
    322 
    323             ArgumentCompleter* argumentCompleter_[5];
    324 
    325             KeybindMode::Value keybindMode_;
    326             int inputConfiguredParam_;
    327 
    328             LanguageEntryLabel description_;
    329             LanguageEntryLabel descriptionReturnvalue_;
    330             LanguageEntryLabel descriptionParam_[MAX_FUNCTOR_ARGUMENTS];
     635            bool bActive_;                                                  ///< True if the command should be active (it can still be inactive, for example if the function is missing)
     636            bool bHidden_;                                                  ///< True if the command is hidden (it is still executable, but not visible in the list of available commands)
     637            AccessLevel::Enum accessLevel_;                                 ///< The access level (the state of the game in which you can access the command)
     638            std::string baseName_;                                          ///< The name that was first assigned to the command
     639            FunctorPtr baseFunctor_;                                        ///< The functor that defines the header of the command-function
     640
     641            ExecutorPtr executor_;                                          ///< The Executor that is used to execute the command
     642            std::stack<Command> commandStack_;                              ///< A stack of commands, used to push and pop different functions
     643            std::vector<void*> objectStack_;                                ///< A stack of objects, used to push and pop different objects for a function
     644
     645            ArgumentCompleter* argumentCompleter_[MAX_FUNCTOR_ARGUMENTS];   ///< ArgumentCompleter for each argument
     646
     647            KeybindMode::Value keybindMode_;                                ///< The keybind mode
     648            int inputConfiguredParam_;                                      ///< The input configured param
     649
     650            LanguageEntryLabel description_;                                ///< The description of the command
     651            LanguageEntryLabel descriptionReturnvalue_;                     ///< A description of the return-value
     652            LanguageEntryLabel descriptionParam_[MAX_FUNCTOR_ARGUMENTS];    ///< A description for each argument
    331653
    332654        public:
     655            /// Returns the map with all groups and commands.
    333656            static inline const std::map<std::string, std::map<std::string, ConsoleCommand*> >& getCommands()
    334657                { return ConsoleCommand::getCommandMap(); }
     658            /// Returns the map with all groups and commands in lowercase.
    335659            static inline const std::map<std::string, std::map<std::string, ConsoleCommand*> >& getCommandsLC()
    336660                { return ConsoleCommand::getCommandMapLC(); }
    337661
     662            /// Returns a command (shortcut) with given name. @param name The name of the command shortcut @param bPrintError If true, an error is printed if the command doesn't exist
    338663            static inline const ConsoleCommand* getCommand(const std::string& name, bool bPrintError = false)
    339664                { return ConsoleCommand::getCommand("", name, bPrintError); }
     665            /// Returns a command (shortcut) with given name in lowercase. @param name The lowercase name of the command shortcut @param bPrintError If true, an error is printed if the command doesn't exist
    340666            static inline const ConsoleCommand* getCommandLC(const std::string& name, bool bPrintError = false)
    341667                { return ConsoleCommand::getCommandLC("", name, bPrintError); }
    … …  
    354680    };
    355681
     682    /**
     683        @brief Creates a new ConsoleCommand.
     684        @param name The name of the command
     685        @param executor The executor of the command
     686        @param bInitialized If true, the command is ready to be executed, otherwise it has to be activated first.
     687    */
    356688    inline ConsoleCommand* createConsoleCommand(const std::string& name, const ExecutorPtr& executor, bool bInitialized = true)
    357689        { return new ConsoleCommand("", name, executor, bInitialized); }
     690    /**
     691        @brief Creates a new ConsoleCommand.
     692        @param group The group of the command
     693        @param name The name of the command
     694        @param executor The executor of the command
     695        @param bInitialized If true, the command is ready to be executed, otherwise it has to be activated first.
     696    */
    358697    inline ConsoleCommand* createConsoleCommand(const std::string& group, const std::string& name, const ExecutorPtr& executor, bool bInitialized = true)
    359698        { return new ConsoleCommand(group, name, executor, bInitialized); }
    360699
     700
     701    /**
     702        @brief Returns a manipulator for a command with the given name.
     703
     704        @note If the command doesn't exist, the manipulator contains a NULL pointer to the command,
     705        but it can still be used without checks, because all functions of ConsoleCommandManipulator
     706        check internally if the command exists.
     707    */
    361708    inline ConsoleCommand::ConsoleCommandManipulator ModifyConsoleCommand(const std::string& name)
    362709        { return ConsoleCommand::getCommand(name, true); }
     710    /**
     711        @brief Returns a manipulator for a command with the given group and name.
     712
     713        @note If the command doesn't exist, the manipulator contains a NULL pointer to the command,
     714        but it can still be used without checks, because all functions of ConsoleCommandManipulator
     715        check internally if the command exists.
     716    */
    363717    inline ConsoleCommand::ConsoleCommandManipulator ModifyConsoleCommand(const std::string& group, const std::string& name)
    364718        { return ConsoleCommand::getCommand(group, name, true); }

  • code/trunk/src/libraries/core/command/ConsoleCommandCompilation.cc

    r7284 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @brief Implementation of some console commands.
     32*/
    2833
    2934#include "ConsoleCommandCompilation.h"
    … …  
    5156    SetConsoleCommand("calculate", calculate);
    5257
     58    /**
     59        @brief Reads the content of a file and executes the commands in it line by line.
     60    */
    5361    void source(const std::string& filename)
    5462    {
    … …  
    8694    }
    8795
     96    /**
     97        @brief Simply returns the arguments.
     98    */
    8899    std::string echo(const std::string& text)
    89100    {
    … …  
    91102    }
    92103
     104    /**
     105        @brief Writes text to the console, depending on the first argument with or without a line-break after it.
     106    */
    93107    void puts(bool newline, const std::string& text)
    94108    {
    … …  
    103117    }
    104118
     119    /**
     120        @brief Writes text to a file.
     121    */
    105122    void write(const std::string& filename, const std::string& text)
    106123    {
    … …  
    118135    }
    119136
     137    /**
     138        @brief Appends text to a file.
     139    */
    120140    void append(const std::string& filename, const std::string& text)
    121141    {
    … …  
    133153    }
    134154
     155    /**
     156        @brief Reads text from a file
     157    */
    135158    std::string read(const std::string& filename)
    136159    {
    … …  
    158181    }
    159182
     183    /**
     184        @brief Parses the mathematical expression and returns the result.
     185    */
    160186    float calculate(const std::string& calculation)
    161187    {

  • code/trunk/src/libraries/core/command/ConsoleCommandCompilation.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command ConsoleCommand
     32    @brief Declaration of some console commands.
     33*/
     34
    2935#ifndef _ConsoleCommandCompilation_H__
    3036#define _ConsoleCommandCompilation_H__

  • code/trunk/src/libraries/core/command/Executor.cc

    r7284 r7401  
    2727 *   Inspiration: Executor by Benjamin Grauer
    2828 */
     29
     30/**
     31    @file
     32    @brief Implementation of orxonox::Executor
     33*/
    2934
    3035#include "Executor.h"
    … …  
    4045namespace orxonox
    4146{
     47    /**
     48        @brief Constructor: Creates an executor.
     49        @param functor The wrapped functor
     50        @param name The name of the executor (optional, used mostly for debug output)
     51    */
    4252    Executor::Executor(const FunctorPtr& functor, const std::string& name)
    4353    {
    … …  
    4656    }
    4757
     58    /**
     59        @brief Copy-constructor: Creates a new executor with the same values and a clone of the wrapped Functor.
     60    */
    4861    Executor::Executor(const Executor& other) : name_(other.name_)
    4962    {
    … …  
    5366    }
    5467
     68    /**
     69        @brief Destructor
     70    */
    5571    Executor::~Executor()
    5672    {
    5773    }
    5874
     75    /**
     76        @brief Calls the wrapped function with arguments that are passed in a string.
     77        @param arguments The arguments that should be passed to the function, separated by @a delimiter
     78        @param error A pointer to a variable (or NULL) that is used to store the error code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
     79        @param delimiter The delimiter that is used to separate the arguments in the string @a arguments
     80        @param bPrintError If true, errors are printed to the console if the function couldn't be executed with the given arguments
     81        @return Returns the return value of the function (or MT_Type::Null if there is no return value)
     82    */
    5983    MultiType Executor::parse(const std::string& arguments, int* error, const std::string& delimiter, bool bPrintError) const
    6084    {
    … …  
    6286    }
    6387
     88    /**
     89        @brief Calls the wrapped function with arguments that are passed as tokens in a SubString
     90        @param arguments The arguments that should be passed to the function
     91        @param error A pointer to a variable (or NULL) that is used to store the error code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
     92        @param delimiter The delimiter that was used to separate the arguments in the SubString @a arguments (used to join the surplus arguments)
     93        @param bPrintError If true, errors are printed to the console if the function couldn't be executed with the given arguments
     94        @return Returns the return value of the function (or MT_Type::Null if there is no return value)
     95    */
    6496    MultiType Executor::parse(const SubString& arguments, int* error, const std::string& delimiter, bool bPrintError) const
    6597    {
    66         MultiType param[MAX_FUNCTOR_ARGUMENTS];
    67         unsigned int paramCount = this->evaluateParams(arguments, param, error, delimiter);
    68 
     98        // evaluate the arguments
     99        MultiType arg[MAX_FUNCTOR_ARGUMENTS];
     100        unsigned int argCount = this->evaluateArguments(arguments, arg, error, delimiter);
     101
     102        // check if an error occurred
    69103        if (error && *error)
    70104        {
    71105            if (bPrintError)
    72                 COUT(2) << "Warning: Can't call executor " << this->name_ << " through parser: Not enough parameters or default values given (input: " << arguments.join() << ")." << std::endl;
     106                COUT(2) << "Warning: Can't call executor " << this->name_ << " through parser: Not enough arguments or default values given (input: " << arguments.join() << ")." << std::endl;
    73107            return MT_Type::Null;
    74108        }
    75109
    76         COUT(5) << "Executor::parse: \"" << arguments.join(delimiter) << "\" -> " << paramCount << " params: " << param[0] << " / " << param[1] << " / " << param[2] << " / " << param[3] << " / " << param[4] << std::endl;
    77 
    78         switch (paramCount)
     110        COUT(5) << "Executor::parse: \"" << arguments.join(delimiter) << "\" -> " << argCount << " arguments: " << arg[0] << " / " << arg[1] << " / " << arg[2] << " / " << arg[3] << " / " << arg[4] << std::endl;
     111
     112        // execute the function with the evaluated arguments (the default values of the executor are also included in these arguments)
     113        switch (argCount)
    79114        {
    80115            case 0:  return (*this->functor_)();
    81             case 1:  return (*this->functor_)(param[0]);
    82             case 2:  return (*this->functor_)(param[0], param[1]);
    83             case 3:  return (*this->functor_)(param[0], param[1], param[2]);
    84             case 4:  return (*this->functor_)(param[0], param[1], param[2], param[3]);
     116            case 1:  return (*this->functor_)(arg[0]);
     117            case 2:  return (*this->functor_)(arg[0], arg[1]);
     118            case 3:  return (*this->functor_)(arg[0], arg[1], arg[2]);
     119            case 4:  return (*this->functor_)(arg[0], arg[1], arg[2], arg[3]);
    85120            case 5:
    86             default: return (*this->functor_)(param[0], param[1], param[2], param[3], param[4]);
     121            default: return (*this->functor_)(arg[0], arg[1], arg[2], arg[3], arg[4]);
    87122        }
    88123    }
    89124
    90     int Executor::evaluateParams(const SubString& arguments, MultiType param[MAX_FUNCTOR_ARGUMENTS], int* error, const std::string& delimiter) const
     125    /**
     126        @brief Converts the arguments in a SubString to the right type, so they can be used to execute the function without further conversions.
     127        @param arguments The arguments that should be converted
     128        @param arg An array of MultiType where the converted arguments will be stored
     129        @param error A pointer to a variable (or NULL) that is used to store the error code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
     130        @param delimiter The delimiter that was used to separate the arguments in the SubString @a arguments (used to join the surplus arguments)
     131        @return Returns the number of evaluated arguments
     132    */
     133    int Executor::evaluateArguments(const SubString& arguments, MultiType arg[MAX_FUNCTOR_ARGUMENTS], int* error, const std::string& delimiter) const
    91134    {
    92135        unsigned int paramCount = this->functor_->getParamCount();
    … …  
    106149        // assign all given arguments to the multitypes
    107150        for (unsigned int i = 0; i < std::min(std::min(argumentCount, paramCount), MAX_FUNCTOR_ARGUMENTS); i++)
    108             param[i] = arguments[i];
     151            arg[i] = arguments[i];
    109152
    110153        // fill the remaining multitypes with default values
    111154        for (unsigned int i = argumentCount; i < std::min(paramCount, MAX_FUNCTOR_ARGUMENTS); i++)
    112             param[i] = this->defaultValue_[i];
     155            arg[i] = this->defaultValue_[i];
    113156
    114157        // assign the remaining arguments all to the last parameter if it is a string
    115158        if ((paramCount <= MAX_FUNCTOR_ARGUMENTS) &&(argumentCount > paramCount) && (paramCount == 1 || this->functor_->getTypenameParam(paramCount - 1) == "string"))
    116             param[paramCount - 1] = arguments.subSet(paramCount - 1).join(delimiter);
    117 
    118         // evaluate the param types through the functor
     159            arg[paramCount - 1] = arguments.subSet(paramCount - 1).join(delimiter);
     160
     161        // evaluate the parameter types through the functor
    119162        for (unsigned int i = 0; i < std::min(paramCount, MAX_FUNCTOR_ARGUMENTS); i++)
    120             this->functor_->evaluateParam(i, param[i]);
     163            this->functor_->evaluateArgument(i, arg[i]);
    121164
    122165        if (error)
    … …  
    125168    }
    126169
    127     void Executor::setDefaultValues(const MultiType& param1)
    128     {
    129         this->defaultValue_[0] = param1;
    130     }
    131 
    132     void Executor::setDefaultValues(const MultiType& param1, const MultiType& param2)
    133     {
    134         this->defaultValue_[0] = param1;
    135         this->defaultValue_[1] = param2;
    136     }
    137 
    138     void Executor::setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3)
    139     {
    140         this->defaultValue_[0] = param1;
    141         this->defaultValue_[1] = param2;
    142         this->defaultValue_[2] = param3;
    143     }
    144 
    145     void Executor::setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4)
    146     {
    147         this->defaultValue_[0] = param1;
    148         this->defaultValue_[1] = param2;
    149         this->defaultValue_[2] = param3;
    150         this->defaultValue_[3] = param4;
    151     }
    152 
    153     void Executor::setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5)
    154     {
    155         this->defaultValue_[0] = param1;
    156         this->defaultValue_[1] = param2;
    157         this->defaultValue_[2] = param3;
    158         this->defaultValue_[3] = param4;
    159         this->defaultValue_[4] = param5;
    160     }
    161 
    162     void Executor::setDefaultValue(unsigned int index, const MultiType& param)
     170    /// Defines the default value for the first parameter.
     171    void Executor::setDefaultValues(const MultiType& arg1)
     172    {
     173        this->defaultValue_[0] = arg1;
     174    }
     175
     176    /// Defines the default value for the first two parameters.
     177    void Executor::setDefaultValues(const MultiType& arg1, const MultiType& arg2)
     178    {
     179        this->defaultValue_[0] = arg1;
     180        this->defaultValue_[1] = arg2;
     181    }
     182
     183    /// Defines the default value for the first three parameters.
     184    void Executor::setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3)
     185    {
     186        this->defaultValue_[0] = arg1;
     187        this->defaultValue_[1] = arg2;
     188        this->defaultValue_[2] = arg3;
     189    }
     190
     191    /// Defines the default value for the first four parameters.
     192    void Executor::setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4)
     193    {
     194        this->defaultValue_[0] = arg1;
     195        this->defaultValue_[1] = arg2;
     196        this->defaultValue_[2] = arg3;
     197        this->defaultValue_[3] = arg4;
     198    }
     199
     200    /// Defines the default value for the first five parameters.
     201    void Executor::setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5)
     202    {
     203        this->defaultValue_[0] = arg1;
     204        this->defaultValue_[1] = arg2;
     205        this->defaultValue_[2] = arg3;
     206        this->defaultValue_[3] = arg4;
     207        this->defaultValue_[4] = arg5;
     208    }
     209
     210    /// Defines the default value for a parameter with given index (the first parameter has index 0).
     211    void Executor::setDefaultValue(unsigned int index, const MultiType& arg)
    163212    {
    164213        if (index < MAX_FUNCTOR_ARGUMENTS)
    165             this->defaultValue_[index] = param;
    166     }
    167 
     214            this->defaultValue_[index] = arg;
     215    }
     216
     217    /// Returns true if the executor has a default value for each parameter of the wrapped function, so it can be called without passing additional arguments.
    168218    bool Executor::allDefaultValuesSet() const
    169219    {

  • code/trunk/src/libraries/core/command/Executor.h

    r7284 r7401  
    2828 */
    2929
     30/**
     31    @defgroup FunctorExecutor Functor and Executor
     32    @ingroup Command
     33*/
     34
     35/**
     36    @file
     37    @ingroup Command FunctorExecutor
     38    @brief Declaration of the orxonox::Executor class and the createExecutor() functions.
     39
     40    @anchor ExecutorExample
     41
     42    orxonox::Executor is used to wrap an orxonox::Functor and to store default values for
     43    its parameters. Usually one uses the function createExecutor() to create a new executor.
     44    This function returns an orxonox::ExecutorPtr which is a typedef of @ref orxonox::SharedPtr
     45    "SharedPtr<Executor>", used to manage the pointer to the executor.
     46
     47    Executors are mostly used to execute callbacks. Because some callback functions need arguments,
     48    Executor provides an easy interface to store these arguments as default values, so the
     49    executor can also be executed without arguments because it will use these default values.
     50
     51    The Executor doesn't contain the function-pointer directly. Instead it wraps an instance
     52    of orxonox::Functor. See @ref FunctorExample "Functor.h" for more information and some
     53    examples.
     54
     55    Example:
     56    @code
     57    void myFunction(int a, int b)                           // declare a static function
     58    {
     59        COUT(0) << "The sum is " << (a + b) << std::endl;   // print the sum of a and b to the console
     60    }
     61
     62    FunctorPtr functor = createFunctor(&myFunction);        // create a functor that wraps the function-pointer
     63    ExecutorPtr executor = createExecutor(functor);         // create an executor that wraps the functor
     64
     65    (*executor)(2, 5);                                      // calls the executor with arguments 2 and 5, prints "The sum is 7" to the console
     66
     67    executor->setDefaultValue(1, 10);                       // sets the default-value for the second parameter (note: paramters start at index 0) to 10
     68
     69    (*executor)(2);                                         // calls the executor with argument 2 and default-value 10, prints "The sum is 12"
     70
     71    executor->setDefaultValue(0, 5);                        // sets the default-value for the first parameter to 5
     72
     73    (*executor)();                                          // calls the executor with default-values only, prints "The sum is 15"
     74    @endcode
     75
     76    Because executors that were created with createExecutor() are managed by an orxonox::SharedPtr,
     77    they don't need to be deleted after usage.
     78*/
     79
    3080#ifndef _Executor_H__
    3181#define _Executor_H__
    … …  
    4090namespace orxonox
    4191{
     92    /**
     93        @brief This class is used to wrap a Functor and to store default values for any of its parameters.
     94
     95        @see See @ref ExecutorExample "Executor.h" for an example.
     96    */
    4297    class _CoreExport Executor
    4398    {
    … …  
    47102            virtual ~Executor();
    48103
     104            /// Calls the wrapped function with 0 arguments. If the function needs more arguments, the executor's default values are used.
    49105            inline MultiType operator()() const
    50106                { return (*this->functor_)(this->defaultValue_[0], this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    51             inline MultiType operator()(const MultiType& param1) const
    52                 { return (*this->functor_)(param1, this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    53             inline MultiType operator()(const MultiType& param1, const MultiType& param2) const
    54                 { return (*this->functor_)(param1, param2, this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    55             inline MultiType operator()(const MultiType& param1, const MultiType& param2, const MultiType& param3) const
    56                 { return (*this->functor_)(param1, param2, param3, this->defaultValue_[3], this->defaultValue_[4]); }
    57             inline MultiType operator()(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4) const
    58                 { return (*this->functor_)(param1, param2, param3, param4, this->defaultValue_[4]); }
    59             inline MultiType operator()(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5) const
    60                 { return (*this->functor_)(param1, param2, param3, param4, param5); }
     107            /// Calls the wrapped function with 1 argument. If the function needs more arguments, the executor's default values are used.
     108            inline MultiType operator()(const MultiType& arg1) const
     109                { return (*this->functor_)(arg1, this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
     110            /// Calls the wrapped function with 2 arguments. If the function needs more arguments, the executor's default values are used.
     111            inline MultiType operator()(const MultiType& arg1, const MultiType& arg2) const
     112                { return (*this->functor_)(arg1, arg2, this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
     113            /// Calls the wrapped function with 3 arguments. If the function needs more arguments, the executor's default values are used.
     114            inline MultiType operator()(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3) const
     115                { return (*this->functor_)(arg1, arg2, arg3, this->defaultValue_[3], this->defaultValue_[4]); }
     116            /// Calls the wrapped function with 4 arguments. If the function needs more arguments, the executor's default values are used.
     117            inline MultiType operator()(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4) const
     118                { return (*this->functor_)(arg1, arg2, arg3, arg4, this->defaultValue_[4]); }
     119            /// Calls the wrapped function with 5 arguments. If the function needs more arguments, the executor's default values are used.
     120            inline MultiType operator()(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5) const
     121                { return (*this->functor_)(arg1, arg2, arg3, arg4, arg5); }
    61122
    62123            MultiType parse(const std::string& arguments, int* error = 0, const std::string& delimiter = " ", bool bPrintError = false) const;
    63124            MultiType parse(const SubString& arguments, int* error = 0, const std::string& delimiter = " ", bool bPrintError = false) const;
    64125
    65             int evaluateParams(const SubString& arguments, MultiType param[MAX_FUNCTOR_ARGUMENTS], int* error = 0, const std::string& delimiter = " ") const;
    66 
     126            int evaluateArguments(const SubString& arguments, MultiType arg[MAX_FUNCTOR_ARGUMENTS], int* error = 0, const std::string& delimiter = " ") const;
     127
     128            /// Changes the functor.
    67129            inline void setFunctor(const FunctorPtr& functor)
    68130                { this->functor_ = functor; }
     131            /// Returns the functor.
    69132            inline const FunctorPtr& getFunctor() const
    70133                { return this->functor_; }
    71134
     135            /// Changes the name of the executor.
    72136            inline void setName(const std::string& name)
    73137                { this->name_ = name; }
     138            /// Returns the name of the executor.
    74139            inline const std::string& getName() const
    75140                { return this->name_; }
    76141
     142            /// Returns the number of parameters of the wrapped function.
    77143            inline unsigned int getParamCount() const
    78144                { return this->functor_->getParamCount(); }
     145            /// Returns true if the wrapped function returns a value.
    79146            inline bool hasReturnvalue() const
    80147                { return this->functor_->hasReturnvalue(); }
     148            /// Returns the type of the wrapped function (static or member).
    81149            inline Functor::Type::Enum getType() const
    82150                { return this->functor_->getType(); }
     151            /// Returns the name of the type of a parameter with given index (the first parameter has index 0).
    83152            inline std::string getTypenameParam(unsigned int param) const
    84153                { return this->functor_->getTypenameParam(param); }
     154            /// Returns the name of the type of the return value.
    85155            inline std::string getTypenameReturnvalue() const
    86156                { return this->functor_->getTypenameReturnvalue(); }
    87157
    88             void setDefaultValues(const MultiType& param1);
    89             void setDefaultValues(const MultiType& param1, const MultiType& param2);
    90             void setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3);
    91             void setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4);
    92             void setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5);
    93             void setDefaultValue(unsigned int index, const MultiType& param);
    94 
     158            void setDefaultValues(const MultiType& arg1);
     159            void setDefaultValues(const MultiType& arg1, const MultiType& arg2);
     160            void setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3);
     161            void setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4);
     162            void setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5);
     163            void setDefaultValue(unsigned int index, const MultiType& arg);
     164
     165            /// Returns the default value for a parameter with given index (the first parameter has index 0).
    95166            inline MultiType getDefaultValue(unsigned int index) const
    96167            {
    … …  
    102173
    103174            bool allDefaultValuesSet() const;
     175
     176            /// Returns true if the executor contains a default value for the parameter with given index (the first parameter has index 0).
    104177            inline bool defaultValueSet(unsigned int index) const
    105178            {
    … …  
    111184
    112185        protected:
    113             FunctorPtr functor_;
    114             std::string name_;
    115             MultiType defaultValue_[MAX_FUNCTOR_ARGUMENTS];
     186            FunctorPtr functor_;                                ///< The underlying Functor that wraps a function
     187            std::string name_;                                  ///< The name of the executor
     188            MultiType defaultValue_[MAX_FUNCTOR_ARGUMENTS];     ///< The default values, one for each parameter
    116189    };
    117190
     191    /**
     192        @brief A child class of Executor, used to distinguish executors that wrap static functions from executors that wrap member-functions.
     193
     194        Behaves exactly like Executor, because static functions need no special treatment.
     195    */
    118196    class _CoreExport ExecutorStatic : public Executor
    119197    {
    120198        public:
     199            /// Constructor: Initializes the parent class
    121200            ExecutorStatic(const FunctorStaticPtr& functor, const std::string& name = "") : Executor(functor, name) {}
     201            /// Destructor
    122202            virtual ~ExecutorStatic() {}
    123203    };
    124204
     205    /**
     206        @brief A child class of Executor, used for easier handling of non-static member-functions.
     207
     208        Overloads some functions that call the underlying FunctorMember and additionally pass
     209        an object-pointer that is needed for non-static member-functions.
     210    */
    125211    template <class T>
    126212    class ExecutorMember : public Executor
    127213    {
    128214        public:
     215            /// Constructor: Initializes the parent class and the pointer to the member-functor.
    129216            ExecutorMember(const FunctorMemberPtr<T>& functor, const std::string& name = "") : Executor(functor, name), functorMember_(functor) {}
     217            /// Destructor
    130218            virtual ~ExecutorMember() {}
    131219
    132220            using Executor::operator();
    133221
     222            /// Calls the wrapped function with 0 arguments and an object-pointer. If the function needs more arguments, the executor's default values are used.
    134223            inline MultiType operator()(T* object) const
    135224                { return (*this->functorMember_)(object, this->defaultValue_[0], this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    136             inline MultiType operator()(T* object, const MultiType& param1) const
    137                 { return (*this->functorMember_)(object, param1, this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    138             inline MultiType operator()(T* object, const MultiType& param1, const MultiType& param2) const
    139                 { return (*this->functorMember_)(object, param1, param2, this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    140             inline MultiType operator()(T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3) const
    141                 { return (*this->functorMember_)(object, param1, param2, param3, this->defaultValue_[3], this->defaultValue_[4]); }
    142             inline MultiType operator()(T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4) const
    143                 { return (*this->functorMember_)(object, param1, param2, param3, param4, this->defaultValue_[4]); }
    144             inline MultiType operator()(T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5) const
    145                 { return (*this->functorMember_)(object, param1, param2, param3, param4, param5); }
    146 
    147 
    148             inline MultiType operator()(const T* object) const
    149                 { return (*this->functorMember_)(object, this->defaultValue_[0], this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    150             inline MultiType operator()(const T* object, const MultiType& param1) const
    151                 { return (*this->functorMember_)(object, param1, this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    152             inline MultiType operator()(const T* object, const MultiType& param1, const MultiType& param2) const
    153                 { return (*this->functorMember_)(object, param1, param2, this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    154             inline MultiType operator()(const T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3) const
    155                 { return (*this->functorMember_)(object, param1, param2, param3, this->defaultValue_[3], this->defaultValue_[4]); }
    156             inline MultiType operator()(const T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4) const
    157                 { return (*this->functorMember_)(object, param1, param2, param3, param4, this->defaultValue_[4]); }
    158             inline MultiType operator()(const T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5) const
    159                 { return (*this->functorMember_)(object, param1, param2, param3, param4, param5); }
    160 
     225            /// Calls the wrapped function with 1 argument and an object-pointer. If the function needs more arguments, the executor's default values are used.
     226            inline MultiType operator()(T* object, const MultiType& arg1) const
     227                { return (*this->functorMember_)(object, arg1, this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
     228            /// Calls the wrapped function with 2 arguments and an object-pointer. If the function needs more arguments, the executor's default values are used.
     229            inline MultiType operator()(T* object, const MultiType& arg1, const MultiType& arg2) const
     230                { return (*this->functorMember_)(object, arg1, arg2, this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
     231            /// Calls the wrapped function with 3 arguments and an object-pointer. If the function needs more arguments, the executor's default values are used.
     232            inline MultiType operator()(T* object, const MultiType& arg1, const MultiType& arg2, const MultiType& arg3) const
     233                { return (*this->functorMember_)(object, arg1, arg2, arg3, this->defaultValue_[3], this->defaultValue_[4]); }
     234            /// Calls the wrapped function with 4 arguments and an object-pointer. If the function needs more arguments, the executor's default values are used.
     235            inline MultiType operator()(T* object, const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4) const
     236                { return (*this->functorMember_)(object, arg1, arg2, arg3, arg4, this->defaultValue_[4]); }
     237            /// Calls the wrapped function with 5 arguments and an object-pointer. If the function needs more arguments, the executor's default values are used.
     238            inline MultiType operator()(T* object, const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5) const
     239                { return (*this->functorMember_)(object, arg1, arg2, arg3, arg4, arg5); }
     240
     241            /// Changes the object-pointer of the underlying FunctorMember.
    161242            inline void setObject(T* object) const
    162243                { this->functorMember_->setObject(object); }
    163             inline void setObject(const T* object) const
    164                 { this->functorMember_->setObject(object); }
     244            /// Returns the object-pointer of the underlying FunctorMember.
     245            inline T* getObject() const
     246                { return this->functorMember_->getObject(); }
    165247
    166248            using Executor::parse;
    167249
    168             MultiType parse(T* object, const std::string& params, int* error = 0, const std::string& delimiter = " ", bool bPrintError = false) const
     250            /// Overloads Executor::parse() with an additional object-pointer.
     251            MultiType parse(T* object, const std::string& arguments, int* error = 0, const std::string& delimiter = " ", bool bPrintError = false) const
    169252            {
    170253                T* oldobject = this->functorMember_->getObject();
    171254
    172255                this->functorMember_->setObject(object);
    173                 const MultiType& result = this->Executor::parse(params, error, delimiter, bPrintError);
     256                const MultiType& result = this->Executor::parse(arguments, error, delimiter, bPrintError);
    174257                this->functorMember_->setObject(oldobject);
    175258
    … …  
    177260            }
    178261
    179             MultiType parse(const T* object, const std::string& params, int* error = 0, const std::string& delimiter = " ", bool bPrintError = false) const
    180             {
    181                 T* oldobject = this->functorMember_->getObject();
    182 
    183                 this->functorMember_->setObject(object);
    184                 const MultiType& result = this->Executor::parse(params, error, delimiter, bPrintError);
    185                 this->functorMember_->setObjects(oldobject);
    186 
    187                 return result;
    188             }
    189 
    190262        protected:
    191             FunctorMemberPtr<T> functorMember_;
     263            FunctorMemberPtr<T> functorMember_;     ///< A pointer to the FunctorMember is stored separately to avoid casting when executing the function.
    192264    };
    193265
     266    /// Creates a new Executor that wraps a given Functor.
    194267    inline ExecutorPtr createExecutor(const FunctorPtr& functor, const std::string& name = "")
    195268    {
    … …  
    197270    }
    198271
     272    /// Creates a new ExecutorMember that wraps a given FunctorMember.
    199273    template <class T>
    200274    inline ExecutorMemberPtr<T> createExecutor(const FunctorMemberPtr<T>& functor, const std::string& name = "")
    … …  
    203277    }
    204278
     279    /// Creates a new ExecutorStatic that wraps a given FunctorStatic.
    205280    inline ExecutorStaticPtr createExecutor(const FunctorStaticPtr& functor, const std::string& name = "")
    206281    {

  • code/trunk/src/libraries/core/command/ExecutorPtr.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command FunctorExecutor
     32    @brief Typedefs and definitions of ExecutorPtr, ExecutorStaticPtr, and ExecutorMemberPtr
     33
     34    Instances of orxonox::Executor are usually managed by an orxonox::SharedPtr. This ensures
     35    that Executors will be destroyed after usage. To make things easier, there's a typedef
     36    that defines ExecutorPtr as SharedPtr<Executor>.
     37
     38    Because there's not only orxonox::Executor, but also orxonox::ExecutorStatic, and
     39    orxonox::ExecutorMember, the shared pointers need to store them all and also reflect
     40    their hierarchy - ExecutorStatic and ExecutorMember should not be mixed, but both can
     41    be converted to Executor. This is achieved by using orxonox::SharedChildPtr.
     42
     43    Because it's not possible to use a typedef for a template, we have to define the
     44    helper class ExecutorMemberPtr<T> that makes it easier to use ExecutorMember.
     45*/
     46
    2947#ifndef _ExecutorPtr_H__
    3048#define _ExecutorPtr_H__
    … …  
    3553namespace orxonox
    3654{
     55    /// ExecutorPtr is just a typedef of SharedPtr
    3756    typedef SharedPtr<Executor> ExecutorPtr;
    3857
     58    /// ExecutorStaticPtr is just a typedef of SharedChildPtr
    3959    typedef SharedChildPtr<ExecutorStatic, ExecutorPtr> ExecutorStaticPtr;
    4060
     61    /// It's not possible to use a typedef for ExecutorMemberPtr<T>, so we have to create a child-class instead. It inherits all functions from SharedChildPtr, but needs to (re-)implement some constructors.
    4162    template <class T>
    4263    class ExecutorMemberPtr : public SharedChildPtr<ExecutorMember<T>, ExecutorPtr>

  • code/trunk/src/libraries/core/command/Functor.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command FunctorExecutor
     32    @brief Definition of orxonox::Functor and its specialized subclasses, as well as the createFunctor() functions.
     33
     34    @anchor FunctorExample
     35
     36    Functors can be used to wrap function-pointers. While function-pointers have a very
     37    complicated syntax in C++, Functors are always the same and you can call the wrapped
     38    function-pointer independently of its parameter with arguments of type MultiType. These
     39    arguments are then automatically converted to the right type.
     40
     41    To create a Functor, the helper function createFunctor() is used. It returns an instance
     42    of orxonox::FunctorPtr which is simply a typedef of @ref orxonox::SharedPtr "SharedPtr<Functor>".
     43    This means you don't have to delete the Functor after using it, because it is managed
     44    by the SharedPtr.
     45
     46    Example:
     47    @code
     48    int myStaticFunction(int value)                         // Definition of a static function
     49    {
     50        return (value * 2);                                 // Return the double of the value
     51    }
     52
     53    FunctorPtr functor = createFunctor(&myStaticFunction);  // Create a Functor
     54
     55    int result = (*functor)(5);                             // Calls the functor with value = 5, result == 10
     56
     57    int result = (*functor)("7");                           // Calls the functor with a string which is converted to an integer, result == 14
     58    @endcode
     59
     60    Functors can also be used if you work with member-functions. In this case createFunctor()
     61    returns an instance of orxonox::FunctorMemberPtr - this allows you to define the object
     62    that will be used to call the function.
     63
     64    Example:
     65    @code
     66    class MyClass                                                   // Define a class
     67    {
     68        public:
     69            MyClass(const std::string& text)                        // Constructor
     70            {
     71                this->text_ = text;
     72            }
     73
     74            bool contains(const std::string& word)                  // Function that searches for "word" in "text"
     75            {
     76                return (this->text_.find(word) != std::string::npos);
     77            }
     78
     79        private:
     80            std::string text_;                                      // Member variable
     81    };
     82
     83    MyClass* object = new MyClass("Hello World");                   // Create an object of type MyClass and set its text to "Hello World"
     84
     85    FunctorPtr functor = createFunctor(&MyClass:contains, object);  // Create a Functor (note the object!)
     86
     87    bool result = (*functor)("World");                              // result == true
     88    bool result = (*functor)("test");                               // result == false
     89    @endcode
     90
     91    Instead of assigning the object directly to the functor when creating it, you can also define
     92    it at any later point or when you call the functor. Note however that this works only with
     93    orxonox::FunctorMember.
     94
     95    @code
     96    MyClass* object1 = new MyClass("Hello World");                  // Create an object
     97    MyClass* object2 = new MyClass("this is a test");               // Create another object
     98
     99    FunctorMemberPtr functor = createFunctor(&MyClass:contains);    // Create a FunctorMember (note: no object this time)
     100
     101    bool result = (*functor)("World");                              // result == false and an error: "Error: Can't execute FunctorMember, no object set."
     102
     103    bool result = (*functor)(object1, "World");                     // result == true
     104    bool result = (*functor)(object1, "test");                      // result == false
     105    bool result = (*functor)(object2, "test");                      // result == true
     106
     107    functor->setObject(object1);                                    // Assign an object to the FunctorMember
     108
     109    bool result = (*functor)("World");                              // result == true (no error this time, because the object was set using setObject())
     110    @endcode
     111*/
     112
    29113#ifndef _Functor_H__
    30114#define _Functor_H__
    … …  
    40124namespace orxonox
    41125{
    42     const unsigned int MAX_FUNCTOR_ARGUMENTS = 5;
    43 
     126    const unsigned int MAX_FUNCTOR_ARGUMENTS = 5;   ///< The maximum number of parameters of a function that is supported by Functor
     127
     128    namespace detail
     129    {
     130        template <class T>
     131        inline std::string _typeToString() { return "unknown"; }
     132
     133        template <> inline std::string _typeToString<void>()               { return "void"; }
     134        template <> inline std::string _typeToString<int>()                { return "int"; }
     135        template <> inline std::string _typeToString<unsigned int>()       { return "uint"; }
     136        template <> inline std::string _typeToString<char>()               { return "char"; }
     137        template <> inline std::string _typeToString<unsigned char>()      { return "uchar"; }
     138        template <> inline std::string _typeToString<short>()              { return "short"; }
     139        template <> inline std::string _typeToString<unsigned short>()     { return "ushort"; }
     140        template <> inline std::string _typeToString<long>()               { return "long"; }
     141        template <> inline std::string _typeToString<unsigned long>()      { return "ulong"; }
     142        template <> inline std::string _typeToString<long long>()          { return "longlong"; }
     143        template <> inline std::string _typeToString<unsigned long long>() { return "ulonglong"; }
     144        template <> inline std::string _typeToString<float>()              { return "float"; }
     145        template <> inline std::string _typeToString<double>()             { return "double"; }
     146        template <> inline std::string _typeToString<long double>()        { return "longdouble"; }
     147        template <> inline std::string _typeToString<bool>()               { return "bool"; }
     148        template <> inline std::string _typeToString<std::string>()        { return "string"; }
     149        template <> inline std::string _typeToString<Vector2>()            { return "Vector2"; }
     150        template <> inline std::string _typeToString<Vector3>()            { return "Vector3"; }
     151        template <> inline std::string _typeToString<Quaternion>()         { return "Quaternion"; }
     152        template <> inline std::string _typeToString<ColourValue>()        { return "ColourValue"; }
     153        template <> inline std::string _typeToString<Radian>()             { return "Radian"; }
     154        template <> inline std::string _typeToString<Degree>()             { return "Degree"; }
     155    }
     156
     157    /// Returns the name of type @a T as string.
    44158    template <class T>
    45     inline std::string _typeToString() { return "unknown"; }
    46 
    47     template <> inline std::string _typeToString<void>()               { return ""; }
    48     template <> inline std::string _typeToString<int>()                { return "int"; }
    49     template <> inline std::string _typeToString<unsigned int>()       { return "uint"; }
    50     template <> inline std::string _typeToString<char>()               { return "char"; }
    51     template <> inline std::string _typeToString<unsigned char>()      { return "uchar"; }
    52     template <> inline std::string _typeToString<short>()              { return "short"; }
    53     template <> inline std::string _typeToString<unsigned short>()     { return "ushort"; }
    54     template <> inline std::string _typeToString<long>()               { return "long"; }
    55     template <> inline std::string _typeToString<unsigned long>()      { return "ulong"; }
    56     template <> inline std::string _typeToString<long long>()          { return "longlong"; }
    57     template <> inline std::string _typeToString<unsigned long long>() { return "ulonglong"; }
    58     template <> inline std::string _typeToString<float>()              { return "float"; }
    59     template <> inline std::string _typeToString<double>()             { return "double"; }
    60     template <> inline std::string _typeToString<long double>()        { return "longdouble"; }
    61     template <> inline std::string _typeToString<bool>()               { return "bool"; }
    62     template <> inline std::string _typeToString<std::string>()        { return "string"; }
    63     template <> inline std::string _typeToString<Vector2>()            { return "Vector2"; }
    64     template <> inline std::string _typeToString<Vector3>()            { return "Vector3"; }
    65     template <> inline std::string _typeToString<Quaternion>()         { return "Quaternion"; }
    66     template <> inline std::string _typeToString<ColourValue>()        { return "ColourValue"; }
    67     template <> inline std::string _typeToString<Radian>()             { return "Radian"; }
    68     template <> inline std::string _typeToString<Degree>()             { return "Degree"; }
    69 
    70     template <class T>
    71     inline std::string typeToString() { return _typeToString<typename Loki::TypeTraits<T>::UnqualifiedReferredType>(); }
    72 
     159    inline std::string typeToString() { return detail::_typeToString<typename Loki::TypeTraits<T>::UnqualifiedReferredType>(); }
     160
     161    /**
     162        @brief The Functor classes are used to wrap function pointers.
     163
     164        Function-pointers in C++ have a pretty complicated syntax and you can't store
     165        and call them unless you know the exact type. A Functor can be used to wrap
     166        a function-pointer and to store it independent of its type. You can also call
     167        it independently of its parameters by passing the arguments as MultiType. They
     168        are converted automatically to the right type.
     169
     170        Functor is a pure virtual base class.
     171
     172        @see See @ref FunctorExample "Functor.h" for some examples.
     173    */
    73174    class _CoreExport Functor
    74175    {
    … …  
    76177            struct Type
    77178            {
     179                /// Defines the type of a function (static or member)
    78180                enum Enum
    79181                {
    … …  
    84186
    85187        public:
     188            /// Calls the function-pointer with up to five arguments. In case of a member-function, the assigned object-pointer is used to call the function. @return Returns the return-value of the function (if any; MT_Type::Null otherwise)
    86189            virtual MultiType operator()(const MultiType& param1 = MT_Type::Null, const MultiType& param2 = MT_Type::Null, const MultiType& param3 = MT_Type::Null, const MultiType& param4 = MT_Type::Null, const MultiType& param5 = MT_Type::Null) = 0;
    87190
     191            /// Creates a new instance of Functor with the same values like this (used instead of a copy-constructor)
    88192            virtual FunctorPtr clone() = 0;
    89193
     194            /// Returns the type of the function: static or member.
    90195            virtual Type::Enum getType() const = 0;
     196            /// Returns the number of parameters of the function.
    91197            virtual unsigned int getParamCount() const = 0;
     198            /// Returns true if the function has a return-value.
    92199            virtual bool hasReturnvalue() const = 0;
    93200
    94             virtual std::string getTypenameParam(unsigned int param) const = 0;
     201            /// Returns the type-name of the parameter with given index (the first parameter has index 0).
     202            virtual std::string getTypenameParam(unsigned int index) const = 0;
     203            /// Returns the type-name of the return-value.
    95204            virtual std::string getTypenameReturnvalue() const = 0;
    96205
    97             virtual void evaluateParam(unsigned int index, MultiType& param) const = 0;
    98 
    99             virtual void setRawObjectPointer(void* object) {}
    100             virtual void* getRawObjectPointer() const { return 0; }
    101 
    102             template <class F>
    103             inline bool setFunction(F* function)
    104             {
    105                 if (this->getFullIdentifier() == typeid(F*))
    106                 {
    107                     modifyFunctor(this, function);
    108                     return true;
    109                 }
    110                 return false;
    111             }
    112 
     206            /// Converts a given argument to the type of the parameter with given index (the first parameter has index 0).
     207            virtual void evaluateArgument(unsigned int index, MultiType& argument) const = 0;
     208
     209            /// Assigns an object-pointer to the functor which is used to execute a member-function.
     210            virtual void setRawObjectPointer(void* object) = 0;
     211            /// Returns the object-pointer.
     212            virtual void* getRawObjectPointer() const = 0;
     213
     214            /// Returns the full identifier of the function-pointer which is defined as typeid(@a F), where @a F is the type of the stored function-pointer. Used to compare functors.
    113215            virtual const std::type_info& getFullIdentifier() const = 0;
     216            /// Returns an identifier of the header of the function (doesn't include the function's class). Used to compare functors.
    114217            virtual const std::type_info& getHeaderIdentifier() const = 0;
     218            /// Returns an identifier of the header of the function (doesn't include the function's class), but regards only the first @a params parameters. Used to compare functions if an Executor provides default-values for the other parameters.
    115219            virtual const std::type_info& getHeaderIdentifier(unsigned int params) const = 0;
    116220    };
    … …  
    118222    namespace detail
    119223    {
     224        // helper class to determine if a functor is static or not
    120225        template <class O>
    121226        struct FunctorTypeStatic
    … …  
    126231    }
    127232
     233    /**
     234        @brief FunctorMember is a child class of Functor and expands it with an object-pointer, that
     235        is used for member-functions, as well as an overloaded execution operator.
     236
     237        @param O The type of the function's class (or void if it's a static function)
     238
     239        Note that FunctorMember is also used for static functions, but with T = void. FunctorStatic
     240        is a typedef of FunctorMember<void>. The void* object-pointer is ignored in this case.
     241
     242        @see See @ref FunctorExample "Functor.h" for some examples.
     243    */
    128244    template <class O>
    129245    class FunctorMember : public Functor
    130246    {
    131247        public:
     248            /// Constructor: Stores the object-pointer.
    132249            FunctorMember(O* object = 0) : object_(object) {}
    133250
     251            /// Calls the function-pointer with up to five arguments and an object. In case of a static-function, the object can be NULL. @return Returns the return-value of the function (if any; MT_Type::Null otherwise)
    134252            virtual MultiType operator()(O* object, const MultiType& param1 = MT_Type::Null, const MultiType& param2 = MT_Type::Null, const MultiType& param3 = MT_Type::Null, const MultiType& param4 = MT_Type::Null, const MultiType& param5 = MT_Type::Null) = 0;
    135253
     254            // see Functor::operator()()
    136255            MultiType operator()(const MultiType& param1 = MT_Type::Null, const MultiType& param2 = MT_Type::Null, const MultiType& param3 = MT_Type::Null, const MultiType& param4 = MT_Type::Null, const MultiType& param5 = MT_Type::Null)
    137256            {
     257                // call the function if it is static or if an object was assigned
    138258                if (detail::FunctorTypeStatic<O>::result || this->object_)
    139259                    return (*this)(this->object_, param1, param2, param3, param4, param5);
    … …  
    145265            }
    146266
     267            // see Functor::getType()
    147268            Functor::Type::Enum getType() const
    148269                { return detail::FunctorTypeStatic<O>::result ? Functor::Type::Static : Functor::Type::Member; }
    149270
     271            /// Assigns an object-pointer to the functor which is used to execute a member-function.
    150272            inline void setObject(O* object)
    151273                { this->object_ = object;}
     274            /// Returns the object-pointer.
    152275            inline O* getObject() const
    153276                { return this->object_; }
    154277
     278            // see Functor::setRawObjectPointer()
    155279            inline void setRawObjectPointer(void* object)
    156280                { this->object_ = (O*)object; }
     281            // see Functor::getRawObjectPointer()
    157282            inline void* getRawObjectPointer() const
    158283                { return this->object_; }
    159284
    160285        protected:
    161             O* object_;
     286            O* object_;     ///< The stored object-pointer, used to execute a member-function (or NULL for static functions)
    162287    };
    163288
     289    /// FunctorStatic is just a typedef of FunctorMember with @a T = void.
    164290    typedef FunctorMember<void> FunctorStatic;
    165291
     292    /**
     293        @brief FunctorPointer is a child class of FunctorMember and expands it with a function-pointer.
     294        @param F The type of the function-pointer
     295        @param O The type of the function's class (or void if it's a static function)
     296
     297        The template FunctorPointer has an additional template parameter that defines the type
     298        of the function-pointer. This can be handy if you want to get or set the function-pointer.
     299        You can then use a static_cast to cast a Functor to FunctorPointer if you know the type
     300        of the function-pointer.
     301
     302        However FunctorPointer is not aware of the types of the different parameters or the
     303        return value.
     304    */
    166305    template <class F, class O = void>
    167306    class FunctorPointer : public FunctorMember<O>
    168307    {
    169308        public:
     309            /// Constructor: Initializes the base class and stores the function-pointer.
    170310            FunctorPointer(F functionPointer, O* object = 0) : FunctorMember<O>(object), functionPointer_(functionPointer) {}
    171311
     312            /// Changes the function-pointer.
    172313            inline void setFunction(F functionPointer)
    173314                { this->functionPointer_ = functionPointer; }
     315            /// Returns the function-pointer.
    174316            inline F getFunction() const
    175317                { return this->functionPointer_; }
    176318
     319            // see Functor::getFullIdentifier()
    177320            const std::type_info& getFullIdentifier() const
    178321                { return typeid(F); }
    179322
    180323        protected:
    181             F functionPointer_;
     324            F functionPointer_;     ///< The stored function-pointer
    182325    };
    183326
    184327    namespace detail
    185328    {
     329        // Helper class to get the type of the function pointer with the given class, parameters, return-value, and constness
    186330        template <class R, class O, bool isconst, class P1, class P2, class P3, class P4, class P5> struct FunctionPointer                                            { typedef R (O::*Type)(P1, P2, P3, P4, P5); };
    187331        template <class R, class O, class P1, class P2, class P3, class P4, class P5>               struct FunctionPointer<R, O, false, P1, P2, P3, P4, P5>           { typedef R (O::*Type)(P1, P2, P3, P4, P5); };
    … …  
    204348        template <class R>                                                   struct FunctionPointer<R, void, false, void, void, void, void, void> { typedef R (*Type)(); };
    205349
     350        // Helper class, used to call a function-pointer with a given object and parameters and to return its return-value (if available)
    206351        template <class R, class O, bool isconst, class P1, class P2, class P3, class P4, class P5> struct FunctorCaller                                              { static inline MultiType call(typename detail::FunctionPointer<R, O, isconst, P1, P2, P3, P4, P5>::Type functionPointer, O* object, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5) { return (object->*functionPointer)(param1, param2, param3, param4, param5); } };
    207352        template <class R, class O, bool isconst, class P1, class P2, class P3, class P4>           struct FunctorCaller<R, O, isconst, P1, P2, P3, P4, void>         { static inline MultiType call(typename detail::FunctionPointer<R, O, isconst, P1, P2, P3, P4, void>::Type functionPointer, O* object, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5) { return (object->*functionPointer)(param1, param2, param3, param4); } };
    … …  
    229374        template <bool isconst>                                                   struct FunctorCaller<void, void, isconst, void, void, void, void, void> { static inline MultiType call(typename detail::FunctionPointer<void, void, isconst, void, void, void, void, void>::Type functionPointer, void*, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5) { (*functionPointer)(); return MT_Type::Null; } };
    230375
     376        // Helper class, used to identify the header of a function-pointer (independent of its class)
    231377        template <class R, class P1, class P2, class P3, class P4, class P5>
    232378        struct FunctorHeaderIdentifier
    233379        {};
    234380
     381        // Helper class to determine if a function has a returnvalue
    235382        template <class T>
    236383        struct FunctorHasReturnvalue
    … …  
    240387        { enum { result = false }; };
    241388
     389        // Helper class to count the number of parameters
    242390        template <class P1, class P2, class P3, class P4, class P5>
    243391        struct FunctorParamCount
    … …  
    260408    }
    261409
     410    /**
     411        @brief FunctorTemplate is a child class of FunctorPointer and implements all functions
     412        that need to know the exact types of the parameters, return-value, and class.
     413
     414        @param R The type of the return-value of the function
     415        @param O The class of the function
     416        @param isconst True if the function is a const member-function
     417        @param P1 The type of the first parameter
     418        @param P2 The type of the second parameter
     419        @param P3 The type of the third parameter
     420        @param P4 The type of the fourth parameter
     421        @param P5 The type of the fifth parameter
     422
     423        This template has many parameters and is usually not used directly. It is created by
     424        createFunctor(), but only the base-classes Functor, FunctorMember, and FunctorPointer
     425        are used directly. It implements all the virtual functions that are declared by its
     426        base classes.
     427
     428        All template arguments can be void.
     429    */
    262430    template <class R, class O, bool isconst, class P1, class P2, class P3, class P4, class P5>
    263431    class FunctorTemplate : public FunctorPointer<typename detail::FunctionPointer<R, O, isconst, P1, P2, P3, P4, P5>::Type, O>
    264432    {
    265433        public:
     434            /// Constructor: Initializes the base class.
    266435            FunctorTemplate(typename detail::FunctionPointer<R, O, isconst, P1, P2, P3, P4, P5>::Type functionPointer, O* object = 0) : FunctorPointer<typename detail::FunctionPointer<R, O, isconst, P1, P2, P3, P4, P5>::Type, O>(functionPointer, object) {}
    267436
     437            // see FunctorMember::operator()()
    268438            MultiType operator()(O* object, const MultiType& param1 = MT_Type::Null, const MultiType& param2 = MT_Type::Null, const MultiType& param3 = MT_Type::Null, const MultiType& param4 = MT_Type::Null, const MultiType& param5 = MT_Type::Null)
    269439            {
    … …  
    271441            }
    272442
     443            // see Functor::clone()
    273444            FunctorPtr clone()
    274445            {
    … …  
    276447            }
    277448
    278             void evaluateParam(unsigned int index, MultiType& param) const
     449            // see Functor::evaluateArgument()
     450            void evaluateArgument(unsigned int index, MultiType& argument) const
    279451            {
    280452                switch (index)
    281453                {
    282                     case 0: param.convert<P1>(); break;
    283                     case 1: param.convert<P2>(); break;
    284                     case 2: param.convert<P3>(); break;
    285                     case 3: param.convert<P4>(); break;
    286                     case 4: param.convert<P5>(); break;
     454                    case 0: argument.convert<P1>(); break;
     455                    case 1: argument.convert<P2>(); break;
     456                    case 2: argument.convert<P3>(); break;
     457                    case 3: argument.convert<P4>(); break;
     458                    case 4: argument.convert<P5>(); break;
    287459                }
    288460            }
    289461
     462            // see Functor::getParamCount()
    290463            unsigned int getParamCount() const
    291464            {
    … …  
    293466            }
    294467
     468            // see Functor::hasReturnvalue()
    295469            bool hasReturnvalue() const
    296470            {
    … …  
    298472            }
    299473
    300             std::string getTypenameParam(unsigned int param) const
    301             {
    302                 switch (param)
     474            // see Functor::getTypenameParam()
     475            std::string getTypenameParam(unsigned int index) const
     476            {
     477                switch (index)
    303478                {
    304479                    case 0:  return typeToString<P1>();
    … …  
    311486            }
    312487
     488            // see Functor::getTypenameReturnvalue()
    313489            std::string getTypenameReturnvalue() const
    314490            {
    … …  
    316492            }
    317493
     494            // see Functor::getHeaderIdentifier()
    318495            const std::type_info& getHeaderIdentifier() const
    319496            {
    … …  
    321498            }
    322499
     500            // see Functor::getHeaderIdentifier(unsigned int)
    323501            const std::type_info& getHeaderIdentifier(unsigned int params) const
    324502            {
    … …  
    335513    };
    336514
    337     template <class R, class O, class OO, class P1, class P2, class P3, class P4, class P5> inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4, P5), OO* object) { return new FunctorTemplate<R, O, false, P1, P2, P3, P4, P5>(functionPointer, object); }
    338     template <class R, class O, class OO, class P1, class P2, class P3, class P4>           inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4), OO* object)     { return new FunctorTemplate<R, O, false, P1, P2, P3, P4, void>(functionPointer, object); }
    339     template <class R, class O, class OO, class P1, class P2, class P3>                     inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3), OO* object)         { return new FunctorTemplate<R, O, false, P1, P2, P3, void, void>(functionPointer, object); }
    340     template <class R, class O, class OO, class P1, class P2>                               inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2), OO* object)             { return new FunctorTemplate<R, O, false, P1, P2, void, void, void>(functionPointer, object); }
    341     template <class R, class O, class OO, class P1>                                         inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1), OO* object)                 { return new FunctorTemplate<R, O, false, P1, void, void, void, void>(functionPointer, object); }
    342     template <class R, class O, class OO>                                                   inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(), OO* object)                   { return new FunctorTemplate<R, O, false, void, void, void, void, void>(functionPointer, object); }
    343     template <class R, class O, class OO, class P1, class P2, class P3, class P4, class P5> inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4, P5) const, OO* object) { return new FunctorTemplate<R, O, true, P1, P2, P3, P4, P5>(functionPointer, object); }
    344     template <class R, class O, class OO, class P1, class P2, class P3, class P4>           inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4) const, OO* object)     { return new FunctorTemplate<R, O, true, P1, P2, P3, P4, void>(functionPointer, object); }
    345     template <class R, class O, class OO, class P1, class P2, class P3>                     inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3) const, OO* object)         { return new FunctorTemplate<R, O, true, P1, P2, P3, void, void>(functionPointer, object); }
    346     template <class R, class O, class OO, class P1, class P2>                               inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2) const, OO* object)             { return new FunctorTemplate<R, O, true, P1, P2, void, void, void>(functionPointer, object); }
    347     template <class R, class O, class OO, class P1>                                         inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1) const, OO* object)                 { return new FunctorTemplate<R, O, true, P1, void, void, void, void>(functionPointer, object); }
    348     template <class R, class O, class OO>                                                   inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)() const, OO* object)                   { return new FunctorTemplate<R, O, true, void, void, void, void, void>(functionPointer, object); }
    349 
    350     template <class R, class O, class P1, class P2, class P3, class P4, class P5> inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4, P5)) { return new FunctorTemplate<R, O, false, P1, P2, P3, P4, P5>(functionPointer); }
    351     template <class R, class O, class P1, class P2, class P3, class P4>           inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4))     { return new FunctorTemplate<R, O, false, P1, P2, P3, P4, void>(functionPointer); }
    352     template <class R, class O, class P1, class P2, class P3>                     inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3))         { return new FunctorTemplate<R, O, false, P1, P2, P3, void, void>(functionPointer); }
    353     template <class R, class O, class P1, class P2>                               inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2))             { return new FunctorTemplate<R, O, false, P1, P2, void, void, void>(functionPointer); }
    354     template <class R, class O, class P1>                                         inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1))                 { return new FunctorTemplate<R, O, false, P1, void, void, void, void>(functionPointer); }
    355     template <class R, class O>                                                   inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)())                   { return new FunctorTemplate<R, O, false, void, void, void, void, void>(functionPointer); }
    356     template <class R, class O, class P1, class P2, class P3, class P4, class P5> inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4, P5) const) { return new FunctorTemplate<R, O, true, P1, P2, P3, P4, P5>(functionPointer); }
    357     template <class R, class O, class P1, class P2, class P3, class P4>           inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4) const)     { return new FunctorTemplate<R, O, true, P1, P2, P3, P4, void>(functionPointer); }
    358     template <class R, class O, class P1, class P2, class P3>                     inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3) const)         { return new FunctorTemplate<R, O, true, P1, P2, P3, void, void>(functionPointer); }
    359     template <class R, class O, class P1, class P2>                               inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2) const)             { return new FunctorTemplate<R, O, true, P1, P2, void, void, void>(functionPointer); }
    360     template <class R, class O, class P1>                                         inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1) const)                 { return new FunctorTemplate<R, O, true, P1, void, void, void, void>(functionPointer); }
    361     template <class R, class O>                                                   inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)() const)                   { return new FunctorTemplate<R, O, true, void, void, void, void, void>(functionPointer); }
    362 
    363     template <class R, class P1, class P2, class P3, class P4, class P5> inline FunctorStaticPtr createFunctor(R (*functionPointer)(P1, P2, P3, P4, P5)) { return new FunctorTemplate<R, void, false, P1, P2, P3, P4, P5>(functionPointer); }
    364     template <class R, class P1, class P2, class P3, class P4>           inline FunctorStaticPtr createFunctor(R (*functionPointer)(P1, P2, P3, P4))     { return new FunctorTemplate<R, void, false, P1, P2, P3, P4, void>(functionPointer); }
    365     template <class R, class P1, class P2, class P3>                     inline FunctorStaticPtr createFunctor(R (*functionPointer)(P1, P2, P3))         { return new FunctorTemplate<R, void, false, P1, P2, P3, void, void>(functionPointer); }
    366     template <class R, class P1, class P2>                               inline FunctorStaticPtr createFunctor(R (*functionPointer)(P1, P2))             { return new FunctorTemplate<R, void, false, P1, P2, void, void, void>(functionPointer); }
    367     template <class R, class P1>                                         inline FunctorStaticPtr createFunctor(R (*functionPointer)(P1))                 { return new FunctorTemplate<R, void, false, P1, void, void, void, void>(functionPointer); }
    368     template <class R>                                                   inline FunctorStaticPtr createFunctor(R (*functionPointer)())                   { return new FunctorTemplate<R, void, false, void, void, void, void, void>(functionPointer); }
     515    template <class R, class O, class OO, class P1, class P2, class P3, class P4, class P5> inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4, P5), OO* object) { return new FunctorTemplate<R, O, false, P1, P2, P3, P4, P5>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     516    template <class R, class O, class OO, class P1, class P2, class P3, class P4>           inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4), OO* object)     { return new FunctorTemplate<R, O, false, P1, P2, P3, P4, void>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     517    template <class R, class O, class OO, class P1, class P2, class P3>                     inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3), OO* object)         { return new FunctorTemplate<R, O, false, P1, P2, P3, void, void>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     518    template <class R, class O, class OO, class P1, class P2>                               inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2), OO* object)             { return new FunctorTemplate<R, O, false, P1, P2, void, void, void>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     519    template <class R, class O, class OO, class P1>                                         inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1), OO* object)                 { return new FunctorTemplate<R, O, false, P1, void, void, void, void>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     520    template <class R, class O, class OO>                                                   inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(), OO* object)                   { return new FunctorTemplate<R, O, false, void, void, void, void, void>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     521    template <class R, class O, class OO, class P1, class P2, class P3, class P4, class P5> inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4, P5) const, OO* object) { return new FunctorTemplate<R, O, true, P1, P2, P3, P4, P5>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     522    template <class R, class O, class OO, class P1, class P2, class P3, class P4>           inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4) const, OO* object)     { return new FunctorTemplate<R, O, true, P1, P2, P3, P4, void>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     523    template <class R, class O, class OO, class P1, class P2, class P3>                     inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3) const, OO* object)         { return new FunctorTemplate<R, O, true, P1, P2, P3, void, void>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     524    template <class R, class O, class OO, class P1, class P2>                               inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2) const, OO* object)             { return new FunctorTemplate<R, O, true, P1, P2, void, void, void>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     525    template <class R, class O, class OO, class P1>                                         inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1) const, OO* object)                 { return new FunctorTemplate<R, O, true, P1, void, void, void, void>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     526    template <class R, class O, class OO>                                                   inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)() const, OO* object)                   { return new FunctorTemplate<R, O, true, void, void, void, void, void>(functionPointer, object); }   ///< Creates a new FunctorMember with the given function-pointer and an assigned object
     527
     528    template <class R, class O, class P1, class P2, class P3, class P4, class P5> inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4, P5)) { return new FunctorTemplate<R, O, false, P1, P2, P3, P4, P5>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     529    template <class R, class O, class P1, class P2, class P3, class P4>           inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4))     { return new FunctorTemplate<R, O, false, P1, P2, P3, P4, void>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     530    template <class R, class O, class P1, class P2, class P3>                     inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3))         { return new FunctorTemplate<R, O, false, P1, P2, P3, void, void>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     531    template <class R, class O, class P1, class P2>                               inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2))             { return new FunctorTemplate<R, O, false, P1, P2, void, void, void>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     532    template <class R, class O, class P1>                                         inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1))                 { return new FunctorTemplate<R, O, false, P1, void, void, void, void>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     533    template <class R, class O>                                                   inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)())                   { return new FunctorTemplate<R, O, false, void, void, void, void, void>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     534    template <class R, class O, class P1, class P2, class P3, class P4, class P5> inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4, P5) const) { return new FunctorTemplate<R, O, true, P1, P2, P3, P4, P5>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     535    template <class R, class O, class P1, class P2, class P3, class P4>           inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3, P4) const)     { return new FunctorTemplate<R, O, true, P1, P2, P3, P4, void>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     536    template <class R, class O, class P1, class P2, class P3>                     inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2, P3) const)         { return new FunctorTemplate<R, O, true, P1, P2, P3, void, void>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     537    template <class R, class O, class P1, class P2>                               inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1, P2) const)             { return new FunctorTemplate<R, O, true, P1, P2, void, void, void>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     538    template <class R, class O, class P1>                                         inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)(P1) const)                 { return new FunctorTemplate<R, O, true, P1, void, void, void, void>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     539    template <class R, class O>                                                   inline FunctorMemberPtr<O> createFunctor(R (O::*functionPointer)() const)                   { return new FunctorTemplate<R, O, true, void, void, void, void, void>(functionPointer); }   ///< Creates a new FunctorMember with the given function-pointer
     540
     541    template <class R, class P1, class P2, class P3, class P4, class P5> inline FunctorStaticPtr createFunctor(R (*functionPointer)(P1, P2, P3, P4, P5)) { return new FunctorTemplate<R, void, false, P1, P2, P3, P4, P5>(functionPointer); }   ///< Creates a new Functor with the given function-pointer
     542    template <class R, class P1, class P2, class P3, class P4>           inline FunctorStaticPtr createFunctor(R (*functionPointer)(P1, P2, P3, P4))     { return new FunctorTemplate<R, void, false, P1, P2, P3, P4, void>(functionPointer); }   ///< Creates a new Functor with the given function-pointer
     543    template <class R, class P1, class P2, class P3>                     inline FunctorStaticPtr createFunctor(R (*functionPointer)(P1, P2, P3))         { return new FunctorTemplate<R, void, false, P1, P2, P3, void, void>(functionPointer); }   ///< Creates a new Functor with the given function-pointer
     544    template <class R, class P1, class P2>                               inline FunctorStaticPtr createFunctor(R (*functionPointer)(P1, P2))             { return new FunctorTemplate<R, void, false, P1, P2, void, void, void>(functionPointer); }   ///< Creates a new Functor with the given function-pointer
     545    template <class R, class P1>                                         inline FunctorStaticPtr createFunctor(R (*functionPointer)(P1))                 { return new FunctorTemplate<R, void, false, P1, void, void, void, void>(functionPointer); }   ///< Creates a new Functor with the given function-pointer
     546    template <class R>                                                   inline FunctorStaticPtr createFunctor(R (*functionPointer)())                   { return new FunctorTemplate<R, void, false, void, void, void, void, void>(functionPointer); }   ///< Creates a new Functor with the given function-pointer
    369547}
    370548

  • code/trunk/src/libraries/core/command/FunctorPtr.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command FunctorExecutor
     32    @brief Typedefs and definitions of FunctorPtr, FunctorMemberPtr, FunctorStaticPtr, and FunctorPointerPtr
     33
     34    Instances of orxonox::Functor are usually managed by an orxonox::SharedPtr. This ensures
     35    that Functors will be destroyed after usage. To make things easier, there's a typedef
     36    that defines FunctorPtr as SharedPtr<Functor>.
     37
     38    Because there's not only orxonox::Functor, but also orxonox::FunctorStatic, and
     39    orxonox::FunctorMember, the shared pointers need to store them all and also reflect
     40    their hierarchy - FunctorStatic and FunctorMember should not be mixed, but both can
     41    be converted to Functor. This is achieved by using orxonox::SharedChildPtr.
     42
     43    Because it's not possible to use a typedef for a template, we have to define the
     44    helper class FunctorMemberPtr<T> that makes it easier to use FunctorMember. The
     45    same is also done for FunctorPointerPtr<T>, which can be converted to both,
     46    FunctorMemberPtr<T> as well as FunctorPtr.
     47*/
     48
    2949#ifndef _FunctorPtr_H__
    3050#define _FunctorPtr_H__
    … …  
    3555namespace orxonox
    3656{
     57    /// FunctorPtr is just a typedef of SharedPtr
    3758    typedef SharedPtr<Functor> FunctorPtr;
    3859
     60    /// It's not possible to use a typedef for FunctorMemberPtr<T>, so we have to create a child-class instead. It inherits all functions from SharedChildPtr, but needs to (re-)implement some constructors.
    3961    template <class T>
    4062    class FunctorMemberPtr : public SharedChildPtr<FunctorMember<T>, FunctorPtr>
    … …  
    4668    };
    4769
     70    /// FunctorStaticPtr is just FunctorMemberPtr with @a T = void
    4871    typedef FunctorMemberPtr<void> FunctorStaticPtr;
    4972
     73    /// It's not possible to use a typedef for FunctorPointerPtr<T>, so we have to create a child-class instead. It inherits all functions from SharedChildPtr, but needs to (re-)implement some constructors.
    5074    template <class F, class T>
    5175    class FunctorPointerPtr : public SharedChildPtr<FunctorPointer<F, T>, FunctorMemberPtr<T> >

  • code/trunk/src/libraries/core/command/IOConsole.h

    r7287 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command ShellConsole
     32*/
     33
    2934#include "OrxonoxConfig.h"
    3035

  • code/trunk/src/libraries/core/command/IOConsolePOSIX.h

    r7287 r7401  
    2727 *
    2828 */
     29
     30/**
     31    @file
     32    @ingroup Command ShellConsole
     33*/
    2934
    3035#ifndef _IOConsole_H__

  • code/trunk/src/libraries/core/command/IOConsoleWindows.h

    r7287 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup Command ShellConsole
     32*/
    2833
    2934#ifndef _IOConsole_H__

  • code/trunk/src/libraries/core/command/IRC.cc

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the IRC class and the IRC console commands.
     32*/
     33
    2934#include "IRC.h"
    3035
    … …  
    3944namespace orxonox
    4045{
    41     static const unsigned int IRC_TCL_THREADID  = 1421421421;
     46    static const unsigned int IRC_TCL_THREADID  = 1421421421;   ///< The ID of the thread in TclThreadManager that is used for the IRC connection
    4247
    4348    SetConsoleCommand("IRC", "say",  &IRC::say);
    … …  
    4550    SetConsoleCommand("IRC", "nick", &IRC::nick);
    4651
     52    /**
     53        @brief Returns the only existing instance of IRC.
     54    */
     55    IRC& IRC::getInstance()
     56    {
     57        static IRC instance;
     58        return instance;
     59    }
     60
     61    /**
     62        @brief Constructor: Doesn't yet connect to IRC nor does it create a Tcl interpreter.
     63        The IRC object will automatically connect to the IRC server if one of the registered
     64        console commands is used the first time.
     65    */
    4766    IRC::IRC()
    4867    {
    … …  
    5069    }
    5170
     71    /**
     72        @brief Creates and initializes a new multithreaded Tcl-interpreter and defines some callbacks to display IRC-messages in the console.
     73    */
    5274    void IRC::initialize()
    5375    {
    … …  
    7092    }
    7193
    72     IRC& IRC::getInstance()
    73     {
    74         static IRC instance;
    75         return instance;
    76     }
    77 
     94    /**
     95        @brief Executes a Tcl-command on the Tcl-interpreter.
     96    */
    7897    bool IRC::eval(const std::string& command)
    7998    {
    … …  
    96115    }
    97116
     117    /// Console command: Sends a message to the current channel on the IRC server.
    98118    void IRC::say(const std::string& message)
    99119    {
    … …  
    102122    }
    103123
     124    /// Console command: Sends a message to a given channel or nickname on the IRC server.
    104125    void IRC::msg(const std::string& channel, const std::string& message)
    105126    {
    … …  
    108129    }
    109130
     131    /// Console command: Changes the nickname on the IRC server.
    110132    void IRC::nick(const std::string& nickname)
    111133    {
    … …  
    114136    }
    115137
     138    /// Tcl-callback: Prints a message that was received from the current IRC channel to the console.
    116139    void IRC::tcl_say(Tcl::object const &channel, Tcl::object const &nick, Tcl::object const &args)
    117140    {
    … …  
    119142    }
    120143
     144    /// Tcl-callback: Prints a private message that was received from a user to the console.
    121145    void IRC::tcl_privmsg(Tcl::object const &query, Tcl::object const &nick, Tcl::object const &args)
    122146    {
    … …  
    124148    }
    125149
     150    /// Tcl-callback: Prints an action-message (usually /me ...) that was received from the current IRC channel to the console.
    126151    void IRC::tcl_action(Tcl::object const &channel, Tcl::object const &nick, Tcl::object const &args)
    127152    {
    … …  
    129154    }
    130155
     156    /// Tcl-callback: Prints all kinds of information that were received from the IRC server or channel (connection info, join, part, modes, ...) to the console.
    131157    void IRC::tcl_info(Tcl::object const &channel, Tcl::object const &args)
    132158    {

  • code/trunk/src/libraries/core/command/IRC.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command Tcl
     32    @brief Declaration of IRC helper class, used for IRC connections using Tcl.
     33*/
     34
    2935#ifndef _IRC_H__
    3036#define _IRC_H__
    … …  
    3642namespace orxonox
    3743{
     44    /**
     45        @brief The IRC class creates a Tcl-thread (see TclThreadManager) and connects to an IRC server.
     46        It provides different console commands to send messages and to perform other actions on the IRC server.
     47    */
    3848    class _CoreExport IRC
    3949    {
    … …  
    5565
    5666            IRC();
    57             IRC(const IRC& other);
    58             ~IRC() {}
     67            IRC(const IRC& other);              ///< Copy-constructor: Not implemented
     68            ~IRC() {}                           ///< Destructor
    5969
    60             Tcl::interpreter* interpreter_;
    61             std::string nickname_;
     70            Tcl::interpreter* interpreter_;     ///< The Tcl interpreter that is used for the IRC connection
     71            std::string nickname_;              ///< The user's nickname on the IRC server
    6272    };
    6373}

  • code/trunk/src/libraries/core/command/Shell.cc

    r7284 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @brief Implementation of the Shell class.
     32*/
    2833
    2934#include "Shell.h"
    … …  
    4853    unsigned int Shell::cacheSize_s;
    4954
     55    /**
     56        @brief Constructor: Initializes the values and registers itself at OutputHandler.
     57        @param consoleName The name of the shell - used to define the name of the soft-debug-level config-value
     58        @param bScrollable If true, the user is allowed to scroll through the output-lines
     59    */
    5060    Shell::Shell(const std::string& consoleName, bool bScrollable)
    5161        : OutputListener(consoleName)
    … …  
    8898    }
    8999
     100    /**
     101        @brief Destructor: Unregisters the shell from OutputHandler.
     102    */
    90103    Shell::~Shell()
    91104    {
    … …  
    94107    }
    95108
     109    /**
     110        @brief Defines the config values.
     111    */
    96112    void Shell::setConfigValues()
    97113    {
    … …  
    113129    }
    114130
     131    /**
     132        @brief Config-value callback: Called when the history offset has changed in the config-file.
     133    */
    115134    void Shell::commandHistoryOffsetChanged()
    116135    {
    … …  
    119138    }
    120139
     140    /**
     141        @brief Config-value callback: Called when the length of the command history has changed in the config-file.
     142    */
    121143    void Shell::commandHistoryLengthChanged()
    122144    {
    … …  
    131153    }
    132154
     155    /**
     156        @brief Registers this object as listener for different key-events at the input buffer.
     157    */
    133158    void Shell::configureInputBuffer()
    134159    {
    … …  
    159184    }
    160185
    161     /*
    162     void Shell::history()
    163     {
    164         Shell& instance = Shell::getInstance();
    165 
    166         for (unsigned int i = instance.historyOffset_; i < instance.commandHistory_.size(); ++i)
    167             instance.addOutput(instance.commandHistory_[i] + '\n', -1);
    168         for (unsigned int i =  0; i < instance.historyOffset_; ++i)
    169             instance.addOutput(instance.commandHistory_[i] + '\n', -1);
    170     }
    171     */
    172 
     186    /**
     187        @brief Registers a shell listener which listens for changes in this shell.
     188    */
    173189    void Shell::registerListener(ShellListener* listener)
    174190    {
    … …  
    176192    }
    177193
     194    /**
     195        @brief Unregisters a shell listener.
     196    */
    178197    void Shell::unregisterListener(ShellListener* listener)
    179198    {
    … …  
    187206    }
    188207
     208    /**
     209        @brief Changes the position of the cursor in the input buffer.
     210    */
    189211    void Shell::setCursorPosition(unsigned int cursor)
    190212    {
    … …  
    193215    }
    194216
     217    /**
     218        @brief Sends output to the internal output buffer.
     219    */
    195220    void Shell::addOutput(const std::string& text, LineType type)
    196221    {
    … …  
    199224    }
    200225
     226    /**
     227        @brief Clears the list of output-lines.
     228    */
    201229    void Shell::clearOutput()
    202230    {
    … …  
    210238    }
    211239
     240    /**
     241        @brief Returns an iterator to the newest line of output (except if the user is currently scrolling through the output).
     242    */
    212243    Shell::LineList::const_iterator Shell::getNewestLineIterator() const
    213244    {
    … …  
    218249    }
    219250
     251    /**
     252        @brief Returns the end() iterator of the list of output-lines.
     253    */
    220254    Shell::LineList::const_iterator Shell::getEndIterator() const
    221255    {
    … …  
    223257    }
    224258
     259    /**
     260        @brief Adds a command to the history of entered commands and writes it to the config-file.
     261    */
    225262    void Shell::addToHistory(const std::string& command)
    226263    {
    … …  
    237274    }
    238275
     276    /**
     277        @brief Returns a command from the history of entered commands (usually the most recent history entry, but the user can scroll through the history).
     278    */
    239279    const std::string& Shell::getFromHistory() const
    240280    {
    … …  
    246286    }
    247287
     288    /**
     289        @brief Called by OutputHandler or internally whenever output was sent to the output buffer. Reads from the buffer and writes the new output-lines to the list.
     290    */
    248291    void Shell::outputChanged(int lineType)
    249292    {
    … …  
    251294        do
    252295        {
     296            // get the first line from the buffer
    253297            std::string output;
    254298            std::getline(this->outputBuffer_, output);
    255299
     300            // check the state of the buffer
    256301            bool eof = this->outputBuffer_.eof();
    257302            bool fail = this->outputBuffer_.fail();
    258303            if (eof)
    259                 this->outputBuffer_.flush();
     304                this->outputBuffer_.flush(); // check if more output was received in the meantime
    260305            if (eof || fail)
    261                 this->outputBuffer_.clear();
     306                this->outputBuffer_.clear(); // clear the error flags
     307
     308            // the line is terminated with a line-break if neither an error occurred nor the end of the file was reached
    262309            newline = (!eof && !fail);
    263310
     311            // no output retrieved - break the loop
    264312            if (!newline && output.empty())
    265313                break;
    266314
     315            // check if the last line was terminated with a line-break
    267316            if (this->bFinishedLastLine_)
    268317            {
     318                // yes it was - push the new line to the list
    269319                this->outputLines_.push_front(std::make_pair(output, static_cast<LineType>(lineType)));
    270320
     321                // adjust the scroll position if needed
    271322                if (this->scrollPosition_)
    272323                    this->scrollPosition_++;
    273324                else
    274325                    this->scrollIterator_ = this->outputLines_.begin();
    275 
    276                 this->bFinishedLastLine_ = newline;
    277326
    278327                if (!this->scrollPosition_)
    … …  
    281330            else
    282331            {
     332                // no it wasn't - add the new output to the last line
    283333                this->outputLines_.front().first += output;
    284                 this->bFinishedLastLine_ = newline;
    285334                this->updateListeners<&ShellListener::onlyLastLineChanged>();
    286335            }
     336
     337            // remember if the last line was terminated with a line-break
    287338            this->bFinishedLastLine_ = newline;
    288339
    289         } while (newline);
    290     }
    291 
     340        } while (newline); // loop as long as more lines are in the buffer
     341    }
     342
     343    /**
     344        @brief Clears the text in the input buffer.
     345    */
    292346    void Shell::clearInput()
    293347    {
    … …  
    298352    }
    299353
    300     void Shell::setPromptPrefix(const std::string& str)
    301     {
    302     }
    303 
    304354
    305355    // ##########################################
    … …  
    307357    // ##########################################
    308358
     359    /// InputBuffer callback: Called if the input changes.
    309360    void Shell::inputChanged()
    310361    {
    … …  
    313364    }
    314365
     366    /// InputBuffer callback: Called if a key was pressed that executes a command (usually [return]).
    315367    void Shell::execute()
    316368    {
    … …  
    340392    }
    341393
     394    /// InputBuffer callback: Called if a key was pressed that shows hints and completes a command (usually [tab]).
    342395    void Shell::hintAndComplete()
    343396    {
    … …  
    349402    }
    350403
     404    /// InputBuffer callback: Called if a key was pressed that deletes the character before the cursor (usually [backspace]).
    351405    void Shell::backspace()
    352406    {
    … …  
    356410    }
    357411
    358     void Shell::exit()
    359     {
    360         if (this->inputBuffer_->getSize() > 0)
    361         {
    362             this->clearInput();
    363             return;
    364         }
    365 
    366         this->clearInput();
    367         this->scrollPosition_ = 0;
    368         this->scrollIterator_ = this->outputLines_.begin();
    369 
    370         this->updateListeners<&ShellListener::exit>();
    371     }
    372 
     412    /// InputBuffer callback: Called if a key was pressed that deletes the character after the cursor (usually [delete]).
    373413    void Shell::deleteChar()
    374414    {
    … …  
    377417    }
    378418
     419    /// InputBuffer callback: Called if a key was pressed that moves the input cursor the right (usually [arrow right]).
    379420    void Shell::cursorRight()
    380421    {
    … …  
    383424    }
    384425
     426    /// InputBuffer callback: Called if a key was pressed that moves the input cursor the left (usually [arrow left]).
    385427    void Shell::cursorLeft()
    386428    {
    … …  
    389431    }
    390432
     433    /// InputBuffer callback: Called if a key was pressed that moves the input cursor the end of the input line (usually [end]).
    391434    void Shell::cursorEnd()
    392435    {
    … …  
    395438    }
    396439
     440    /// InputBuffer callback: Called if a key was pressed that moves the input cursor the beginning of the input line (usually [home]).
    397441    void Shell::cursorHome()
    398442    {
    … …  
    401445    }
    402446
     447    /// InputBuffer callback: Called if a key was pressed that scrolls upwards through the history of entered commands (usually [arrow up]).
    403448    void Shell::historyUp()
    404449    {
    … …  
    410455    }
    411456
     457    /// InputBuffer callback: Called if a key was pressed that scrolls downwards through the history of entered commands (usually [arrow down]).
    412458    void Shell::historyDown()
    413459    {
    … …  
    419465    }
    420466
     467    /// InputBuffer callback: Called if a key was pressed that searches upwards through the history for a command stat starts like the one the user is currently typing (usually [page up]). Only if the shell is not scrollable.
    421468    void Shell::historySearchUp()
    422469    {
    … …  
    437484    }
    438485
     486    /// InputBuffer callback: Called if a key was pressed that searches downwards through the history for a command stat starts like the one the user is currently typing (usually [page down]). Only if the shell is not scrollable.
    439487    void Shell::historySearchDown()
    440488    {
    … …  
    455503    }
    456504
     505    /// InputBuffer callback: Called if a key was pressed that scrolls upwards through the output history (usually [page up]). Only if the shell is scrollable.
    457506    void Shell::scrollUp()
    458507    {
    … …  
    466515    }
    467516
     517    /// InputBuffer callback: Called if a key was pressed that scrolls downwards through the output history (usually [page down]). Only if the shell is scrollable.
    468518    void Shell::scrollDown()
    469519    {
    … …  
    476526        }
    477527    }
     528
     529    /// InputBuffer callback: Called if a key was pressed that clears the text in the input buffer or closes the shell (usually [esc]).
     530    void Shell::exit()
     531    {
     532        if (this->inputBuffer_->getSize() > 0)
     533        {
     534            this->clearInput();
     535            return;
     536        }
     537
     538        this->clearInput();
     539        this->scrollPosition_ = 0;
     540        this->scrollIterator_ = this->outputLines_.begin();
     541
     542        this->updateListeners<&ShellListener::exit>();
     543    }
    478544}

  • code/trunk/src/libraries/core/command/Shell.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @defgroup ShellConsole Shell and console
     31    @ingroup Command
     32*/
     33
     34/**
     35    @file
     36    @ingroup Command ShellConsole
     37    @brief Declaration of the Shell and ShellListener classes.
     38*/
     39
    2940#ifndef _Shell_H__
    3041#define _Shell_H__
    … …  
    4354namespace orxonox
    4455{
     56    /**
     57        @brief An interface, used to get a notification if the state of the Shell changes.
     58    */
    4559    class _CoreExport ShellListener
    4660    {
    … …  
    5165
    5266        private:
    53             virtual void linesChanged() {}
    54             virtual void onlyLastLineChanged() {}
    55             virtual void lineAdded() {}
    56             virtual void inputChanged() {}
    57             virtual void cursorChanged() {}
    58             virtual void executed() {}
    59             virtual void exit() {}
     67            virtual void linesChanged() {}          ///< Called if all output-lines have changed
     68            virtual void onlyLastLineChanged() {}   ///< Called if only the last output-line has changed
     69            virtual void lineAdded() {}             ///< Called if a new line was added to the output
     70            virtual void inputChanged() {}          ///< Called if the input has changed
     71            virtual void cursorChanged() {}         ///< Called if the cursor in the input line has changed
     72            virtual void executed() {}              ///< Called if a command from the input line was executed
     73            virtual void exit() {}                  ///< Called if the console should be closed
    6074    };
    6175
    6276
     77    /**
     78        @brief The Shell is the logical component of the console that displays output to the user and allows him to enter commands.
     79
     80        The Shell gathers output sent from OutputHandler by inheriting from OutputListener.
     81        The output-lines are stored in the shell, so they can be displayed in a graphical
     82        console. Additionally the Shell has an InputBuffer which is needed by the user to
     83        enter commands.
     84
     85        Different graphical consoles build upon a Shell, for example InGameConsole and IOConsole.
     86    */
    6387    class _CoreExport Shell : virtual public OrxonoxClass, public OutputListener
    6488    {
    6589        public:
     90            /// Defines the type of a line of text in the Shell - some types depend on the output level, others are of internal use.
    6691            enum LineType
    6792            {
    … …  
    88113            void unregisterListener(ShellListener* listener);
    89114
     115            /// Returns the input buffer which is needed by the user to enter text into the shell.
    90116            inline InputBuffer* getInputBuffer()
    91117                { return this->inputBuffer_; }
    92118
    93119            void setCursorPosition(unsigned int cursor);
     120            /// Returns the current position of the cursor in the input buffer.
    94121            inline unsigned int getCursorPosition() const
    95122                { return this->inputBuffer_->getCursorPosition(); }
    96123
     124            /// Returns the current content of the input buffer (the text which was entered by the user)
    97125            inline const std::string& getInput() const
    98126                { return this->inputBuffer_->get(); }
    … …  
    105133            void clearOutput();
    106134
     135            /// Returns the number of output-lines that are displayed in the shell.
    107136            inline unsigned int getNumLines() const
    108137                { return this->outputLines_.size(); }
     138            /// Returns the line which is currently viewed if the user scrolls through the older output-lines in the shell.
    109139            inline unsigned int getScrollPosition() const
    110140                { return this->scrollPosition_; }
    111141
    112             inline const std::string& getPromptPrefix() const { return this->promptPrefix_; }
    113             void setPromptPrefix(const std::string& str);
    114 
     142            /// Returns the cache size that is actually used in CommandExecutor, but placed here for better readability of the config file.
    115143            static inline unsigned int getCacheSize()
    116144                { return Shell::cacheSize_s; }
    … …  
    145173            void exit();
    146174
     175            /// Iterates through all registered @ref ShellListener "shell listeners" and calls the function @a F.
    147176            template <void (ShellListener::*F)()>
    148177            void updateListeners()
    … …  
    152181            }
    153182
    154             std::list<ShellListener*> listeners_;
    155             InputBuffer*              inputBuffer_;
    156             std::stringstream         outputBuffer_;
    157             bool                      bFinishedLastLine_;
    158             LineList                  outputLines_;
    159             LineList::const_iterator  scrollIterator_;
    160             unsigned int              scrollPosition_;
    161             unsigned int              historyPosition_;
    162 
    163             std::string               promptPrefix_;
    164             const std::string         consoleName_;
    165             const bool                bScrollable_;
     183            std::list<ShellListener*> listeners_;           ///< The registered shell listeners
     184            InputBuffer*              inputBuffer_;         ///< The input buffer that is needed by the user to enter text
     185            std::stringstream         outputBuffer_;        ///< The output buffer that is used to retrieve lines of output from OutputListener
     186            bool                      bFinishedLastLine_;   ///< Stores if the most recent output-line was terminated with a line-break or if more output is expected for this line
     187            LineList                  outputLines_;         ///< A list of all output-lines that were displayed in the shell so far
     188            LineList::const_iterator  scrollIterator_;      ///< An iterator to an entry of the list of output-lines, changes if the user scrolls through the output in the shell
     189            unsigned int              scrollPosition_;      ///< The number of the line that is currently being referenced by scrollIterator_
     190            unsigned int              historyPosition_;     ///< If the user scrolls through the history of entered commands (stored in commandHistory_), this contains the currently viewed history entry
     191
     192            const std::string         consoleName_;         ///< The name of this shell - used to define the name of the soft-debug-level config-value
     193            const bool                bScrollable_;         ///< If true, the user can scroll through the output-lines
    166194
    167195            // Config values
    168             unsigned int              maxHistoryLength_;
    169             unsigned int              historyOffset_;
    170             std::vector<std::string>  commandHistory_;
    171             int                       softDebugLevel_;
    172             static unsigned int       cacheSize_s;
     196            unsigned int              maxHistoryLength_;    ///< The maximum number of saved commands
     197            unsigned int              historyOffset_;       ///< The command history is a circular buffer, this variable defines the current write-offset
     198            std::vector<std::string>  commandHistory_;      ///< The history of commands that were entered by the user
     199            int                       softDebugLevel_;      ///< The maximum level of output that is displayed in the shell (will be passed to OutputListener to filter output)
     200            static unsigned int       cacheSize_s;          ///< The maximum cache size of the CommandExecutor - this is stored here for better readability of the config file and because CommandExecutor is no OrxonoxClass
    173201    };
    174202}

  • code/trunk/src/libraries/core/command/TclBind.cc

    r7284 r7401  
    4949    TclBind* TclBind::singletonPtr_s = 0;
    5050
     51    /**
     52        @brief Constructor: Initializes the Tcl-interpreter with a given data path.
     53        @param datapath Path to the directory that contains the Orxonox-specific Tcl-files
     54    */
    5155    TclBind::TclBind(const std::string& datapath)
    5256    {
    … …  
    5660    }
    5761
     62    /**
     63        @brief Destructor: Deletes the Tcl-interpreter.
     64    */
    5865    TclBind::~TclBind()
    5966    {
    … …  
    6269    }
    6370
     71    /**
     72        @brief Defines the path to the directory that contains the Orxonox-specific Tcl-files and initializes the Tcl-interpreter accordingly.
     73    */
    6474    void TclBind::setDataPath(const std::string& datapath)
    6575    {
    … …  
    7181    }
    7282
     83    /**
     84        @brief Creates and initializes the Tcl-interpreter by registering all callbacks and defining some useful functions.
     85    */
    7386    void TclBind::initializeTclInterpreter()
    7487    {
    … …  
    96109    }
    97110
     111    /**
     112        @brief Creates and initializes a new Tcl-interpreter and calls the Orxonox-specific
     113        init.tcl script that defines some special functions which are required by Orxonox.
     114    */
    98115    Tcl::interpreter* TclBind::createTclInterpreter()
    99116    {
    … …  
    116133    }
    117134
     135    /**
     136        @brief Returns the path to the Tcl-library (not the Orxonox-specific Tcl-files).
     137    */
    118138    std::string TclBind::getTclLibraryPath()
    119139    {
    … …  
    128148    }
    129149
     150    /**
     151        @brief Callback: Used to send an Orxonox-command from Tcl to the CommandExecutor and to send its result back to Tcl.
     152    */
    130153    std::string TclBind::tcl_query(Tcl::object const &args)
    131154    {
    … …  
    151174    }
    152175
     176    /**
     177        @brief Callback: Used to send an Orxonox-command from Tcl to the CommandExecutor.
     178    */
    153179    void TclBind::tcl_execute(Tcl::object const &args)
    154180    {
    … …  
    162188    }
    163189
     190    /**
     191        @brief Console command, executes Tcl code. Can be used to bind Tcl-commands to a key, because native
     192        Tcl-commands can not be evaluated and are thus not supported by the key-binder.
     193    */
    164194    std::string TclBind::tcl(const std::string& tclcode)
    165195    {
    … …  
    182212    }
    183213
     214    /**
     215        @brief Console command and implementation of the Tcl-feature "bgerror" which is called if an error
     216        occurred in the background of a Tcl-script.
     217    */
    184218    void TclBind::bgerror(const std::string& error)
    185219    {
    … …  
    187221    }
    188222
     223    /**
     224        @brief Executes Tcl-code and returns the return-value.
     225        @param tclcode A string that contains Tcl-code
     226        @param error A pointer to an integer (or NULL) that is used to write an error-code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
     227        @return Returns the return-value of the executed code (or an empty string if there's no return-value)
     228    */
    189229    std::string TclBind::eval(const std::string& tclcode, int* error)
    190230    {
    … …  
    194234        try
    195235        {
     236            // execute the code
    196237            return TclBind::getInstance().interpreter_->eval(tclcode);
    197238        }

  • code/trunk/src/libraries/core/command/TclBind.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @defgroup Tcl Tcl
     31    @ingroup Command
     32*/
     33
     34/**
     35    @file
     36    @ingroup Command Tcl
     37    @brief Declaration of the TclBind class.
     38
     39    @anchor TclBindExample
     40
     41    orxonox::TclBind is a wrapper class for a Tcl interpreter. It is implemented as
     42    singleton, so it can be accessed by everyone, but all share the same static
     43    Tcl interpreter. If you need a Tcl interpreter at your own, see orxonox::TclThreadManager
     44    for more information.
     45
     46    orxonox::TclBind is used by orxonox::CommandExecutor to execute Tcl commands. It can
     47    also be used to execute Tcl commands from different sources, but note that they may
     48    interfer with the ingame console if used improperly. By no means execute blocking
     49    commands such as endless loops or the tcl command @c vwait. Use orxonox::TclThreadManager
     50    and execute these commands in a multithreaded Tcl interpreter instead.
     51
     52    TclBind also defines different callback functions to return commands from the
     53    Tcl interpreter back to Orxonox. Because of that it's possible to send a mixture
     54    of Orxonox- and Tcl-commands to TclBind::eval() and still get the desired behavior.
     55
     56    Example:
     57    @code
     58    TclBind::eval("puts \"Hello World\"");                              // calls the tcl command "puts", prints "Hello World" to the console
     59    TclBind::eval("log Hello World");                                   // calls the orxonox command "log", prints "Hello World" to the console
     60
     61    TclBind::eval("log [expr 1+1]");                                    // prints "2" to the console (which is the result of the tcl command "expr")
     62
     63    TclBind::eval("puts -nonewline Hello; log World");                  // prints "HelloWorld" to the console
     64
     65    TclBind::eval("for {set i 0} {$i < 10} {incr i} {log test: $i}");   // prints "test: 0", ..., "test: 9" to the console
     66    @endcode
     67
     68    Note that @c puts and @c log behave slightly different, even though both can print
     69    text to the console. @c puts needs quotation marks around multi-word output, while
     70    @c log doesn't. @c puts on the other hand supports the flag @c -nonewline.
     71
     72    TclBind::eval() can also be used to obtain the return-value of a Tcl command:
     73    @code
     74    std::string result = TclBind::eval("expr 1+1");                     // result == "2"
     75    @endcode
     76*/
     77
    2978#ifndef _TclBind_H__
    3079#define _TclBind_H__
    … …  
    3887namespace orxonox
    3988{
     89    /**
     90        @brief A wrapper class for a Tcl interpreter. Used to execute Tcl commands.
     91
     92        TclBind is used to execute Tcl commands, for example if sent to CommandExecutor::execute().
     93        It also defines different callbacks for Tcl, which allows to combine Orxonox-console-commands
     94        and Tcl-function without problems.
     95
     96        @see See @ref TclBindExample "TclBind.h" for more information and an example.
     97    */
    4098    class _CoreExport TclBind : public Singleton<TclBind>
    4199    {
    … …  
    49107
    50108            void setDataPath(const std::string& datapath);
    51             const std::string& getTclDataPath() const { return this->tclDataPath_; }
    52109            static std::string getTclLibraryPath();
     110            /// Returns the path to the Orxonox-specific Tcl-files.
     111            inline const std::string& getTclDataPath() const
     112                { return this->tclDataPath_; }
    53113
    54114            void initializeTclInterpreter();
    55115            static Tcl::interpreter* createTclInterpreter();
    56             Tcl::interpreter* getTclInterpreter() const { return this->interpreter_; }
     116            /// Returns the Tcl-interpreter
     117            inline Tcl::interpreter* getTclInterpreter() const
     118                { return this->interpreter_; }
    57119
    58120            static std::string tcl_query(Tcl::object const &args);
    … …  
    62124
    63125        private:
    64             TclBind(const TclBind& other);
     126            TclBind(const TclBind& other);      ///< Copy-constructor, not implemented
    65127
    66             Tcl::interpreter* interpreter_;
    67             std::string tclDataPath_;
    68             bool bSetTclDataPath_;
     128            Tcl::interpreter* interpreter_;     ///< The wrapped Tcl interpreter
     129            std::string tclDataPath_;           ///< The path to the directory that contains the Orxonox-specific Tcl-files
     130            bool bSetTclDataPath_;              ///< True if tclDataPath_ was defined (after a call to setDataPath())
    69131
    70             static TclBind* singletonPtr_s;
     132            static TclBind* singletonPtr_s;     ///< The singleton pointer
    71133    };
    72134}

  • code/trunk/src/libraries/core/command/TclThreadList.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command Tcl
     32    @brief Definition of TclThreadList.
     33*/
     34
    2935#ifndef _TclThreadList_H__
    3036#define _TclThreadList_H__
    … …  
    4046namespace orxonox
    4147{
     48    /**
     49        @brief A thread-safe implementation of a message queue, used by TclThreadManager.
     50    */
    4251    template <class T>
    4352    class TclThreadList
    … …  
    7180
    7281            /**
    73                 @brief Returns a reference to the mutex which might be useful if you want to iterate through the list (see @ref begin and @ref end).
     82                @brief Returns a reference to the mutex which might be useful if you want to iterate through the list (see @ref getList()).
    7483            */
    7584            inline boost::shared_mutex& getMutex() const

  • code/trunk/src/libraries/core/command/TclThreadManager.cc

    r7284 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @brief Implementation of TclThreadManager.
     32*/
    2833
    2934#include "TclThreadManager.h"
    … …  
    251256    void TclThreadManager::initialize(TclInterpreterBundle* bundle)
    252257    {
    253         const std::string& id_string = getConvertedValue<unsigned int, std::string>(bundle->id_);
     258        const std::string& id_string = multi_cast<std::string>(bundle->id_);
    254259
    255260        // Initialize the new interpreter
    … …  
    303308    /**
    304309        @brief Sends a command to the queue of a given Tcl-interpreter
    305         @param id The id of the target interpreter
     310        @param target_id The id of the target interpreter
    306311        @param command The command to be sent
    307312    */
    … …  
    326331        @brief This function can be called from Tcl to send a command to the queue of any interpreter.
    327332        @param target_id The id of the target thread
     333        @param args Contains the content of the command
    328334    */
    329335    void TclThreadManager::tcl_crossexecute(int target_id, const Tcl::object& args)
    … …  
    334340    /**
    335341        @brief Sends a command to the queue of a given Tcl-interpreter
    336         @param id The id of the target interpreter
     342        @param target_id The id of the target interpreter
    337343        @param command The command to be sent
    338344    */
    … …  
    347353    /**
    348354        @brief Sends a query to a given Tcl-interpreter and waits for the result
    349         @param id The id of the target interpreter
     355        @param target_id The id of the target interpreter
    350356        @param command The command to be sent
    351357        @return The result of the command
    … …  
    359365        @brief This function can be called from Tcl to send a query to the main thread.
    360366        @param source_id The id of the calling thread
     367        @param args Contains the content of the query
    361368
    362369        A query waits for the result of the command. This means, the calling thread will be blocked until
    … …  
    373380        @param source_id The id of the calling thread
    374381        @param target_id The id of the target thread
     382        @param args Contains the content of the query
    375383    */
    376384    std::string TclThreadManager::tcl_crossquery(int source_id, int target_id, const Tcl::object& args)
    … …  
    384392        @param target_id The id of the target thread
    385393        @param command The command to send as a query
    386         @param bUseCommandExecutor Only used if the target_id is 0 (which references the main interpreter). In this case it means if the command should be passed to the CommandExecutor (true) or to the main Tcl interpreter (false). This is true when called by tcl_query and false when called by tcl_crossquery.
     394        @param bUseCommandExecutor Only used if the target_id is 0 (which references the main interpreter). In this case it means if the command should be passed to the CommandExecutor (true) or to the main Tcl interpreter (false). This is true when called by tcl_query() and false when called by tcl_crossquery().
    387395    */
    388396    std::string TclThreadManager::_query(unsigned int source_id, unsigned int target_id, const std::string& command, bool bUseCommandExecutor)
    … …  
    400408            {
    401409                // This query would lead to a deadlock - return with an error
    402                 TclThreadManager::error("Error: Circular query (" + this->dumpList(source_bundle->queriers_.getList()) + ' ' + getConvertedValue<unsigned int, std::string>(source_bundle->id_) \
    403                             + " -> " + getConvertedValue<unsigned int, std::string>(target_bundle->id_) \
    404                             + "), couldn't query Tcl-interpreter with ID " + getConvertedValue<unsigned int, std::string>(target_bundle->id_) \
    405                             + " from other interpreter with ID " + getConvertedValue<unsigned int, std::string>(source_bundle->id_) + '.');
     410                TclThreadManager::error("Error: Circular query (" + this->dumpList(source_bundle->queriers_.getList()) + ' ' + multi_cast<std::string>(source_bundle->id_) \
     411                            + " -> " + multi_cast<std::string>(target_bundle->id_) \
     412                            + "), couldn't query Tcl-interpreter with ID " + multi_cast<std::string>(target_bundle->id_) \
     413                            + " from other interpreter with ID " + multi_cast<std::string>(source_bundle->id_) + '.');
    406414            }
    407415            else
    … …  
    469477                    // This happens if the main thread tries to query a busy interpreter
    470478                    // To avoid a lock of the main thread, we simply don't proceed with the query in this case
    471                     TclThreadManager::error("Error: Couldn't query Tcl-interpreter with ID " + getConvertedValue<unsigned int, std::string>(target_bundle->id_) + ", interpreter is busy right now.");
     479                    TclThreadManager::error("Error: Couldn't query Tcl-interpreter with ID " + multi_cast<std::string>(target_bundle->id_) + ", interpreter is busy right now.");
    472480                }
    473481            }
    … …  
    515523        else
    516524        {
    517             TclThreadManager::error("Error: No Tcl-interpreter with ID " + getConvertedValue<unsigned int, std::string>(id) + " existing.");
     525            TclThreadManager::error("Error: No Tcl-interpreter with ID " + multi_cast<std::string>(id) + " existing.");
    518526            return 0;
    519527        }
    … …  
    531539                output += ' ';
    532540
    533             output += getConvertedValue<unsigned int, std::string>(*it);
     541            output += multi_cast<std::string>(*it);
    534542        }
    535543        return output;
    … …  
    583591        if (cc != TCL_OK)
    584592        {
    585             TclThreadManager::error("Tcl error (" + action + ", ID " + getConvertedValue<unsigned int, std::string>(bundle->id_) + "): " + static_cast<std::string>(result));
     593            TclThreadManager::error("Tcl error (" + action + ", ID " + multi_cast<std::string>(bundle->id_) + "): " + static_cast<std::string>(result));
    586594            return "";
    587595        }

  • code/trunk/src/libraries/core/command/TclThreadManager.h

    r7284 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup Command Tcl
     32    @brief Declaration of TclThreadManager, used to create multithreaded Tcl interpreters.
     33*/
    2834
    2935#ifndef _TclThreadManager_H__

  • code/trunk/src/libraries/core/input/Button.cc

    r7284 r7401  
    176176                // evaluate the command
    177177                CommandEvaluation eval = CommandExecutor::evaluate(commandStr);
    178                 if (!eval.isValid() || eval.evaluateParams(true))
     178                if (!eval.isValid() || eval.evaluateArguments(true))
    179179                {
    180180                    parseError("Command evaluation of \"" + commandStr + "\"failed.", true);

  • code/trunk/src/libraries/core/input/InputCommands.cc

    r5781 r7401  
    5353        if (this->abs_ != 0.0f || this->rel_ != 0.0f)
    5454        {
    55             evaluation_.setEvaluatedParameter(paramIndex_, Vector2(abs_, rel_));
     55            evaluation_.setEvaluatedArgument(paramIndex_, Vector2(abs_, rel_));
    5656            // reset
    5757            rel_ = 0.0;

  • code/trunk/src/libraries/core/input/InputManager.cc

    r7284 r7401  
    140140        Creates the OIS::InputMananger, the keyboard, the mouse and
    141141        the joys ticks. If either of the first two fail, this method throws an exception.
    142     @param windowWidth
    143         The width of the render window
    144     @param windowHeight
    145         The height of the render window
    146142    */
    147143    void InputManager::loadDevices()

  • code/trunk/src/libraries/core/input/InputManager.h

    r6746 r7401  
    122122        @param name
    123123            Unique name of the InputState when referenced as string
     124        @param bAlwaysGetsInput
     125            InputState always gets the input when activated
     126        @param bTransparent
     127            InputState will not prevent underlaying state from receiving input
    124128        @param priority
    125129            Priority matters when multiple states are active. You can specify any

  • code/trunk/src/libraries/core/input/InputState.h

    r7284 r7401  
    128128        void resetExpiration() { bExpired_ = false; }
    129129
    130         //! Updates one specific device handler with #device#Updated
     130        //! Updates one specific device handler with deviceUpdated
    131131        void update(float dt, unsigned int device);
    132132        //! Updates all handlers with allDevicesUpdated

  • code/trunk/src/libraries/core/input/KeyBinder.cc

    r6536 r7401  
    495495    @brief
    496496        Event handler for the mouseMoved Event.
    497     @param e
    498         Mouse state information
     497    @param abs_
     498        The absolute position of the mouse
     499    @param rel_
     500        The relative movement of the mouse
     501    @param clippingSize
     502        Mouse screen area in pixels (usually 1024x1024)
    499503    */
    500504    void KeyBinder::mouseMoved(IntVector2 abs_, IntVector2 rel_, IntVector2 clippingSize)
    … …  
    551555    /**
    552556    @brief Event handler for the mouseScrolled Event.
    553     @param e Mouse state information
     557    @param abs The absolute position of the scroll wheel
     558    @param rel The relative movement of the scroll wheel
    554559    */
    555560    void KeyBinder::mouseScrolled(int abs, int rel)
Note: See TracChangeset for help on using the changeset viewer.